@woosh/meep-engine 3.9.0 → 3.11.0

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

@@ -0,0 +1,488 @@
+import { Av1EncodeContext } from "../av1/encode/Av1EncodeContext.js";
+import { clamp_sample } from "../color/clamp_sample.js";
+import { Av1Config, AuxiliaryTypeProperty, ColourInformation, ImageSpatialExtents, PixelInformation } from "../heif/ItemProperty.js";
+import { CP_BT_709, MC_BT_601, MC_IDENTITY, TC_SRGB } from "../av1/tables/av1_symbols.js";
+import { LINEAR_REFERENCE_NITS } from "../color/transfer_to_linear.js";
+import { apply_effort } from "../av1/encode/encode_effort.js";
+import { build_frame_header, build_sequence_header } from "../av1/encode/build_headers.js";
+import { colour_transform_init } from "../color/ColourTransform.js";
+import { encode_av1_still } from "../av1/encode/encode_av1_still.js";
+import { rgb_row_to_ycbcr } from "../color/rgb_row_to_ycbcr.js";
+import { transfer_row_from_linear } from "../color/linear_to_transfer.js";
+import { write_avif_file } from "../heif/write_avif_file.js";
+
+/**
+ * Chroma is coded at full resolution.
+ * @type {number}
+ */
+export const SUBSAMPLING_444 = 0;
+
+/**
+ * Chroma is coded at half resolution horizontally.
+ * @type {number}
+ */
+export const SUBSAMPLING_422 = 1;
+
+/**
+ * Chroma is coded at half resolution in both directions, which is what most AVIF files use.
+ * @type {number}
+ */
+export const SUBSAMPLING_420 = 2;
+
+/**
+ * Only luma is coded.
+ * @type {number}
+ */
+export const SUBSAMPLING_400 = 3;
+
+/**
+ * The auxiliary type an alpha plane declares itself with.
+ * @type {string}
+ */
+const ALPHA_AUX_TYPE = "urn:mpeg:mpegB:cicp:systems:auxiliary:alpha";
+
+/** @type {number} */
+const PRIMARY_ITEM_ID = 1;
+
+/** @type {number} */
+const ALPHA_ITEM_ID = 2;
+
+/**
+ * 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, options = {}, encoder = new Av1EncodeContext()) {
+    const width = image.width;
+    const height = image.height;
+
+    if (width < 1 || height < 1) {
+        throw new Error(`cannot encode a ${width}x${height} image`);
+    }
+
+    const bit_depth = options.bit_depth ?? 8;
+
+    if (bit_depth !== 8 && bit_depth !== 10 && bit_depth !== 12) {
+        throw new Error(`unsupported bit depth ${bit_depth}`);
+    }
+
+    const subsampling = options.subsampling ?? SUBSAMPLING_420;
+
+    const monochrome = subsampling === SUBSAMPLING_400 ? 1 : 0;
+    const sub_x = subsampling === SUBSAMPLING_420 || subsampling === SUBSAMPLING_422 ? 1 : 0;
+    const sub_y = subsampling === SUBSAMPLING_420 ? 1 : 0;
+
+    const matrix_coefficients = options.matrix_coefficients
+        ?? (subsampling === SUBSAMPLING_444 ? MC_IDENTITY : MC_BT_601);
+
+    const colour = {
+        width,
+        height,
+        bit_depth,
+        monochrome,
+        subsampling_x: sub_x,
+        subsampling_y: sub_y,
+        color_primaries: options.color_primaries ?? CP_BT_709,
+        transfer_characteristics: options.transfer_characteristics ?? TC_SRGB,
+        matrix_coefficients,
+        color_range: 1
+    };
+
+    // only when asked: a caller that configured the encode context itself should not have it
+    // quietly overwritten by a default it never named
+    if (options.effort !== undefined) {
+        apply_effort(encoder, options.effort);
+    }
+
+    if (options.decode_effort !== undefined) {
+        encoder.decode_effort = options.decode_effort;
+    }
+
+    const base_q_idx = quantizer_index(options.quality ?? 75);
+
+    const input_maximum = input_range(image.data, options.input_bit_depth);
+
+    const payload = encode_colour(encoder, image, colour, base_q_idx, options, input_maximum);
+
+    const items = [{
+        id: PRIMARY_ITEM_ID,
+        item_type: "av01",
+        item_name: "colour",
+        hidden: false,
+        properties: [
+            spatial_extents(width, height),
+            pixel_information(bit_depth, monochrome === 1 ? 1 : 3),
+            configuration(encoder, payload.configuration_obus, colour),
+            colour_information(colour)
+        ],
+        essential: [false, false, true, false],
+        data: payload.payload
+    }];
+
+    const references = [];
+
+    if (options.alpha === true) {
+        const alpha = encode_alpha(encoder, image, colour, base_q_idx, input_maximum);
+
+        items.push({
+            id: ALPHA_ITEM_ID,
+            item_type: "av01",
+            item_name: "alpha",
+            hidden: true,
+            properties: [
+                spatial_extents(width, height),
+                pixel_information(bit_depth, 1),
+                configuration(encoder, alpha.configuration_obus, { ...colour, monochrome: 1, subsampling_x: 1, subsampling_y: 1 }),
+                auxiliary_type()
+            ],
+            essential: [false, false, true, true],
+            data: alpha.payload
+        });
+
+        references.push({
+            from_item_id: ALPHA_ITEM_ID,
+            reference_type: "auxl",
+            to_item_ids: [PRIMARY_ITEM_ID]
+        });
+    }
+
+    return new Uint8Array(write_avif_file({
+        primary_item_id: PRIMARY_ITEM_ID,
+        items,
+        references
+    }));
+}
+
+/**
+ * Map a quality on the usual hundred point scale to a quantizer index.
+ *
+ * Quality one hundred is quantizer index zero, which in AV1 means lossless rather than merely very
+ * good: the transform becomes the exactly invertible one and nothing is discarded.
+ *
+ * @param {number} quality
+ * @returns {number}
+ */
+function quantizer_index(quality) {
+    const clamped = Math.min(Math.max(quality, 0), 100);
+
+    return Math.round((100 - clamped) * 255 / 100);
+}
+
+/**
+ * Convert the picture to planes and code it.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {object} image
+ * @param {object} colour
+ * @param {number} base_q_idx
+ * @param {object} options
+ * @param {number} input_maximum
+ * @returns {{configuration_obus: Uint8Array, payload: Uint8Array}}
+ */
+function encode_colour(ec, image, colour, base_q_idx, options, input_maximum) {
+    build_sequence_header(ec.sequence, colour);
+    build_frame_header(ec.frame, ec.sequence, { base_q_idx, restoration_unit_shift: ec.restoration_unit_shift });
+
+    const num_planes = colour.monochrome === 1 ? 1 : 3;
+
+    const padded_width = ec.frame.mi_cols * 4;
+    const padded_height = ec.frame.mi_rows * 4;
+
+    ec.resize_source(padded_width, padded_height, colour.subsampling_x, colour.subsampling_y, num_planes);
+
+    fill_source(ec, image, colour, options, padded_width, padded_height, input_maximum);
+
+    return encode_av1_still(ec);
+}
+
+/**
+ * Code the fourth channel as a monochrome image of its own, which is how AVIF carries alpha.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {object} image
+ * @param {object} colour
+ * @param {number} base_q_idx
+ * @param {number} input_maximum
+ * @returns {{configuration_obus: Uint8Array, payload: Uint8Array}}
+ */
+function encode_alpha(ec, image, colour, base_q_idx, input_maximum) {
+    build_sequence_header(ec.sequence, {
+        ...colour,
+        monochrome: 1,
+        subsampling_x: 1,
+        subsampling_y: 1,
+        matrix_coefficients: MC_BT_601
+    });
+
+    build_frame_header(ec.frame, ec.sequence, { base_q_idx, restoration_unit_shift: ec.restoration_unit_shift });
+
+    const padded_width = ec.frame.mi_cols * 4;
+    const padded_height = ec.frame.mi_rows * 4;
+
+    ec.resize_source(padded_width, padded_height, 1, 1, 1);
+
+    const maximum = (1 << colour.bit_depth) - 1;
+
+    const luma = ec.source[0];
+    const stride = ec.source_stride[0];
+
+    const scale = maximum / input_maximum;
+
+    for (let y = 0; y < padded_height; y++) {
+        const source_y = Math.min(y, image.height - 1);
+
+        for (let x = 0; x < padded_width; x++) {
+            const source_x = Math.min(x, image.width - 1);
+
+            const value = image.data[(source_y * image.width + source_x) * 4 + 3] * scale;
+
+            luma[y * stride + x] = Math.min(Math.max(Math.round(value), 0), maximum);
+        }
+    }
+
+    return encode_av1_still(ec);
+}
+
+/**
+ * The value a caller's samples reach at full scale.
+ *
+ * Integers are taken at their type's range unless the caller says otherwise; floats are taken as
+ * `0 .. 1`, which is also what linear input means once it is past the transfer function.
+ *
+ * @param {Uint8Array|Uint16Array|Float32Array} data
+ * @param {number} [declared] bit depth the caller declares its samples to be
+ * @returns {number}
+ */
+function input_range(data, declared) {
+    if (declared !== undefined) {
+        return (1 << declared) - 1;
+    }
+
+    if (data instanceof Uint8Array || data instanceof Uint8ClampedArray) {
+        return 255;
+    }
+
+    if (data instanceof Uint16Array) {
+        return 65535;
+    }
+
+    return 1;
+}
+
+/**
+ * Convert interleaved RGBA to the planes the encoder codes.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {object} image
+ * @param {object} colour
+ * @param {object} options
+ * @param {number} padded_width
+ * @param {number} padded_height
+ * @param {number} input_maximum
+ */
+function fill_source(ec, image, colour, options, padded_width, padded_height, input_maximum) {
+    const transform = ec.transform;
+
+    colour_transform_init(
+        transform,
+        colour.monochrome === 1 ? MC_BT_601 : colour.matrix_coefficients,
+        colour.color_primaries,
+        colour.color_range,
+        colour.bit_depth
+    );
+
+    const maximum = (1 << colour.bit_depth) - 1;
+
+    const width = image.width;
+    const height = image.height;
+
+    ec.resize_rows(padded_width);
+
+    const rgb = ec.rgb_row;
+    const cb = ec.cb_row;
+    const cr = ec.cr_row;
+
+    const sub_x = colour.subsampling_x;
+    const sub_y = colour.subsampling_y;
+
+    const chroma_width = (padded_width + sub_x) >> sub_x;
+
+    const chroma_accumulator_b = ec.chroma_blue;
+    const chroma_accumulator_r = ec.chroma_red;
+    const chroma_weight = ec.chroma_weight;
+
+    const linear = options.input_is_linear === true;
+
+    // linear input is carried in the caller's white and the colour module works in its own, so
+    // crossing between them is this one factor; signal input is just brought down to `0 .. 1`
+    const scale = linear
+        ? (options.linear_reference_nits ?? LINEAR_REFERENCE_NITS) / LINEAR_REFERENCE_NITS
+        : 1 / input_maximum;
+
+    const monochrome = colour.monochrome === 1;
+
+    for (let y = 0; y < padded_height; y++) {
+        const source_y = Math.min(y, height - 1);
+
+        for (let x = 0; x < padded_width; x++) {
+            const source_x = Math.min(x, width - 1);
+
+            const i = (source_y * width + source_x) * 4;
+
+            rgb[x * 3] = image.data[i] * scale;
+            rgb[x * 3 + 1] = image.data[i + 1] * scale;
+            rgb[x * 3 + 2] = image.data[i + 2] * scale;
+        }
+
+        if (linear) {
+            transfer_row_from_linear(colour.transfer_characteristics, rgb, padded_width);
+        }
+
+        rgb_row_to_ycbcr(transform, rgb, padded_width, ec.source[0], y * ec.source_stride[0], cb, cr);
+
+        if (monochrome) {
+            continue;
+        }
+
+        // chroma is averaged over the samples it will stand for, which is the least this can do and
+        // still be a resampling rather than a decimation
+        const chroma_row = y >> sub_y;
+
+        if ((y & sub_y) === 0) {
+            chroma_accumulator_b.fill(0, 0, chroma_width);
+            chroma_accumulator_r.fill(0, 0, chroma_width);
+            chroma_weight.fill(0, 0, chroma_width);
+        }
+
+        for (let x = 0; x < padded_width; x++) {
+            const column = x >> sub_x;
+
+            chroma_accumulator_b[column] += cb[x];
+            chroma_accumulator_r[column] += cr[x];
+            chroma_weight[column]++;
+        }
+
+        if ((y & sub_y) === sub_y) {
+            const stride_u = ec.source_stride[1];
+            const stride_v = ec.source_stride[2];
+
+            for (let column = 0; column < chroma_width; column++) {
+                const weight = chroma_weight[column];
+
+                if (weight === 0) {
+                    continue;
+                }
+
+                ec.source[1][chroma_row * stride_u + column] = clamp_sample(chroma_accumulator_b[column] / weight, maximum);
+                ec.source[2][chroma_row * stride_v + column] = clamp_sample(chroma_accumulator_r[column] / weight, maximum);
+            }
+        }
+    }
+}
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @returns {ImageSpatialExtents}
+ */
+function spatial_extents(width, height) {
+    const property = new ImageSpatialExtents();
+
+    property.width = width;
+    property.height = height;
+
+    return property;
+}
+
+/**
+ * @param {number} bit_depth
+ * @param {number} channels
+ * @returns {PixelInformation}
+ */
+function pixel_information(bit_depth, channels) {
+    const property = new PixelInformation();
+
+    property.bits_per_channel = new Uint8Array(channels).fill(bit_depth);
+
+    return property;
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {Uint8Array} config_obus
+ * @param {object} colour
+ * @returns {Av1Config}
+ */
+function configuration(ec, config_obus, colour) {
+    const property = new Av1Config();
+
+    property.version = 1;
+    property.seq_profile = ec.sequence.seq_profile;
+    property.seq_level_idx_0 = ec.sequence.seq_level_idx[0];
+    property.seq_tier_0 = 0;
+    property.high_bitdepth = colour.bit_depth > 8 ? 1 : 0;
+    property.twelve_bit = colour.bit_depth === 12 ? 1 : 0;
+    property.monochrome = colour.monochrome;
+    property.chroma_subsampling_x = colour.monochrome === 1 ? 1 : colour.subsampling_x;
+    property.chroma_subsampling_y = colour.monochrome === 1 ? 1 : colour.subsampling_y;
+    property.chroma_sample_position = 0;
+    property.initial_presentation_delay_minus_one = -1;
+    property.config_obus = config_obus;
+
+    return property;
+}
+
+/**
+ * @param {object} colour
+ * @returns {ColourInformation}
+ */
+function colour_information(colour) {
+    const property = new ColourInformation();
+
+    property.colour_type = "nclx";
+    property.colour_primaries = colour.color_primaries;
+    property.transfer_characteristics = colour.transfer_characteristics;
+    property.matrix_coefficients = colour.matrix_coefficients;
+    property.full_range_flag = colour.color_range;
+
+    return property;
+}
+
+/**
+ * @returns {AuxiliaryTypeProperty}
+ */
+function auxiliary_type() {
+    const property = new AuxiliaryTypeProperty();
+
+    property.aux_type = ALPHA_AUX_TYPE;
+
+    return property;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Encode a sampler as an AVIF file.
+ *
+ * A half float sampler is taken to hold linear light in the renderer's normalisation — `1.0` is
+ * SDR reference white, {@link SDR_WHITE_NITS} nits per ITU-R BT.2408 — and is coded through the PQ
+ * transfer function at twelve bits, which is what high dynamic range content needs. An eight bit
+ * sampler is coded as ordinary sRGB.
+ *
+ * {@link avif_to_sampler2d} is the exact inverse of this, in those same units: it names the same
+ * white to the decoder, so a sampler that goes through the pair comes back as itself.
+ *
+ * @param {Sampler2D} sampler
+ * @param {number} [quality] `0 .. 1`
+ * @param {object} [options]
+ * @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 sampler2d_to_avif(sampler: Sampler2D, quality?: number, options?: object, encoder?: Av1EncodeContext): Uint8Array;
+//# sourceMappingURL=sampler2d_to_avif.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sampler2d_to_avif.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/sampler2d_to_avif.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gEARW,MAAM,YACN,MAAM,+BAEJ,UAAU,CAmCtB"}

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

@@ -0,0 +1,108 @@
+import { MC_BT_709, TC_SMPTE_2084 } from "../av1/tables/av1_symbols.js";
+import { SDR_WHITE_NITS } from "../../../core/color/PQ/PQ_constants.js";
+import { SUBSAMPLING_420, SUBSAMPLING_422, encode_avif } from "./encode_avif.js";
+import { half_to_float_uint16 } from "../../../core/binary/half_to_float_uint16.js";
+
+/**
+ * Encode a sampler as an AVIF file.
+ *
+ * A half float sampler is taken to hold linear light in the renderer's normalisation — `1.0` is
+ * SDR reference white, {@link SDR_WHITE_NITS} nits per ITU-R BT.2408 — and is coded through the PQ
+ * transfer function at twelve bits, which is what high dynamic range content needs. An eight bit
+ * sampler is coded as ordinary sRGB.
+ *
+ * {@link avif_to_sampler2d} is the exact inverse of this, in those same units: it names the same
+ * white to the decoder, so a sampler that goes through the pair comes back as itself.
+ *
+ * @param {Sampler2D} sampler
+ * @param {number} [quality] `0 .. 1`
+ * @param {object} [options]
+ * @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 sampler2d_to_avif(sampler, quality = 0.75, options = {}, encoder = undefined) {
+    const width = sampler.width;
+    const height = sampler.height;
+
+    const item_size = sampler.itemSize;
+
+    const data = sampler.data;
+
+    const hdr = data instanceof Uint16Array;
+
+    const rgba = to_rgba(data, item_size, width, height, hdr);
+
+    if (hdr) {
+        return encode_avif({ data: rgba, width, height }, {
+            quality: Math.round(quality * 100),
+            bit_depth: 12,
+            subsampling: options.subsampling ?? SUBSAMPLING_422,
+            matrix_coefficients: MC_BT_709,
+            transfer_characteristics: TC_SMPTE_2084,
+            input_is_linear: true,
+            linear_reference_nits: SDR_WHITE_NITS,
+            alpha: options.alpha === true
+        }, encoder);
+    }
+
+    return encode_avif({ data: rgba, width, height }, {
+        quality: Math.round(quality * 100),
+        subsampling: options.subsampling ?? SUBSAMPLING_420,
+        alpha: options.alpha === true
+    }, encoder);
+}
+
+/**
+ * Expand a sampler's samples to interleaved RGBA of the kind the encoder takes.
+ *
+ * @param {Uint8Array|Uint8ClampedArray|Uint16Array|Float32Array|Float64Array} data
+ * @param {number} item_size
+ * @param {number} width
+ * @param {number} height
+ * @param {boolean} hdr whether the samples are half floats holding linear light
+ * @returns {Uint8ClampedArray|Float32Array}
+ */
+function to_rgba(data, item_size, width, height, hdr) {
+    const count = width * height;
+
+    if (hdr) {
+        const out = new Float32Array(count * 4);
+
+        for (let i = 0; i < count; i++) {
+            const source = i * item_size;
+            const destination = i * 4;
+
+            for (let c = 0; c < 3; c++) {
+                const value = c < item_size ? half_to_float_uint16(data[source + c]) : 0;
+
+                out[destination + c] = Math.max(value, 0);
+            }
+
+            out[destination + 3] = item_size > 3 ? Math.min(Math.max(half_to_float_uint16(data[source + 3]), 0), 1) : 1;
+        }
+
+        return out;
+    }
+
+    if (item_size === 4) {
+        return data;
+    }
+
+    const out = new Uint8ClampedArray(count * 4);
+
+    for (let i = 0; i < count; i++) {
+        const source = i * item_size;
+        const destination = i * 4;
+
+        for (let c = 0; c < 3; c++) {
+            out[destination + c] = c < item_size ? data[source + c] : 0;
+        }
+
+        out[destination + 3] = item_size > 3 ? data[source + 3] : 255;
+    }
+
+    return out;
+}