@woosh/meep-engine 3.9.0 → 3.11.0

package/src/avif/native/api/decode_avif.js

@@ -0,0 +1,111 @@
+import { AvifDecoder } from "./AvifDecoder.js";
+import { apply_transformations } from "./apply_transformations.js";
+import { convert_to_rgba } from "./convert_to_rgba.js";
+import { decode_image_item } from "./decode_image_item.js";
+import { find_item_property } from "../heif/find_item_property.js";
+import { find_item_references } from "../heif/find_item_references.js";
+import { find_items_referencing } from "../heif/find_items_referencing.js";
+import { parse_avif_file } from "../heif/parse_avif_file.js";
+
+/**
+ * The auxiliary type an alpha plane declares itself with.
+ * @type {string}
+ * @see ISO/IEC 23000-22 section 8.2 "Auxiliary image items"
+ */
+const ALPHA_AUX_TYPE = "urn:mpeg:mpegB:cicp:systems:auxiliary:alpha";
+
+/**
+ * Decode an AVIF file to interleaved RGBA.
+ *
+ * Synchronous by design: there is no worker, no WebAssembly and nothing to wait for, so a promise
+ * would only be ceremony. A caller that does not want to block should call this from a worker it
+ * controls, which is the arrangement meep already has for encoding.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @param {object} [options] see {@link convert_to_rgba}, plus `apply_transformations` to honour the
+ *   file's declared orientation — off by default, because the decoder this replaces left it to its
+ *   caller and a caller that already handles orientation would otherwise apply it twice
+ * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function decode_avif(buffer, options = {}, decoder = new AvifDecoder()) {
+    const bytes = buffer instanceof Uint8Array
+        ? buffer
+        : new Uint8Array(buffer);
+
+    const file = parse_avif_file(bytes);
+
+    const primary = file.items.get(file.primary_item_id);
+
+    if (primary === undefined) {
+        throw new Error(`the file's primary item ${file.primary_item_id} is not in its item table`);
+    }
+
+    const image = decoder.image;
+
+    image.alpha = null;
+    image.alpha_stride = 0;
+    image.alpha_premultiplied = 0;
+
+    decode_image_item(file, primary, decoder.colour_frame, decoder.colour_store, image);
+
+    decode_alpha(file, primary, decoder, image);
+
+    const converted = convert_to_rgba(decoder, image, options);
+
+    if (options.apply_transformations === true) {
+        return apply_transformations(file, primary, converted);
+    }
+
+    return converted;
+}
+
+/**
+ * Find and decode the alpha plane, if the file has one.
+ *
+ * AVIF codes alpha as a separate monochrome image that points at the picture it belongs to, rather
+ * than as a fourth plane, which is why this is a second decode rather than a fourth channel.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} primary
+ * @param {AvifDecoder} decoder
+ * @param {YuvImage} image
+ */
+function decode_alpha(file, primary, decoder, image) {
+    const candidates = find_items_referencing(file, primary.id, "auxl");
+
+    for (let i = 0; i < candidates.length; i++) {
+        const item = file.items.get(candidates[i]);
+
+        if (item === undefined) {
+            continue;
+        }
+
+        const auxC = find_item_property(file, item, "auxC");
+
+        if (auxC === null || auxC.aux_type !== ALPHA_AUX_TYPE) {
+            continue;
+        }
+
+        const alpha = decoder.alpha_image;
+
+        decode_image_item(file, item, decoder.alpha_frame, decoder.alpha_store, alpha);
+
+        if (alpha.width !== image.width || alpha.height !== image.height) {
+            throw new Error(`the alpha plane is ${alpha.width}x${alpha.height}, but the picture is ${image.width}x${image.height}`);
+        }
+
+        image.alpha = alpha.planes[0];
+        image.alpha_stride = alpha.stride[0];
+        image.alpha_bit_depth = alpha.bit_depth;
+        image.alpha_range = alpha.color_range;
+
+        // `prem` says the colour channels were multiplied by this alpha before coding
+        image.alpha_premultiplied = find_item_references(file, primary.id, "prem").includes(item.id) ? 1 : 0;
+
+        return;
+    }
+}

package/src/avif/native/api/decode_image_item.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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: AvifFile, item: AvifItem, ctx: Av1FrameContext, store: PlaneStore, image: YuvImage): void;
+//# sourceMappingURL=decode_image_item.d.ts.map

package/src/avif/native/api/decode_image_item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode_image_item.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/decode_image_item.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;GAeG;AACH,kIAuGC"}

package/src/avif/native/api/decode_image_item.js

@@ -0,0 +1,234 @@
+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
+            );
+        }
+    }
+}

package/src/avif/native/api/encode_avif.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Encode interleaved RGBA samples as an AVIF file.
+ *
+ * @param {object} image
+ * @param {Uint8Array|Uint8ClampedArray|Uint16Array|Float32Array} image.data interleaved RGBA
+ * @param {number} image.width
+ * @param {number} image.height
+ * @param {object} [options]
+ * @param {number} [options.quality] `0 .. 100`, where 100 is lossless
+ * @param {number} [options.effort] one of the `EFFORT_*` constants: how hard to search before
+ *   deciding, which trades encode time against size at the same quality. Left out, whatever the
+ *   encode context is already set to stands, which for a fresh one is `EFFORT_BALANCED`
+ * @param {number} [options.decode_effort] one of the `DECODE_*` constants: which in-loop filters
+ *   the file asks the reader to run, which trades *decode* time against size at the same fidelity.
+ *   The other axis to `effort`, and an unrelated one. Defaults to `DECODE_FAST`
+ * @param {number} [options.bit_depth] depth to code at: `8`, `10` or `12`
+ * @param {number} [options.input_bit_depth] depth of the samples handed in; ignored for float input
+ * @param {number} [options.subsampling] one of the `SUBSAMPLING_*` constants
+ * @param {boolean} [options.alpha] code the fourth channel as an alpha plane
+ * @param {number} [options.color_primaries]
+ * @param {number} [options.transfer_characteristics]
+ * @param {number} [options.matrix_coefficients]
+ * @param {boolean} [options.input_is_linear] the samples are linear light, to be encoded through
+ *   the transfer function rather than taken as signal values
+ * @param {number} [options.linear_reference_nits] luminance a linear `1.0` in the *input* stands
+ *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read with `input_is_linear`, and
+ *   the exact counterpart of {@link convert_to_rgba}'s option of the same name
+ * @param {Av1EncodeContext} [encoder] pass one back in to encode many images without reallocating
+ * @returns {Uint8Array}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function encode_avif(image: {
+    data: Uint8Array | Uint8ClampedArray | Uint16Array | Float32Array;
+    width: number;
+    height: number;
+}, options?: {
+    quality?: number;
+    effort?: number;
+    decode_effort?: number;
+    bit_depth?: number;
+    input_bit_depth?: number;
+    subsampling?: number;
+    alpha?: boolean;
+    color_primaries?: number;
+    transfer_characteristics?: number;
+    matrix_coefficients?: number;
+    input_is_linear?: boolean;
+    linear_reference_nits?: number;
+}, encoder?: Av1EncodeContext): Uint8Array;
+/**
+ * Chroma is coded at full resolution.
+ * @type {number}
+ */
+export const SUBSAMPLING_444: number;
+/**
+ * Chroma is coded at half resolution horizontally.
+ * @type {number}
+ */
+export const SUBSAMPLING_422: number;
+/**
+ * Chroma is coded at half resolution in both directions, which is what most AVIF files use.
+ * @type {number}
+ */
+export const SUBSAMPLING_420: number;
+/**
+ * Only luma is coded.
+ * @type {number}
+ */
+export const SUBSAMPLING_400: number;
+import { Av1EncodeContext } from "../av1/encode/Av1EncodeContext.js";
+//# sourceMappingURL=encode_avif.d.ts.map

package/src/avif/native/api/encode_avif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode_avif.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/encode_avif.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IA7BwE,IAAI,EAAjE,UAAU,GAAC,iBAAiB,GAAC,WAAW,GAAC,YAAY;IACvC,KAAK,EAAnB,MAAM;IACQ,MAAM,EAApB,MAAM;;IAEW,OAAO,GAAxB,MAAM;IACW,MAAM,GAAvB,MAAM;IAGW,aAAa,GAA9B,MAAM;IAGW,SAAS,GAA1B,MAAM;IACW,eAAe,GAAhC,MAAM;IACW,WAAW,GAA5B,MAAM;IACY,KAAK,GAAvB,OAAO;IACU,eAAe,GAAhC,MAAM;IACW,wBAAwB,GAAzC,MAAM;IACW,mBAAmB,GAApC,MAAM;IACY,eAAe,GAAjC,OAAO;IAEU,qBAAqB,GAAtC,MAAM;aAGN,gBAAgB,GACd,UAAU,CAwGtB;AAxKD;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,8BAFU,MAAM,CAEiB;iCAnCA,mCAAmC"}