@woosh/meep-engine 3.30.0 → 3.32.0

package/src/format/image/avif/api/decode_image_item.js

@@ -1,234 +1,322 @@
-import { decode_av1_still } from "../av1/decode/decode_av1_still.js";
-import { find_item_property } from "../heif/find_item_property.js";
-import { find_item_references } from "../heif/find_item_references.js";
-import { parse_image_grid } from "../heif/parse_image_grid.js";
-import { read_item_data } from "../heif/read_item_data.js";
-
-/**
- * Largest grid this decoder will assemble.
- *
- * The format allows 65536 tiles, which at any sane tile size is a demand for more memory than the
- * machine has. A file asking for one is far more likely to be malformed or hostile than real.
- * @type {number}
- */
-const MAX_GRID_TILES = 4096;
-
-/**
- * Decode one image item — a coded frame, or a grid of them — into a plane description.
- *
- * A single item does not copy: the image points straight at the frame context's output planes. A
- * grid has to copy, because the tiles are decoded one after another into the same context.
- *
- * @param {AvifFile} file
- * @param {AvifItem} item
- * @param {Av1FrameContext} ctx
- * @param {PlaneStore} store where a grid is assembled
- * @param {YuvImage} image filled in with the result
- * @see ISO/IEC 23008-12 section 6.6.2 "Image grid"
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function decode_image_item(file, item, ctx, store, image) {
-    if (item.item_type === "tmap") {
-        // a tone mapped item is a base picture plus a gain map, and its first reference is the base.
-        // Decoding that is what a decoder without gain map support is supposed to fall back to, and
-        // it is a correct picture rather than a degraded one — just not the brighter one.
-        const referenced = find_item_references(file, item.id, "dimg");
-
-        if (referenced.length === 0) {
-            throw new Error("a tone mapped item references no base image");
-        }
-
-        const base = file.items.get(referenced[0]);
-
-        if (base === undefined) {
-            throw new Error(`a tone mapped item references item ${referenced[0]}, which the file does not contain`);
-        }
-
-        decode_image_item(file, base, ctx, store, image);
-
-        return;
-    }
-
-    if (item.item_type === "av01") {
-        decode_single_item(file, item, ctx);
-
-        describe(ctx, image);
-
-        image.planes[0] = ctx.output_planes[0];
-        image.planes[1] = ctx.output_planes[1];
-        image.planes[2] = ctx.output_planes[2];
-
-        image.stride.set(ctx.output_stride);
-
-        apply_colour_property(file, item, image);
-
-        return;
-    }
-
-    if (item.item_type !== "grid") {
-        throw new Error(`item type ${item.item_type} cannot be decoded as an image`);
-    }
-
-    const grid = parse_image_grid(read_item_data(file, item));
-
-    const tiles = find_item_references(file, item.id, "dimg");
-
-    const expected = grid.rows * grid.columns;
-
-    if (tiles.length !== expected) {
-        throw new Error(`grid declares ${expected} tiles but references ${tiles.length}`);
-    }
-
-    if (expected > MAX_GRID_TILES) {
-        throw new Error(`grid of ${expected} tiles is beyond the ${MAX_GRID_TILES} this decoder assembles`);
-    }
-
-    let tile_width = 0;
-    let tile_height = 0;
-
-    for (let index = 0; index < tiles.length; index++) {
-        const tile = file.items.get(tiles[index]);
-
-        if (tile === undefined) {
-            throw new Error(`grid references item ${tiles[index]}, which the file does not contain`);
-        }
-
-        decode_single_item(file, tile, ctx);
-
-        if (index === 0) {
-            tile_width = ctx.output_width;
-            tile_height = ctx.output_height;
-
-            describe(ctx, image);
-
-            image.width = grid.output_width;
-            image.height = grid.output_height;
-
-            if (tile_width * grid.columns < grid.output_width || tile_height * grid.rows < grid.output_height) {
-                throw new Error("the grid's tiles do not cover the picture it declares");
-            }
-
-            store.resize(grid.output_width, grid.output_height, image.subsampling_x, image.subsampling_y, image.num_planes);
-        } else if (ctx.output_width !== tile_width || ctx.output_height !== tile_height) {
-            throw new Error("a grid's tiles must all be the same size");
-        }
-
-        copy_tile(
-            ctx,
-            store,
-            image,
-            (index % grid.columns) * tile_width,
-            Math.floor(index / grid.columns) * tile_height
-        );
-    }
-
-    image.planes[0] = store.planes[0];
-    image.planes[1] = store.planes[1];
-    image.planes[2] = store.planes[2];
-
-    image.stride.set(store.stride);
-
-    // the derived item carries the colour signalling for the picture as a whole
-    apply_colour_property(file, item, image);
-}
-
-/**
- * @param {AvifFile} file
- * @param {AvifItem} item
- * @param {Av1FrameContext} ctx
- */
-function decode_single_item(file, item, ctx) {
-    const av1C = find_item_property(file, item, "av1C");
-
-    if (av1C === null) {
-        throw new Error(`item ${item.id} has no av1C configuration`);
-    }
-
-    decode_av1_still(ctx, read_item_data(file, item), av1C.config_obus);
-}
-
-/**
- * @param {Av1FrameContext} ctx
- * @param {YuvImage} image
- */
-function describe(ctx, image) {
-    const sequence = ctx.sequence;
-
-    image.width = ctx.output_width;
-    image.height = ctx.output_height;
-    image.bit_depth = ctx.bit_depth;
-    image.subsampling_x = ctx.subsampling_x;
-    image.subsampling_y = ctx.subsampling_y;
-    image.num_planes = ctx.num_planes;
-
-    image.color_primaries = sequence.color_primaries;
-    image.transfer_characteristics = sequence.transfer_characteristics;
-    image.matrix_coefficients = sequence.matrix_coefficients;
-    image.color_range = sequence.color_range;
-}
-
-/**
- * Let a container level `colr` property override what the sequence header says.
- *
- * The two disagree more often than one would like — an encoder writes the stream once and the
- * container per item — and the container wins, because that is the level a file's colour management
- * is expected to be edited at.
- *
- * @param {AvifFile} file
- * @param {AvifItem} item
- * @param {YuvImage} image
- */
-function apply_colour_property(file, item, image) {
-    const colr = find_item_property(file, item, "colr");
-
-    if (colr === null || colr.colour_type !== "nclx") {
-        return;
-    }
-
-    image.color_primaries = colr.colour_primaries;
-    image.transfer_characteristics = colr.transfer_characteristics;
-    image.matrix_coefficients = colr.matrix_coefficients;
-    image.color_range = colr.full_range_flag;
-}
-
-/**
- * @param {Av1FrameContext} ctx
- * @param {PlaneStore} store
- * @param {YuvImage} image
- * @param {number} left in luma samples
- * @param {number} top
- */
-function copy_tile(ctx, store, image, left, top) {
-    for (let plane = 0; plane < image.num_planes; plane++) {
-        const sub_x = plane > 0 ? image.subsampling_x : 0;
-        const sub_y = plane > 0 ? image.subsampling_y : 0;
-
-        const source = ctx.output_planes[plane];
-        const source_stride = ctx.output_stride[plane];
-
-        const destination = store.planes[plane];
-        const destination_stride = store.stride[plane];
-
-        const destination_left = left >> sub_x;
-        const destination_top = top >> sub_y;
-
-        const plane_width = (store.width + sub_x) >> sub_x;
-        const plane_height = (store.height + sub_y) >> sub_y;
-
-        // a tile that hangs off the right or bottom edge is cropped, which is how a grid codes a
-        // picture whose size is not a multiple of the tile size
-        const columns = Math.min((ctx.output_width + sub_x) >> sub_x, plane_width - destination_left);
-        const rows = Math.min((ctx.output_height + sub_y) >> sub_y, plane_height - destination_top);
-
-        for (let y = 0; y < rows; y++) {
-            const from = y * source_stride;
-
-            destination.set(
-                source.subarray(from, from + columns),
-                (destination_top + y) * destination_stride + destination_left
-            );
-        }
-    }
-}
+import { decode_av1_still } from "../av1/decode/decode_av1_still.js";
+import { find_item_properties } from "../heif/find_item_properties.js";
+import { find_item_property } from "../heif/find_item_property.js";
+import { find_item_references } from "../heif/find_item_references.js";
+import { parse_image_grid } from "../heif/parse_image_grid.js";
+import { read_item_data } from "../heif/read_item_data.js";
+
+/**
+ * Largest grid this decoder will assemble.
+ *
+ * The format allows 65536 tiles, which at any sane tile size is a demand for more memory than the
+ * machine has. A file asking for one is far more likely to be malformed or hostile than real.
+ * @type {number}
+ */
+const MAX_GRID_TILES = 4096;
+
+/**
+ * How many tone mapped items may be followed before the chain is called a cycle.
+ *
+ * A real one is a single hop — a tone mapped item's first reference is its base picture — and the
+ * same four `read_item_data` allows its own construction-method chain is generous for both.
+ * @type {number}
+ */
+const MAX_TONE_MAP_DEPTH = 4;
+
+/**
+ * Decode one image item — a coded frame, or a grid of them — into a plane description.
+ *
+ * A single item does not copy: the image points straight at the frame context's output planes. A
+ * grid has to copy, because the tiles are decoded one after another into the same context.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {Av1FrameContext} ctx
+ * @param {PlaneStore} store where a grid is assembled
+ * @param {YuvImage} image filled in with the result
+ * @param {number} [depth] internal — how many tone-mapped items have been followed to get here
+ * @see ISO/IEC 23008-12 section 6.6.2 "Image grid"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function decode_image_item(file, item, ctx, store, image, depth = 0) {
+    if (depth > MAX_TONE_MAP_DEPTH) {
+        // The same guard `read_item_data` carries for the same shape, and for
+        // the same reason: the reference graph is untrusted input, so a file
+        // can point a tone mapped item at itself, or two of them at each other,
+        // in a handful of bytes of `iref` — and the recursion below would then
+        // run until the stack died. A RangeError is not an Error the callers
+        // distinguish, and this runs inside a decode worker.
+        throw new Error(`item ${item.id} is part of a tone mapped reference cycle`);
+    }
+
+    if (item.item_type === "tmap") {
+        // a tone mapped item is a base picture plus a gain map, and its first reference is the base.
+        // Decoding that is what a decoder without gain map support is supposed to fall back to, and
+        // it is a correct picture rather than a degraded one — just not the brighter one.
+        const referenced = find_item_references(file, item.id, "dimg");
+
+        if (referenced.length === 0) {
+            throw new Error("a tone mapped item references no base image");
+        }
+
+        const base = file.items.get(referenced[0]);
+
+        if (base === undefined) {
+            throw new Error(`a tone mapped item references item ${referenced[0]}, which the file does not contain`);
+        }
+
+        decode_image_item(file, base, ctx, store, image, depth + 1);
+
+        return;
+    }
+
+    if (item.item_type === "av01") {
+        decode_single_item(file, item, ctx);
+
+        describe(ctx, image);
+
+        image.planes[0] = ctx.output_planes[0];
+        image.planes[1] = ctx.output_planes[1];
+        image.planes[2] = ctx.output_planes[2];
+
+        image.stride.set(ctx.output_stride);
+
+        apply_colour_property(file, item, image);
+
+        return;
+    }
+
+    if (item.item_type !== "grid") {
+        throw new Error(`item type ${item.item_type} cannot be decoded as an image`);
+    }
+
+    const grid = parse_image_grid(read_item_data(file, item));
+
+    const tiles = find_item_references(file, item.id, "dimg");
+
+    const expected = grid.rows * grid.columns;
+
+    if (tiles.length !== expected) {
+        throw new Error(`grid declares ${expected} tiles but references ${tiles.length}`);
+    }
+
+    if (expected > MAX_GRID_TILES) {
+        throw new Error(`grid of ${expected} tiles is beyond the ${MAX_GRID_TILES} this decoder assembles`);
+    }
+
+    let tile_width = 0;
+    let tile_height = 0;
+
+    for (let index = 0; index < tiles.length; index++) {
+        const tile = file.items.get(tiles[index]);
+
+        if (tile === undefined) {
+            throw new Error(`grid references item ${tiles[index]}, which the file does not contain`);
+        }
+
+        decode_single_item(file, tile, ctx);
+
+        if (index === 0) {
+            tile_width = ctx.output_width;
+            tile_height = ctx.output_height;
+
+            describe(ctx, image);
+
+            image.width = grid.output_width;
+            image.height = grid.output_height;
+
+            if (tile_width * grid.columns < grid.output_width || tile_height * grid.rows < grid.output_height) {
+                throw new Error("the grid's tiles do not cover the picture it declares");
+            }
+
+            store.resize(grid.output_width, grid.output_height, image.subsampling_x, image.subsampling_y, image.num_planes);
+        } else if (ctx.output_width !== tile_width || ctx.output_height !== tile_height) {
+            throw new Error("a grid's tiles must all be the same size");
+        }
+
+        copy_tile(
+            ctx,
+            store,
+            image,
+            (index % grid.columns) * tile_width,
+            Math.floor(index / grid.columns) * tile_height
+        );
+    }
+
+    image.planes[0] = store.planes[0];
+    image.planes[1] = store.planes[1];
+    image.planes[2] = store.planes[2];
+
+    image.stride.set(store.stride);
+
+    // the derived item carries the colour signalling for the picture as a whole
+    apply_colour_property(file, item, image);
+}
+
+/**
+ * Property types this decoder honours, either by acting on them or by handing them to its caller.
+ * An ESSENTIAL property outside this set means the item cannot be decoded as its author intended.
+ *
+ * `irot` and `imir` are in it because they are handed on, which is honouring them. `a1lx` and
+ * `pasp` are informational — extent sizes and a pixel aspect ratio — so ignoring them still shows
+ * the right samples.
+ *
+ * Out of it, and therefore refused when essential: `clap`, a crop {@link apply_transformations}
+ * deliberately declines, and `a1op` / `lsel`, which choose an operating point and a layer of a
+ * layered stream — decoding the default instead is a different picture. So is any fourcc this
+ * decoder has never heard of.
+ *
+ * @type {string[]}
+ */
+const HONOURED_PROPERTY_TYPES = [
+    "ispe", "pixi", "av1C", "colr", "pasp", "irot", "imir", "auxC", "clli", "mdcv", "cclv", "a1lx"
+];
+
+/**
+ * Refuse an item that declares a property essential which this decoder cannot honour.
+ *
+ * HEIF requires a reader that does not understand an essential property to decline the item rather
+ * than decode it. `read_ipma` has always unpacked the bit into `property_essential`, and nothing
+ * read it: an unrecognised property was ignored, so an item
+ * carrying an essential crop, operating point or layer selection came back as the STORED picture
+ * presented as the intended one — the wrong framing, the wrong layer — with nothing to say so.
+ * That is the failure this module is written to avoid.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ */
+function reject_unhonoured_essential_properties(file, item) {
+    const indices = item.property_indices;
+
+    for (let i = 0; i < indices.length; i++) {
+        if (item.property_essential[i] !== true) {
+            continue;
+        }
+
+        const property = file.properties[indices[i] - 1];
+
+        if (property === undefined) {
+            // a stale association: find_item_property skips these, and so does this
+            continue;
+        }
+
+        if (HONOURED_PROPERTY_TYPES.indexOf(property.type) === -1) {
+            throw new Error(`item ${item.id} declares essential property '${property.type}', which this decoder does not honour`);
+        }
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {Av1FrameContext} ctx
+ */
+function decode_single_item(file, item, ctx) {
+    reject_unhonoured_essential_properties(file, item);
+
+    const av1C = find_item_property(file, item, "av1C");
+
+    if (av1C === null) {
+        throw new Error(`item ${item.id} has no av1C configuration`);
+    }
+
+    decode_av1_still(ctx, read_item_data(file, item), av1C.config_obus);
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {YuvImage} image
+ */
+function describe(ctx, image) {
+    const sequence = ctx.sequence;
+
+    image.width = ctx.output_width;
+    image.height = ctx.output_height;
+    image.bit_depth = ctx.bit_depth;
+    image.subsampling_x = ctx.subsampling_x;
+    image.subsampling_y = ctx.subsampling_y;
+    image.num_planes = ctx.num_planes;
+
+    image.color_primaries = sequence.color_primaries;
+    image.transfer_characteristics = sequence.transfer_characteristics;
+    image.matrix_coefficients = sequence.matrix_coefficients;
+    image.color_range = sequence.color_range;
+}
+
+/**
+ * Let a container level `colr` property override what the sequence header says.
+ *
+ * The two disagree more often than one would like — an encoder writes the stream once and the
+ * container per item — and the container wins, because that is the level a file's colour management
+ * is expected to be edited at.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {YuvImage} image
+ */
+function apply_colour_property(file, item, image) {
+    /*
+     Every colr, not the first one.
+
+     HEIF lets an item carry two — one nclx with the CICP codes and one rICC or prof with an ICC
+     profile — so a reader can use whichever it understands. This used to take the first of the
+     type and give up when it was not nclx, so an item that associated its ICC profile first lost
+     its container-level signalling and was converted with whatever the sequence header carried:
+     typically unspecified, which reads as BT.601. A BT.2020 PQ picture through the BT.601 matrix
+     is a visibly wrong hue in saturated regions.
+    */
+    const properties = find_item_properties(file, item, "colr");
+
+    const colr = properties.find(property => property.colour_type === "nclx");
+
+    if (colr === undefined) {
+        return;
+    }
+
+    image.color_primaries = colr.colour_primaries;
+    image.transfer_characteristics = colr.transfer_characteristics;
+    image.matrix_coefficients = colr.matrix_coefficients;
+    image.color_range = colr.full_range_flag;
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {PlaneStore} store
+ * @param {YuvImage} image
+ * @param {number} left in luma samples
+ * @param {number} top
+ */
+function copy_tile(ctx, store, image, left, top) {
+    for (let plane = 0; plane < image.num_planes; plane++) {
+        const sub_x = plane > 0 ? image.subsampling_x : 0;
+        const sub_y = plane > 0 ? image.subsampling_y : 0;
+
+        const source = ctx.output_planes[plane];
+        const source_stride = ctx.output_stride[plane];
+
+        const destination = store.planes[plane];
+        const destination_stride = store.stride[plane];
+
+        const destination_left = left >> sub_x;
+        const destination_top = top >> sub_y;
+
+        const plane_width = (store.width + sub_x) >> sub_x;
+        const plane_height = (store.height + sub_y) >> sub_y;
+
+        // a tile that hangs off the right or bottom edge is cropped, which is how a grid codes a
+        // picture whose size is not a multiple of the tile size
+        const columns = Math.min((ctx.output_width + sub_x) >> sub_x, plane_width - destination_left);
+        const rows = Math.min((ctx.output_height + sub_y) >> sub_y, plane_height - destination_top);
+
+        for (let y = 0; y < rows; y++) {
+            const from = y * source_stride;
+
+            destination.set(
+                source.subarray(from, from + columns),
+                (destination_top + y) * destination_stride + destination_left
+            );
+        }
+    }
+}