Lossy JPEG XL encoder (VarDCT)

encodeJXL({ quality }) encodes lossy JPEG XLs, quality mapping to the
Butteraugli distance like cjxl -q; without it images stay lossless. The
encoder follows libjxl's effort 3: XYB, 8x8 DCTs, the constant
quantization field of the distance with libjxl's global scale, LF
quantizer and dead zones, default matrices, block contexts and chroma
from luma, EPF iterations by distance. LF coefficients use the weighted
predictor with libjxl's fixed tree per channel, HF metadata the left
predictor, alpha (lossless) the gradient, in the global stream or the
pass groups.

The new entropy encoder (entropy-enc.ts) clusters contexts, writes the
context map and codes tokens with ANS (libjxl's count normalization and
histogram format; the alias table comes from the decoder's) or prefix
codes. Bit writer and image header moved out of fast-lossless.ts, the
lossless output is unchanged.

1920x1080 photo at d1: 240.8 kB at the PSNR of cjxl -e 3's 240.2 kB,
0.9 s. BD-rate vs cjxl -e 3: +0.8 to +2.9% (photos, screenshots); vs
-e 7: -1 to +10% on photos, +31-42% on screenshots. Every size, distance
and alpha case tried decodes in djxl within 1 of our decoder.

Also exports AVIFEncodeOptions, which index.ts was missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lfv41PqHEGbU7SLg5onpG1

Author: matmen

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.7.0
+
+### Features
+
+- `Image.encodeJXL({ quality })` encodes lossy JPEG XLs (VarDCT): `quality` (0-100) maps to the Butteraugli distance
+  like `cjxl -q` (90 is cjxl's default, 100 is lossless); without it, images are encoded losslessly as before. The
+  encoder follows libjxl's effort 3: XYB, 8x8 DCTs, libjxl's quantization, the weighted predictor for the LF, ANS,
+  the edge preserving filter. Its files are within about 1-3% of `cjxl -e 3` at the same PSNR; a 1920x1080 photo
+  takes about 0.9 s. Alpha is lossless.
+
+### Fixes
+
+- `AVIFEncodeOptions` is exported (with the new `JXLEncodeOptions`).
+
 ## 3.6.0
 
 ### Features

README.md

@@ -68,8 +68,8 @@ deno add jsr:@matmen/imagescript     # Deno (npm:imagescript works too)
   , lossless and lossy [WebPs](https://imagescript.matmen.dev/classes/Image.html#encodewebp) (lossy ones byte for
   byte like libwebp's cwebp)
   , [AVIFs](https://imagescript.matmen.dev/classes/Image.html#encodeavif) (lossy and lossless, with alpha)
-  , lossless [JPEG XLs](https://imagescript.matmen.dev/classes/Image.html#encodejxl) (byte for byte like libjxl's
-  `cjxl -e 1`)
+  , [JPEG XLs](https://imagescript.matmen.dev/classes/Image.html#encodejxl) (lossless byte for byte like libjxl's
+  `cjxl -e 1`, lossy about as small as `cjxl -e 3`)
   , [BMPs](https://imagescript.matmen.dev/classes/Image.html#encodebmp)
   , [QOIs](https://imagescript.matmen.dev/classes/Image.html#encodeqoi)
   , [Netpbm images](https://imagescript.matmen.dev/classes/Image.html#encodepnm) (PBM, PGM, PPM or PAM, whichever is
@@ -129,8 +129,8 @@ the text shaping is ported from [HarfBuzz](https://github.com/harfbuzz/harfbuzz)
 [Unicode Character Database](https://www.unicode.org/ucd/). The AV1 decoder is ported from
 [dav1d](https://code.videolan.org/videolan/dav1d), AVIFs are converted to RGB like
 [libavif](https://github.com/AOMediaCodec/libavif) does, the JPEG XL decoder is ported from
-[jxl-oxide](https://github.com/tirr-c/jxl-oxide) and [libjxl](https://github.com/libjxl/libjxl), the JPEG XL encoder
-from libjxl's fast lossless encoder, the AV1 encoder mirrors the decoder and uses libaom's symbol encoder.
+[jxl-oxide](https://github.com/tirr-c/jxl-oxide) and [libjxl](https://github.com/libjxl/libjxl), the JPEG XL encoders
+follow libjxl's fast lossless encoder and its effort 3, the AV1 encoder mirrors the decoder and uses libaom's symbol encoder.
 See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for their licenses.
 
 ---

THIRD_PARTY_NOTICES.md

@@ -290,8 +290,9 @@ DEALINGS IN THE SOFTWARE.
 ## libjxl, JPEG XL conformance
 
 The Modular decoding, the rendering pipeline, blending, the XYB conversion and the rendering of patches, splines and
-noise follow libjxl, the JPEG XL reference implementation, and the lossless encoder is ported from its fast lossless
-encoder; tests/jxl includes files of its conformance suite. JPEG XL
+noise follow libjxl, the JPEG XL reference implementation, the lossless encoder is ported from its fast lossless
+encoder, the lossy encoder follows its effort 3 (heuristics, quantization, the ANS histograms, fixed trees and
+clustering); tests/jxl includes files of its conformance suite. JPEG XL
 is covered by Google's patent grant for libjxl (the "Additional IP Rights Grant" in libjxl's PATENTS file).
 
 ```

src/codecs/jxl.ts

@@ -1,7 +1,8 @@
 /*!
  * JPEG XL (ISO/IEC 18181): bare codestreams and the container (ISO/IEC 18181-2: jxlc, jxlp boxes), the image header,
  * the frames up to the first one shown (with its orientation); see ./jxl/ for the decoder, ported from jxl-oxide and
- * libjxl (see THIRD_PARTY_NOTICES.md). Encoded images with Exif get the container (signature, ftyp, Exif, jxlc boxes)
+ * libjxl (see THIRD_PARTY_NOTICES.md); the encoders' codestreams, with Exif in the container (signature, ftyp, Exif, jxlc
+ * boxes)
  */
 import { MAX_PIXELS, checkPixels } from '../util/limits.ts';
 import { BitReader } from './jxl/bits.ts';
@@ -11,6 +12,7 @@ import { decodeFrame, DecoderState } from './jxl/frame.ts';
 import { ColorOutput } from './jxl/color.ts';
 import { ToneMapping } from './hdr.ts';
 import { encodeRGBA } from './jxl/fast-lossless.ts';
+import { encodeVarDCT } from './jxl/vardct-enc.ts';
 import { concat } from '../util/mem.ts';
 
 const CONTAINER = [0, 0, 0, 12, 0x4a, 0x58, 0x4c, 0x20, 0x0d, 0x0a, 0x87, 0x0a];
@@ -21,9 +23,12 @@ export function isJXL(d: Uint8Array): boolean {
     return d.length >= 12 && CONTAINER.every((v, i) => d[i] === v);
 }
 
-/** Encodes RGBA pixels as a lossless JPEG XL: the codestream, in the container if there is Exif data (a TIFF header and IFDs) */
-export function encode(rgba: Uint8Array, width: number, height: number, exif?: Uint8Array): Uint8Array {
-    const stream = encodeRGBA(rgba, width, height);
+/**
+ * Encodes RGBA pixels as a JPEG XL, lossless or lossy (with a Butteraugli distance above 0): the codestream, in the
+ * container if there is Exif data (a TIFF header and IFDs)
+ */
+export function encode(rgba: Uint8Array, width: number, height: number, exif?: Uint8Array, distance = 0): Uint8Array {
+    const stream = distance > 0 ? encodeVarDCT(rgba, width, height, { distance }) : encodeRGBA(rgba, width, height);
     if (!exif?.length) return stream;
     // (ftyp: brand jxl, minor version 0, compatible jxl; Exif: the offset of the TIFF header, 0, then the TIFF data)
     const jxl = [0x6a, 0x78, 0x6c, 0x20];

src/codecs/jxl/bit-writer.ts

@@ -0,0 +1,54 @@
+/*!
+ * The bit writer of the JPEG XL encoders, ported with the fast lossless encoder from libjxl
+ * (lib/jxl/enc_fast_lossless.cc). Copyright (c) the JPEG XL Project Authors, BSD-3-Clause License (see
+ * THIRD_PARTY_NOTICES.md)
+ */
+
+/** Bits in LSB first order, growing as needed */
+export class BitWriter {
+    data = new Uint8Array(256);
+    length = 0;
+    private buf = 0;
+    /** the bits in buf (less than 8 between writes) */
+    bits = 0;
+
+    /** writes the low count (up to 32) bits of v */
+    write(count: number, v: number): void {
+        if (count > 24) {
+            this.write(16, v & 0xffff);
+            this.write(count - 16, Math.floor(v / 65536));
+            return;
+        }
+        if (this.length + 4 > this.data.length) {
+            const data = new Uint8Array(this.data.length * 2);
+            data.set(this.data);
+            this.data = data;
+        }
+        this.buf |= v << this.bits;
+        this.bits += count;
+        while (this.bits >= 8) {
+            this.data[this.length++] = this.buf & 0xff;
+            this.buf >>>= 8;
+            this.bits -= 8;
+        }
+    }
+
+    zeroPadToByte(): void {
+        if (this.bits) this.write(8 - this.bits, 0);
+    }
+
+    /** the size in bits */
+    get size(): number {
+        return this.length * 8 + this.bits;
+    }
+
+    /** appends another writer's bits */
+    append(w: BitWriter): void {
+        for (let i = 0; i < w.length; i++) this.write(8, w.data[i]);
+        if (w.bits) this.write(w.bits, w.buf);
+    }
+
+    bytes(): Uint8Array {
+        return this.data.subarray(0, this.length);
+    }
+}