@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/heif/find_items_referencing.js

@@ -0,0 +1,36 @@
+/**
+ * Collect the item IDs that reference `to_item_id` with `reference_type`.
+ *
+ * The inverse of {@link find_item_references}, and the direction that matters for auxiliary
+ * images: an alpha item declares an `auxl` reference *to* the colour item, so finding the alpha
+ * plane for a picture means searching by target.
+ *
+ * @param {AvifFile} file
+ * @param {number} to_item_id
+ * @param {string} reference_type
+ * @returns {number[]}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function find_items_referencing(file, to_item_id, reference_type) {
+    const result = [];
+
+    for (let i = 0; i < file.references.length; i++) {
+        const reference = file.references[i];
+
+        if (reference.reference_type !== reference_type) {
+            continue;
+        }
+
+        for (let j = 0; j < reference.to_item_ids.length; j++) {
+            if (reference.to_item_ids[j] === to_item_id) {
+                result.push(reference.from_item_id);
+
+                break;
+            }
+        }
+    }
+
+    return result;
+}

package/src/avif/native/heif/parse_avif_file.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parse an AVIF file into its item model.
+ *
+ * Only structure is read: item payloads are located, not decoded, and their bytes are left in
+ * place. Nothing is copied out of `buffer`.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @returns {AvifFile}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_avif_file(buffer: ArrayBuffer | Uint8Array): AvifFile;
+import { AvifFile } from "./AvifFile.js";
+//# sourceMappingURL=parse_avif_file.d.ts.map

package/src/avif/native/heif/parse_avif_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_avif_file.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/parse_avif_file.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;AACH,wCANW,WAAW,GAAC,UAAU,GACpB,QAAQ,CAwCpB;yBA1D6D,eAAe"}

package/src/avif/native/heif/parse_avif_file.js

@@ -0,0 +1,383 @@
+import { for_each_box } from "../isobmff/for_each_box.js";
+import { ByteCursor } from "../isobmff/ByteCursor.js";
+import { full_box_flags, full_box_version, read_full_box_header } from "../isobmff/read_full_box_header.js";
+import { AvifFile, AvifItem, ItemExtent, ItemReference } from "./AvifFile.js";
+import { parse_item_property } from "./parse_item_property.js";
+
+/**
+ * Ceiling on counts read from the file before they are used to size anything. A real AVIF has a
+ * handful of items and properties; a count in the millions is corruption, and without a ceiling it
+ * becomes a multi-gigabyte allocation or a loop that never ends.
+ * @type {number}
+ */
+const MAX_ENTRIES = 65536;
+
+/**
+ * Parse an AVIF file into its item model.
+ *
+ * Only structure is read: item payloads are located, not decoded, and their bytes are left in
+ * place. Nothing is copied out of `buffer`.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @returns {AvifFile}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_avif_file(buffer) {
+    const file = new AvifFile();
+
+    const cursor = new ByteCursor().init(buffer);
+
+    file.bytes = cursor.bytes.subarray(0, cursor.end);
+
+    let saw_ftyp = false;
+    let saw_meta = false;
+
+    for_each_box(cursor, (header, box_cursor) => {
+        if (header.type === "ftyp") {
+            read_ftyp(file, box_cursor, header.end);
+
+            saw_ftyp = true;
+        } else if (header.type === "meta") {
+            read_meta(file, box_cursor, header.end);
+
+            saw_meta = true;
+        } else if (header.type === "moov") {
+            file.has_image_sequence = true;
+        }
+    });
+
+    if (!saw_ftyp) {
+        throw new Error("not an ISOBMFF file: no ftyp box");
+    }
+
+    if (!saw_meta) {
+        throw new Error("not an AVIF file: no meta box");
+    }
+
+    resolve_item_offsets(file);
+
+    return file;
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ftyp(file, cursor, end) {
+    file.major_brand = cursor.fourcc();
+    file.minor_version = cursor.u32();
+
+    while (cursor.position + 4 <= end) {
+        file.compatible_brands.push(cursor.fourcc());
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_meta(file, cursor, end) {
+    read_full_box_header(cursor);
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        switch (header.type) {
+            case "pitm":
+                read_pitm(file, box_cursor);
+                break;
+            case "iloc":
+                read_iloc(file, box_cursor);
+                break;
+            case "iinf":
+                read_iinf(file, box_cursor, header.end);
+                break;
+            case "iref":
+                read_iref(file, box_cursor, header.end);
+                break;
+            case "iprp":
+                read_iprp(file, box_cursor, header.end);
+                break;
+            case "idat":
+                file.item_data = box_cursor.view_bytes(header.payload_size);
+                break;
+            default:
+                break;
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_pitm(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    file.primary_item_id = version === 0 ? cursor.u16() : cursor.u32();
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {number} id
+ * @returns {AvifItem}
+ */
+function item_for_id(file, id) {
+    let item = file.items.get(id);
+
+    if (item === undefined) {
+        item = new AvifItem();
+        item.id = id;
+
+        file.items.set(id, item);
+    }
+
+    return item;
+}
+
+/**
+ * @param {number} count
+ * @param {string} what
+ */
+function check_count(count, what) {
+    if (count > MAX_ENTRIES) {
+        throw new Error(`${what} declares ${count} entries, beyond the ${MAX_ENTRIES} supported`);
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ */
+function read_iloc(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const sizes = cursor.u8();
+    const offset_size = (sizes >> 4) & 0xf;
+    const length_size = sizes & 0xf;
+
+    const base_and_index = cursor.u8();
+    const base_offset_size = (base_and_index >> 4) & 0xf;
+    const index_size = version === 1 || version === 2 ? base_and_index & 0xf : 0;
+
+    const item_count = version < 2 ? cursor.u16() : cursor.u32();
+
+    check_count(item_count, "iloc");
+
+    for (let i = 0; i < item_count; i++) {
+        const id = version < 2 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        if (version === 1 || version === 2) {
+            item.construction_method = cursor.u16() & 0xf;
+        }
+
+        item.data_reference_index = cursor.u16();
+        item.base_offset = cursor.uint_of_size(base_offset_size);
+
+        const extent_count = cursor.u16();
+
+        check_count(extent_count, "iloc extents");
+
+        for (let j = 0; j < extent_count; j++) {
+            if (index_size > 0) {
+                cursor.uint_of_size(index_size);
+            }
+
+            const extent = new ItemExtent();
+
+            extent.offset = cursor.uint_of_size(offset_size);
+            extent.length = cursor.uint_of_size(length_size);
+
+            item.extents.push(extent);
+        }
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.6 "Item information box"
+ */
+function read_iinf(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const entry_count = version === 0 ? cursor.u16() : cursor.u32();
+
+    check_count(entry_count, "iinf");
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type !== "infe") {
+            return;
+        }
+
+        read_infe(file, box_cursor, header.end);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_infe(file, cursor, end) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const flags = full_box_flags(version_and_flags);
+
+    if (version < 2) {
+        // versions 0 and 1 have no item_type field at all, so an item's nature can only be guessed
+        // from its name. No AVIF writer emits them; refusing is better than guessing.
+        throw new Error(`infe version ${version} is not supported by AVIF`);
+    }
+
+    const id = version === 2 ? cursor.u16() : cursor.u32();
+
+    const item = item_for_id(file, id);
+
+    cursor.u16();
+
+    item.item_type = cursor.fourcc();
+    item.item_name = cursor.utf8_string();
+    item.hidden = (flags & 1) !== 0;
+
+    if (item.item_type === "mime" && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    } else if (item.item_type === "uri " && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.12 "Item reference box"
+ */
+function read_iref(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        const reference = new ItemReference();
+
+        reference.reference_type = header.type;
+        reference.from_item_id = version === 0 ? box_cursor.u16() : box_cursor.u32();
+
+        const count = box_cursor.u16();
+
+        check_count(count, "iref");
+
+        for (let i = 0; i < count; i++) {
+            reference.to_item_ids.push(version === 0 ? box_cursor.u16() : box_cursor.u32());
+        }
+
+        file.references.push(reference);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 23008-12 section 9.3 "Item properties"
+ */
+function read_iprp(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type === "ipco") {
+            read_ipco(file, box_cursor, header.end);
+        } else if (header.type === "ipma") {
+            read_ipma(file, box_cursor);
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ipco(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        file.properties.push(parse_item_property(header.type, box_cursor, header.payload_size));
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_ipma(file, cursor) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const wide_indices = (full_box_flags(version_and_flags) & 1) !== 0;
+
+    const entry_count = cursor.u32();
+
+    check_count(entry_count, "ipma");
+
+    for (let i = 0; i < entry_count; i++) {
+        const id = version < 1 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        const association_count = cursor.u8();
+
+        for (let j = 0; j < association_count; j++) {
+            let essential;
+            let index;
+
+            if (wide_indices) {
+                const packed = cursor.u16();
+
+                essential = (packed & 0x8000) !== 0;
+                index = packed & 0x7fff;
+            } else {
+                const packed = cursor.u8();
+
+                essential = (packed & 0x80) !== 0;
+                index = packed & 0x7f;
+            }
+
+            // index 0 means "no property"; the specification allows it and it must not be treated
+            // as a reference to the first property
+            if (index === 0) {
+                continue;
+            }
+
+            item.property_indices.push(index);
+            item.property_essential.push(essential);
+        }
+    }
+}
+
+/**
+ * Fold `base_offset` into each extent, so consumers see absolute offsets and never have to know
+ * which of the three construction methods produced them.
+ *
+ * Method 1 offsets are relative to `idat` and method 2 to another item; both are left in their own
+ * space and resolved by {@link read_item_data}, which is the only place that can see the target.
+ *
+ * @param {AvifFile} file
+ */
+function resolve_item_offsets(file) {
+    for (const item of file.items.values()) {
+        for (let i = 0; i < item.extents.length; i++) {
+            item.extents[i].offset += item.base_offset;
+        }
+    }
+}

package/src/avif/native/heif/parse_image_grid.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parse a `grid` derived image's payload.
+ *
+ * This is not a box: it is the item's own data, laid out as version, flags, the tile counts and
+ * the assembled output size. Bit 0 of `flags` widens the output dimensions from 16 to 32 bits.
+ *
+ * The tile counts are stored minus one, so a grid always has at least one row and one column.
+ *
+ * @param {Uint8Array} payload
+ * @returns {ImageGrid}
+ * @see ISO/IEC 23008-12 section 6.6.2.3 "Image grid"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_image_grid(payload: Uint8Array): ImageGrid;
+import { ImageGrid } from "./AvifFile.js";
+//# sourceMappingURL=parse_image_grid.d.ts.map

package/src/avif/native/heif/parse_image_grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_image_grid.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/parse_image_grid.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,0CAPW,UAAU,GACR,SAAS,CAmCrB;0BA9CyB,eAAe"}

package/src/avif/native/heif/parse_image_grid.js

@@ -0,0 +1,48 @@
+import { ByteCursor } from "../isobmff/ByteCursor.js";
+import { ImageGrid } from "./AvifFile.js";
+
+/**
+ * Parse a `grid` derived image's payload.
+ *
+ * This is not a box: it is the item's own data, laid out as version, flags, the tile counts and
+ * the assembled output size. Bit 0 of `flags` widens the output dimensions from 16 to 32 bits.
+ *
+ * The tile counts are stored minus one, so a grid always has at least one row and one column.
+ *
+ * @param {Uint8Array} payload
+ * @returns {ImageGrid}
+ * @see ISO/IEC 23008-12 section 6.6.2.3 "Image grid"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_image_grid(payload) {
+    const cursor = new ByteCursor().init(payload);
+
+    const version = cursor.u8();
+
+    if (version !== 0) {
+        throw new Error(`grid version ${version} is not supported`);
+    }
+
+    const flags = cursor.u8();
+
+    const grid = new ImageGrid();
+
+    grid.rows = cursor.u8() + 1;
+    grid.columns = cursor.u8() + 1;
+
+    if ((flags & 1) !== 0) {
+        grid.output_width = cursor.u32();
+        grid.output_height = cursor.u32();
+    } else {
+        grid.output_width = cursor.u16();
+        grid.output_height = cursor.u16();
+    }
+
+    if (grid.output_width === 0 || grid.output_height === 0) {
+        throw new Error(`grid declares a ${grid.output_width}x${grid.output_height} output`);
+    }
+
+    return grid;
+}

package/src/avif/native/heif/parse_item_property.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parse one item property box into its struct.
+ *
+ * The cursor is positioned at the box payload; `payload_size` is its length. Unrecognised types
+ * are captured verbatim as {@link UnknownProperty} rather than dropped, because property indices
+ * in `ipma` are positional — silently discarding one would renumber every property after it.
+ *
+ * @param {string} type four character box type
+ * @param {ByteCursor} cursor positioned at the payload
+ * @param {number} payload_size
+ * @returns {object} one of the structs in `ItemProperty.js`
+ * @see ISO/IEC 23000-22 section 7.3 "AV1 Image Item Properties"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_item_property(type: string, cursor: ByteCursor, payload_size: number): object;
+//# sourceMappingURL=parse_item_property.d.ts.map

package/src/avif/native/heif/parse_item_property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_item_property.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/parse_item_property.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AACH,0CATW,MAAM,oCAEN,MAAM,GACJ,MAAM,CAoNlB"}