jpeg xl gain maps

Author: matmen

CHANGELOG.md

@@ -23,8 +23,9 @@
     at a quality or size, `{ gainMap: false }` leaves it out; `DecodeOptions.gainMap: false` doesn't read it.
   - Files with the gain map cut off (some chat apps and uploads keep the index but drop the map) and broken gain map
     metadata decode as before, without one.
-  - AVIFs carry gain maps too (a tone mapped item, AVIF 1.2): `Image.decode` reads them and `encodeAVIF()` writes
-    them (with the same `gainMap` option), so Ultra HDR JPEGs convert to HDR AVIFs a fraction of the size.
+  - AVIFs and JPEG XLs carry gain maps too (AVIF 1.2's tone mapped item, JPEG XL's jhgm box): `Image.decode` reads
+    them, `encodeAVIF()` and `encodeJXL()` write them (with the same `gainMap` option), so Ultra HDR JPEGs convert to
+    HDR AVIFs and JPEG XLs a fraction of the size.
   - iPhone JPEGs carry Apple's own kind of gain map (with its headroom in Apple's XMP or Exif maker note): it's read
     too, converted to the same parameters, and written as an Ultra HDR gain map.
 

README.md

@@ -71,7 +71,7 @@ await writeFile('output.png', await image.encode());
 | GIF, APNG (animations) | ✓ | ✓ |
 | BMP, QOI, TGA, Netpbm | ✓ | ✓ |
 | TIFF, ICO/CUR, Radiance HDR | ✓ | |
-| [HDR gain maps](https://imagescript.dev/classes/GainMap.html) (Ultra HDR and iPhone JPEGs, AVIF) | ✓ | ✓, kept through edits |
+| [HDR gain maps](https://imagescript.dev/classes/GainMap.html) (Ultra HDR and iPhone JPEGs, AVIF, JPEG XL) | ✓ | ✓, kept through edits |
 
 [Animations](https://imagescript.dev/classes/Animation.html) can be decoded from GIF, APNG, WebP and JPEG XL,
 and encoded as GIF, APNG or WebP, all at once or

src/codecs/jxl.ts

@@ -20,6 +20,7 @@ import { encodeModular } from './jxl/modular-lossless.ts';
 import { encodeVarDCT } from './jxl/vardct-enc.ts';
 import { concat } from '../util/mem.ts';
 import { srgbDecode, type Curve } from '../util/icc.ts';
+import { readISO, writeISO, type Params } from './gainmap.ts';
 
 const CONTAINER = [0, 0, 0, 12, 0x4a, 0x58, 0x4c, 0x20, 0x0d, 0x0a, 0x87, 0x0a];
 
@@ -33,15 +34,28 @@ export function isJXL(d: Uint8Array): boolean {
  * Encodes RGBA pixels as a JPEG XL, lossless or lossy (with a Butteraugli distance above 0, and an effort 0-2): the
  * codestream, in the container if there is Exif data (a TIFF header and IFDs); lossy with up to threads worker threads
  */
-export async function encode(rgba: Uint8Array, width: number, height: number, exif?: Uint8Array, distance = 0, effort = 1, threads = 1): Promise<Uint8Array> {
-    const stream = distance > 0 ? await encodeVarDCT(rgba, width, height, { distance, effort, threads })
-        : effort ? await encodeModular(rgba, width, height, threads) : encodeRGBA(rgba, width, height);
-    if (!exif?.length) return stream;
+export async function encode(rgba: Uint8Array, width: number, height: number, exif?: Uint8Array, distance = 0, effort = 1, threads = 1, gainMap?: GainMapInput): Promise<Uint8Array> {
+    const codestreamOf = (pixels: Uint8Array, w: number, h: number, d: number): Promise<Uint8Array> | Uint8Array => d > 0 ? encodeVarDCT(pixels, w, h, { distance: d, effort, threads })
+        : effort ? encodeModular(pixels, w, h, threads) : encodeRGBA(pixels, w, h);
+    const stream = await codestreamOf(rgba, width, height, distance);
+    if (!exif?.length && !gainMap) 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];
-    return concat([CONTAINER, ...box('ftyp', jxl, [0, 0, 0, 0], jxl), ...box('Exif', [0, 0, 0, 0], exif), ...box('jxlc', stream)]);
+    const boxes = [...box('ftyp', jxl, [0, 0, 0, 0], jxl)];
+    if (exif?.length) boxes.push(...box('Exif', [0, 0, 0, 0], exif));
+    if (gainMap) {
+        // jhgm (libjxl's JxlGainMapWriteBundle): version 0, the ISO 21496-1 metadata (its size, 16 bits), no color
+        // encoding or ICC profile (sizes 0: the alternate image's are the base image's), then the map's codestream
+        const metadata = writeISO(gainMap.params);
+        const map = await codestreamOf(gainMap.pixels, gainMap.width, gainMap.height, gainMap.distance);
+        boxes.push(...box('jhgm', [0, metadata.length >> 8, metadata.length & 255], metadata, [0, 0, 0, 0, 0], map));
+    }
+    return concat([CONTAINER, ...boxes, ...box('jxlc', stream)]);
 }
 
+/** A gain map to write: its RGBA pixels, parameters and the distance to encode it at (0: losslessly) */
+export interface GainMapInput { pixels: Uint8Array, width: number, height: number, params: Params, distance: number }
+
 // a box: its header and content
 const box = (type: string, ...content: ArrayLike<number>[]): ArrayLike<number>[] => {
     const size = 8 + content.reduce((n, c) => n + c.length, 0);
@@ -50,10 +64,9 @@ const box = (type: string, ...content: ArrayLike<number>[]): ArrayLike<number>[]
 
 const fourcc = (d: Uint8Array, o: number): string => String.fromCharCode(d[o], d[o + 1], d[o + 2], d[o + 3]);
 
-/** The codestream of a file: itself, or the container's jxlc box or jxlp boxes joined */
-function codestream(d: Uint8Array): Uint8Array {
-    if (d[0] === 0xff) return d;
-    const view = new DataView(d.buffer, d.byteOffset, d.byteLength), parts: Uint8Array[] = [];
+// the container's boxes: their types and contents
+function* boxesOf(d: Uint8Array): Generator<{ type: string, content: Uint8Array }> {
+    const view = new DataView(d.buffer, d.byteOffset, d.byteLength);
     for (let o = 0; o + 8 <= d.length;) {
         let size = view.getUint32(o), header = 8;
         const type = fourcc(d, o + 4);
@@ -63,11 +76,20 @@ function codestream(d: Uint8Array): Uint8Array {
             header = 16;
         } else if (size === 0) size = d.length - o;
         if (size < header || o + size > d.length) throw new Error(`JPEG XL: invalid ${type} box`);
-        if (type === 'jxlc') return d.subarray(o + header, o + size);
-        // (jxlp: a 4-byte index, then a part)
-        if (type === 'jxlp') parts.push(d.subarray(o + header + 4, o + size));
+        yield { type, content: d.subarray(o + header, o + size) };
         o += size;
     }
+}
+
+/** The codestream of a file: itself, or the container's jxlc box or jxlp boxes joined */
+function codestream(d: Uint8Array): Uint8Array {
+    if (d[0] === 0xff) return d;
+    const parts: Uint8Array[] = [];
+    for (const { type, content } of boxesOf(d)) {
+        if (type === 'jxlc') return content;
+        // (jxlp: a 4-byte index, then a part)
+        if (type === 'jxlp') parts.push(content.subarray(4));
+    }
     if (!parts.length) throw new Error('JPEG XL: no codestream');
     const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
     let at = 0;
@@ -165,8 +187,33 @@ export async function* frames(data: Uint8Array, maxPixels = MAX_PIXELS, toneMapp
     }
 }
 
-/** Decodes the first frame shown */
-export async function decode(data: Uint8Array, maxPixels = MAX_PIXELS, toneMapping: ToneMapping = 'reinhard', threads = 1): Promise<{ width: number, height: number, pixels: Uint8Array, orientation: number, icc?: Uint8Array, colorSpace?: ColorSpace }> {
-    for await (const frame of frames(data, maxPixels, toneMapping, threads)) return frame;
+/** Decodes the first frame shown (and the gain map of the jhgm box, if asked for and there is one that can be read) */
+export async function decode(data: Uint8Array, maxPixels = MAX_PIXELS, toneMapping: ToneMapping = 'reinhard', threads = 1, gainMap = false): Promise<{ width: number, height: number, pixels: Uint8Array, orientation: number, icc?: Uint8Array, colorSpace?: ColorSpace, gainMap?: { width: number, height: number, pixels: Uint8Array, params: Params } }> {
+    for await (const frame of frames(data, maxPixels, toneMapping, threads)) {
+        if (!gainMap || data[0] === 0xff) return frame;
+        return { ...frame, gainMap: await decodeGainMap(data, maxPixels).catch(() => undefined) };
+    }
     throw new Error('JPEG XL: no frame shown');
 }
+
+// the jhgm box's gain map (libjxl's JxlGainMapReadBundle): version 0, the ISO 21496-1 metadata (its size, 16 bits),
+// the alternate image's color encoding and ICC profile (their sizes, 8 and 32 bits), the map's codestream
+async function decodeGainMap(data: Uint8Array, maxPixels: number): Promise<{ width: number, height: number, pixels: Uint8Array, params: Params } | undefined> {
+    for (const { type, content: c } of boxesOf(data)) {
+        if (type !== 'jhgm') continue;
+        if (c.length < 3 || c[0] !== 0) return undefined;
+        const metadataSize = c[1] << 8 | c[2];
+        let o = 3 + metadataSize;
+        if (o + 1 > c.length) return undefined;
+        const metadata = c.subarray(3, o);
+        // (the metadata as ISO 21496-1 has it; or after a version byte, like AVIF's tmap item)
+        const params = readISO(metadata) ?? (metadata[0] === 0 ? readISO(metadata.subarray(1)) : null);
+        o += 1 + c[o];
+        if (!params || o + 4 > c.length) return undefined;
+        o += 4 + (c[o] << 24 >>> 0) + (c[o + 1] << 16 | c[o + 2] << 8 | c[o + 3]);
+        if (o >= c.length) return undefined;
+        // (its values as they are: no color management, no tone mapping)
+        for await (const { width, height, pixels } of frames(c.subarray(o), maxPixels, 'clamp', 1)) return { width, height, pixels, params };
+    }
+    return undefined;
+}

src/gainmap.ts

@@ -35,8 +35,8 @@ const perChannel = (value: number | number[], name: string): number[] => {
  * A gain map: a small image saying how much brighter each part of an image gets on an HDR display, as Ultra HDR
  * (JPEG-R) photos from phones carry it. HDR displays show the image boosted by it, the others the image as it is.
  *
- * {@link Image.decode} reads the gain maps of JPEGs and AVIFs into {@link Image.gainMap}, {@link Image.encodeJPEG} and
- * {@link Image.encodeAVIF} write them;
+ * {@link Image.decode} reads the gain maps of JPEGs, AVIFs and JPEG XLs into {@link Image.gainMap},
+ * {@link Image.encodeJPEG}, {@link Image.encodeAVIF} and {@link Image.encodeJXL} write them;
  * the map's pixels are only decoded once they're needed. The map covers the whole image, at any resolution (phones
  * write a quarter of the width and height). Its value `v` (0-255, per channel or one for all) boosts the linear
  * light of the image by `2^(gainMapMin + (gainMapMax - gainMapMin) * (v / 255)^(1 / gamma))`

src/image.ts

@@ -232,8 +232,8 @@ export interface DecodeOptions {
      */
     toneMapping?: ToneMapping;
     /**
-     * Whether to read the gain maps of JPEGs (Ultra HDR, JPEG-R, ISO 21496-1, Apple's) and AVIFs (tone mapped items)
-     * into {@link Image.gainMap}. A JPEG's map's pixels are only decoded when they're needed. Default: `true`
+     * Whether to read the gain maps of JPEGs (Ultra HDR, JPEG-R, ISO 21496-1, Apple's), AVIFs (tone mapped items) and
+     * JPEG XLs (jhgm boxes) into {@link Image.gainMap}. A JPEG's map's pixels are only decoded when they're needed. Default: `true`
      */
     gainMap?: boolean;
     /**
@@ -271,6 +271,12 @@ export interface JXLEncodeOptions {
     threads?: number;
     /** Metadata to include, see {@link Metadata} */
     metadata?: Metadata;
+    /**
+     * Whether to write the image's {@link Image.gainMap} (brighter on HDR displays: a jhgm box, like libjxl's), or how:
+     * `quality` (1-100 like `quality`, 100 lossless; default `90`) and `scale` (its size relative to the image, default
+     * its own). Default: `true`
+     */
+    gainMap?: boolean | { quality?: number, scale?: number };
 }
 
 /** Options of {@link Image.encodeAVIF} */
@@ -2488,16 +2494,14 @@ export class Image {
      * container, with the metadata as Exif
      * @param options See {@link JXLEncodeOptions}
      */
-    async encodeJXL({ quality, effort = 1, threads = defaultThreads(), metadata = {} }: JXLEncodeOptions = {}): Promise<Uint8Array> {
+    async encodeJXL({ quality, effort = 1, threads = defaultThreads(), metadata = {}, gainMap = true }: JXLEncodeOptions = {}): Promise<Uint8Array> {
         checkEffort(effort, 2);
         checkThreads(threads);
-        let distance = 0;
-        if (quality !== undefined) {
-            const q = checkQuality(quality);
-            // (cjxl's distance of a quality)
-            distance = q >= 100 ? 0 : q >= 30 ? 0.1 + (100 - q) * 0.09 : 53 / 3000 * q * q - 23 / 20 * q + 25;
-        }
-        return jxl.encode(this.__bytes__(), this.width, this.height, exifData(resolveMetadata(metadata)), distance, effort, threads);
+        // (cjxl's distance of a quality)
+        const distanceOf = (q: number): number => q >= 100 ? 0 : q >= 30 ? 0.1 + (100 - q) * 0.09 : 53 / 3000 * q * q - 23 / 20 * q + 25;
+        const distance = quality === undefined ? 0 : distanceOf(checkQuality(quality));
+        const map = this.__gain_map_pixels__(gainMap);
+        return jxl.encode(this.__bytes__(), this.width, this.height, exifData(resolveMetadata(metadata)), distance, effort, threads, map && { ...map, distance: distanceOf(map.quality) });
     }
 
     /**
@@ -2542,7 +2546,7 @@ export class Image {
                 return { width, height, pixels };
             };
             if (ImageType.isAVIF(dataView)) return avif.decode(data, maxPixels, toneMapping, threads, gainMap);
-            if (ImageType.isJXL(dataView)) return jxl.decode(data, maxPixels, toneMapping, threads);
+            if (ImageType.isJXL(dataView)) return jxl.decode(data, maxPixels, toneMapping, threads, gainMap);
             if (ImageType.isBMP(dataView)) return bitmap(bmp.decode(data, maxPixels));
             if (ImageType.isICO(dataView)) return bitmap(ico.decode(data, maxPixels));
             if (ImageType.isQOI(dataView)) return qoi.decode(data, maxPixels);

tests/gainmap.js

@@ -245,6 +245,26 @@ const meanValue = (image, left, top, right, bottom) => {
 		if (scaled.gainMap.width !== 128 || scaled.gainMap.height !== 96) panic(`AVIF ${name}: scaled map ${scaled.gainMap.width}x${scaled.gainMap.height}`);
 	}
 
+	// JPEG XL: the gain map in a jhgm box (lossy and lossless), the image as without one
+	for (const [name, image] of [['single-channel', single], ['multi-channel', multi]]) {
+		for (const options of [{quality: 80}, {}]) {
+			const jxl = await image.encodeJXL(options);
+			const back = await Image.decode(jxl);
+			const map = back.gainMap;
+			if (!map || map.channels !== image.gainMap.channels || map.width !== image.gainMap.width || !close(map.gainMapMax, image.gainMap.gainMapMax) || !close(map.gainMapMin, image.gainMap.gainMapMin) || Math.abs(map.hdrCapacityMax - image.gainMap.hdrCapacityMax) > 1e-6)
+				panic(`JXL ${name} ${JSON.stringify(options)}: ${map ? `${map.channels} channels, ${map.width}, ${map.gainMapMax}` : 'no gain map'}`);
+			let sum = 0;
+			const a = map.image.bitmap, b = image.gainMap.image.bitmap;
+			for (let i = 0; i < a.length; i += 4) sum += Math.abs(a[i] - b[i]);
+			if (sum / (a.length / 4) > 1) panic(`JXL ${name}: map off by ${sum / (a.length / 4)}`);
+			const plain = await image.encodeJXL({...options, gainMap: false});
+			if ((await Image.decode(plain)).gainMap !== null || !same(back, await Image.decode(plain))) panic(`JXL ${name}: the base differs with the map, or gainMap: false wrote it`);
+			if ((await Image.decode(jxl, {gainMap: false})).gainMap !== null) panic(`JXL ${name}: gainMap: false still read the map`);
+		}
+		const lossless = await Image.decode(await image.encodeJXL({gainMap: {quality: 100}}));
+		if (!same(lossless.gainMap.image, image.gainMap.image)) panic(`JXL ${name}: a lossless map changed`);
+	}
+
 	// invalid arguments throw before the image or its map changes
 	for (const [name, call] of [['blur', i => i.blur('5')], ['fill', i => i.fill('red')], ['cover', i => i.cover(-1, 10)]]) {
 		const image = single.clone();