supervision 0.2.4 → 0.2.6

package/dist/mask-preparation.worker.js

@@ -376,6 +376,68 @@
         KeypointMarkerShape["Circle"] = "circle";
         KeypointMarkerShape["Cross"] = "cross";
     })(KeypointMarkerShape || (KeypointMarkerShape = {}));
+
+    /**
+     * What the stored values of a depth map measure.
+     *
+     * Every kind stores 0 where there is no depth.
+     */
+    const DepthMapKind = {
+        /** Stereo disparity in pixels of the map. Larger is nearer. */
+        DisparityPx: "disparity_px",
+        /** Metric depth along the optical axis in metres. Smaller is nearer. */
+        DepthM: "depth_m",
+        /**
+         * Unitless inverse depth up to an unknown scale and shift, as monocular
+         * models produce it. Larger is nearer; it has no metric depth.
+         */
+        RelativeInverse: "relative_inverse",
+    };
+    /**
+     * The quantity a depth renderer colours.
+     *
+     * Disparity is inverse depth, so it spends colour on near detail the way
+     * stereo measures it. Either way the nearest end of the range is the warm or
+     * bright end of the colour table.
+     */
+    const DepthQuantity = {
+        Disparity: "disparity",
+        Depth: "depth",
+    };
+    const DepthColormap = {
+        Turbo: "turbo",
+        Viridis: "viridis",
+        Cividis: "cividis",
+        Inferno: "inferno",
+        Magma: "magma",
+        Grayscale: "grayscale",
+    };
+    /** How a depth map is sampled where one map pixel does not cover one media pixel. */
+    const DepthSampling = {
+        /** Nearest when the map is at least media size, edge-aware otherwise. */
+        Auto: "auto",
+        Nearest: "nearest",
+        /**
+         * Bilinear over valid neighbours only, falling back to the nearest one
+         * across a depth edge, so objects never bleed into the background.
+         */
+        EdgeAware: "edge-aware",
+    };
+    /**
+     * The luma range a depth preview video's codes are written in.
+     *
+     * TV range is what browsers' hardware decoders return as written; a decoder
+     * may squeeze full range into TV range or move codes converting it to RGB.
+     */
+    const DepthPreviewLevels = {
+        /** Every code from 0 to 255; the top code is 255. */
+        Full: "full",
+        /** Limited range: black is 16 and the top code is 235. */
+        Tv: "tv",
+    };
+    new Set(Object.values(DepthColormap));
+    new Set(Object.values(DepthQuantity));
+    new Set(Object.values(DepthSampling));
     function rasterizePolygonToMask(points, dimensions) {
         const data = createEmptyMask(dimensions);
         if (points.length < 3) {
@@ -429,8 +491,10 @@
         if (instructions.length === 0) {
             return undefined;
         }
-        const maskWidth = Math.max(...instructions.map(({ mask }) => mask.width));
-        const maskHeight = Math.max(...instructions.map(({ mask }) => mask.height));
+        /* Pixel-grid dimensions use integer parts throughout allocation and RLE
+           traversal. */
+        const maskWidth = Math.floor(Math.max(...instructions.map(({ mask }) => mask.width)));
+        const maskHeight = Math.floor(Math.max(...instructions.map(({ mask }) => mask.height)));
         const width = resolveRasterWidth(maskWidth, options.maxWidth);
         const height = width === maskWidth
             ? maskHeight
@@ -482,8 +546,8 @@
      */
     function writeMaskRuns(data, frameWidth, mask, detectionMaskId) {
         const counts = decodeCompressedRleCounts(mask.counts);
-        const maskWidth = mask.width;
-        const maskHeight = mask.height;
+        const maskWidth = Math.floor(mask.width);
+        const maskHeight = Math.floor(mask.height);
         let maskOffset = 0;
         for (let index = 0; index < counts.length; index += 1) {
             const runLength = counts[index] ?? 0;
@@ -517,9 +581,10 @@
      */
     function writeScaledMaskRuns(data, axes, mask, detectionMaskId) {
         const counts = decodeCompressedRleCounts(mask.counts);
-        const maskWidth = mask.width;
-        const maskHeight = mask.height;
+        const maskWidth = Math.floor(mask.width);
+        const maskHeight = Math.floor(mask.height);
         let maskOffset = 0;
+        const stride = axes.stride;
         for (let index = 0; index < counts.length; index += 1) {
             const runLength = counts[index] ?? 0;
             if (index % 2 === 0 || runLength <= 0) {
@@ -528,17 +593,30 @@
             }
             let x = Math.floor(maskOffset / maskHeight);
             let y = maskOffset - x * maskHeight;
-            let column = axes.columns[x];
-            for (let step = 0; step < runLength; step += 1) {
-                if (x >= maskWidth) {
-                    break;
+            let remaining = runLength;
+            /* A run walks down one column and wraps into the next, so it splits into
+               column-sized segments. Within a segment the destination offset only ever
+               steps by the row pitch or stays put: createMaskAxisMap builds
+               `rows[i] = min(height - 1, floor(i * scale)) * width` with scale <= 1, so
+               consecutive entries differ by exactly 0 or exactly `width`. Walking the
+               destination directly therefore touches the same bytes the per-pixel loop
+               touched, and drops the bounds test, the wrap test and one typed-array
+               load from every source pixel. Where the scale collapses several source
+               rows onto one destination row, this writes that byte once instead of
+               once per source row. */
+            while (remaining > 0 && x < maskWidth) {
+                const span = Math.min(remaining, maskHeight - y);
+                const column = axes.columns[x];
+                const first = axes.rows[y];
+                const last = axes.rows[y + span - 1];
+                for (let offset = first; offset <= last; offset += stride) {
+                    data[offset + column] = detectionMaskId;
                 }
-                data[axes.rows[y] + column] = detectionMaskId;
-                y += 1;
+                remaining -= span;
+                y += span;
                 if (y === maskHeight) {
                     y = 0;
                     x += 1;
-                    column = axes.columns[x];
                 }
             }
             maskOffset += runLength;
@@ -550,22 +628,19 @@
             : maskWidth;
     }
     /**
-     * A stroke is measured in texels of the raster it is drawn on, so a coarser
-     * raster measures it in coarser texels. A stroke of a texel or more keeps at
-     * least one, the thinnest line the shader can draw; a narrower one keeps its
-     * own width, which the shader draws as an inner boundary at any scale. The
-     * ceiling is the widest neighbourhood the shaders scan, so a wider stroke would
-     * be drawn at the ceiling anyway and every layer drawing the same annotation
-     * has to arrive at the same width.
+     * Converts a source-grid stroke width into raster texels. Fractional widths
+     * let coverage shaders draw a border within a texel. The ceiling bounds the
+     * neighbourhood the shaders scan.
      */
     function resolveIdMaskStrokeTexels(strokeWidth, maskWidth, rasterWidth) {
         const scale = maskWidth > 0 ? rasterWidth / maskWidth : 1;
-        return Math.min(Math.max(strokeWidth * scale, Math.min(strokeWidth, 1)), MAX_ID_MASK_STROKE_WIDTH);
+        return Math.min(strokeWidth * scale, MAX_ID_MASK_STROKE_WIDTH);
     }
     function createScaledMaskAxes(frame) {
         return {
             columns: createMaskAxisMap(frame.maskWidth, frame.width, 1),
             rows: createMaskAxisMap(frame.maskHeight, frame.height, frame.width),
+            stride: frame.width,
         };
     }
     /** Rows hold their destination offset, so writing a run is two lookups. */
@@ -595,6 +670,8 @@
         palette[offset + 2] = (color & 0xff) / 255;
         palette[offset + 3] = Math.max(0, Math.min(alpha, 1));
     }
+    new Set(Object.values(DepthPreviewLevels));
+    new Set(Object.values(DepthMapKind));
 
     var MediaRendererFit;
     (function (MediaRendererFit) {
@@ -1106,6 +1183,520 @@
         MaskPreparationWorkerMessageType["Prepare"] = "prepare";
     })(MaskPreparationWorkerMessageType || (MaskPreparationWorkerMessageType = {}));
 
+    /**
+     * Messages between the depth source and the render-preparation worker, which
+     * decodes depth and confidence PNGs, and copies decoded preview frames' luma,
+     * off the main thread. Internal: the worker script is a deployment asset, and
+     * its protocol is not public.
+     */
+    var DepthPreparationWorkerMessageType;
+    (function (DepthPreparationWorkerMessageType) {
+        DepthPreparationWorkerMessageType["Decode"] = "depth-decode";
+        DepthPreparationWorkerMessageType["Complete"] = "depth-decode-complete";
+        DepthPreparationWorkerMessageType["Error"] = "depth-decode-error";
+        DepthPreparationWorkerMessageType["PreviewLuma"] = "depth-preview-luma";
+        DepthPreparationWorkerMessageType["PreviewLumaComplete"] = "depth-preview-luma-complete";
+    })(DepthPreparationWorkerMessageType || (DepthPreparationWorkerMessageType = {}));
+
+    /*
+     * Grayscale PNG decoding for depth maps and their confidence planes.
+     *
+     * Every image path a browser offers (<img>, createImageBitmap, ImageDecoder,
+     * canvas) hands back 8 bits per channel, so a 16-bit depth PNG is decoded
+     * here: the browser's own zlib inflates the IDAT stream, and the row filters
+     * are undone in JavaScript.
+     *
+     * This module imports nothing, so the render-preparation worker, the main
+     * thread and the depth benchmark all run the same code.
+     */
+    const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+    const COLOR_TYPE_GRAY = 0;
+    /** 16384 x 16384, beyond any GPU texture; a header claiming more is refused. */
+    const MAX_PNG_PIXELS = 16_384 * 16_384;
+    async function decodePng16(bytes, options = {}) {
+        const header = readPngHeader(bytes, 16);
+        const rowBytes = header.width * 2 + 1;
+        const raw = await (options.inflate ?? inflateWithDecompressionStream)(header.idat, rowBytes * header.height);
+        const values = new Uint16Array(header.width * header.height);
+        checkInflatedLength(raw, rowBytes * header.height);
+        unfilterGray16(raw, header.width, header.height, values);
+        return {
+            height: header.height,
+            paddedUpload: options.padRowsForWebGl && header.width % 2 === 1
+                ? padRows(values, header.width, header.height)
+                : undefined,
+            values,
+            width: header.width,
+        };
+    }
+    async function decodePng8Gray(bytes, options = {}) {
+        const header = readPngHeader(bytes, 8);
+        const rowBytes = header.width + 1;
+        const raw = await (options.inflate ?? inflateWithDecompressionStream)(header.idat, rowBytes * header.height);
+        const values = new Uint8Array(header.width * header.height);
+        checkInflatedLength(raw, rowBytes * header.height);
+        unfilterGray8(raw, header.width, header.height, values);
+        return { height: header.height, values, width: header.width };
+    }
+    /**
+     * Inflates with the platform's `DecompressionStream("deflate")` (zlib
+     * framing, which is what PNG uses) straight into one buffer of the expected
+     * size, so no second copy joins the output chunks.
+     */
+    async function inflateWithDecompressionStream(chunks, byteLength) {
+        const stream = new DecompressionStream("deflate");
+        const writer = stream.writable.getWriter();
+        const reader = stream.readable.getReader();
+        // Writers split IDAT into many small chunks (libpng's default is 8 KiB).
+        // One write of the joined stream costs a copy of the compressed bytes and
+        // saves a stream round trip per chunk.
+        const zlib = chunks.length === 1 ? chunks[0] : joinChunks(chunks);
+        const writing = (async () => {
+            await writer.write(zlib);
+            await writer.close();
+        })();
+        const output = new Uint8Array(byteLength);
+        let offset = 0;
+        // A corrupt stream rejects both sides; the reader's error is the one thrown.
+        writing.catch(() => undefined);
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (offset + value.byteLength > byteLength) {
+                    throw new RangeError("PNG image data is longer than its header says.");
+                }
+                output.set(value, offset);
+                offset += value.byteLength;
+            }
+            await writing;
+        }
+        catch (error) {
+            await reader.cancel().catch(() => undefined);
+            throw error instanceof RangeError
+                ? error
+                : new RangeError(`PNG image data does not inflate: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return offset === byteLength ? output : output.subarray(0, offset);
+    }
+    function joinChunks(chunks) {
+        const joined = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0));
+        let offset = 0;
+        for (const chunk of chunks) {
+            joined.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return joined;
+    }
+    function readPngHeader(input, bitDepth) {
+        const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        if (bytes.byteLength < 8 ||
+            PNG_SIGNATURE.some((value, index) => bytes[index] !== value)) {
+            throw new RangeError("Not a PNG file.");
+        }
+        let offset = 8;
+        let width = 0;
+        let height = 0;
+        let sawHeader = false;
+        let sawEnd = false;
+        const idat = [];
+        while (offset + 12 <= bytes.byteLength) {
+            const length = view.getUint32(offset);
+            const type = view.getUint32(offset + 4);
+            const dataStart = offset + 8;
+            const dataEnd = dataStart + length;
+            if (dataEnd + 4 > bytes.byteLength) {
+                throw new RangeError("PNG file is truncated.");
+            }
+            if (type === 0x49484452) {
+                // IHDR
+                if (length !== 13)
+                    throw new RangeError("PNG header is malformed.");
+                width = view.getUint32(dataStart);
+                height = view.getUint32(dataStart + 4);
+                const depth = bytes[dataStart + 8];
+                const colorType = bytes[dataStart + 9];
+                if (bytes[dataStart + 10] !== 0 || bytes[dataStart + 11] !== 0) {
+                    throw new RangeError("PNG uses an unknown compression or filter.");
+                }
+                if (bytes[dataStart + 12] !== 0) {
+                    throw new RangeError("Interlaced PNGs are not supported.");
+                }
+                if (colorType !== COLOR_TYPE_GRAY || depth !== bitDepth) {
+                    throw new RangeError(`Expected a ${bitDepth}-bit grayscale PNG, got bit depth ${depth} with colour type ${colorType}.`);
+                }
+                sawHeader = true;
+            }
+            else if (type === 0x49444154) {
+                // IDAT
+                idat.push(bytes.subarray(dataStart, dataEnd));
+            }
+            else if (type === 0x49454e44) {
+                // IEND
+                sawEnd = true;
+                break;
+            }
+            offset = dataEnd + 4;
+        }
+        if (!sawHeader)
+            throw new RangeError("PNG has no header.");
+        if (!sawEnd)
+            throw new RangeError("PNG file is truncated.");
+        if (width === 0 || height === 0 || width * height > MAX_PNG_PIXELS) {
+            throw new RangeError(`PNG size ${width}x${height} is not supported.`);
+        }
+        if (idat.length === 0)
+            throw new RangeError("PNG has no image data.");
+        return { height, idat, width };
+    }
+    function checkInflatedLength(raw, expected) {
+        if (raw.byteLength !== expected) {
+            throw new RangeError("PNG image data is shorter than its header says.");
+        }
+    }
+    /*
+     * Undoes the row filters of a 16-bit grayscale image and writes host-order
+     * samples, in one pass. Each filter runs on bytes, and the two bytes of a
+     * sample never carry into each other, so the loops keep a sample's high and
+     * low bytes apart and join them only for the store. The previous row is read
+     * back from the output, which already holds it unfiltered; the first row reads
+     * a row of zeros, which is what PNG defines above the image.
+     *
+     * Each filter is its own small function with one loop, called once per row,
+     * so engines compile each loop on its own: SpiderMonkey slowed a Paeth loop
+     * that shared a function with the other filters.
+     */
+    function unfilterGray16(raw, width, height, out) {
+        const rowBytes = width * 2 + 1;
+        const zeroRow = new Uint16Array(width);
+        for (let y = 0; y < height; y += 1) {
+            const filter = raw[y * rowBytes];
+            const unfilterRow = ROW_FILTERS_16[filter];
+            if (!unfilterRow) {
+                throw new RangeError(`PNG row ${y} has unknown filter ${filter}.`);
+            }
+            const o = y * width;
+            unfilterRow(raw, y * rowBytes + 1, out, o, o + width, y === 0 ? zeroRow : out, y === 0 ? 0 : o - width);
+        }
+    }
+    function noneRow16(raw, s, out, o, end) {
+        for (let i = o; i < end; i += 1, s += 2) {
+            out[i] = (raw[s] << 8) | raw[s + 1];
+        }
+    }
+    function subRow16(raw, s, out, o, end) {
+        let hi = 0;
+        let lo = 0;
+        for (let i = o; i < end; i += 1, s += 2) {
+            hi = (raw[s] + hi) & 0xff;
+            lo = (raw[s + 1] + lo) & 0xff;
+            out[i] = (hi << 8) | lo;
+        }
+    }
+    function upRow16(raw, s, out, o, end, prev, p) {
+        for (let i = o; i < end; i += 1, s += 2, p += 1) {
+            const up = prev[p];
+            out[i] = (((raw[s] + (up >> 8)) & 0xff) << 8) | ((raw[s + 1] + up) & 0xff);
+        }
+    }
+    function averageRow16(raw, s, out, o, end, prev, p) {
+        let hi = 0;
+        let lo = 0;
+        for (let i = o; i < end; i += 1, s += 2, p += 1) {
+            const up = prev[p];
+            hi = (raw[s] + ((hi + (up >> 8)) >> 1)) & 0xff;
+            lo = (raw[s + 1] + ((lo + (up & 0xff)) >> 1)) & 0xff;
+            out[i] = (hi << 8) | lo;
+        }
+    }
+    /** Paeth: per byte, whichever of left, up and up-left is closest to left + up - up-left. */
+    function paethRow16(raw, s, out, o, end, prev, p) {
+        let hi = 0;
+        let lo = 0;
+        let upLeftHi = 0;
+        let upLeftLo = 0;
+        for (let i = o; i < end; i += 1, s += 2, p += 1) {
+            const up = prev[p];
+            const upHi = up >> 8;
+            const upLo = up & 0xff;
+            let pa = Math.abs(upHi - upLeftHi);
+            let pb = Math.abs(hi - upLeftHi);
+            let pc = Math.abs(hi + upHi - upLeftHi - upLeftHi);
+            hi =
+                (raw[s] + (pa <= pb && pa <= pc ? hi : pb <= pc ? upHi : upLeftHi)) &
+                    0xff;
+            pa = Math.abs(upLo - upLeftLo);
+            pb = Math.abs(lo - upLeftLo);
+            pc = Math.abs(lo + upLo - upLeftLo - upLeftLo);
+            lo =
+                (raw[s + 1] + (pa <= pb && pa <= pc ? lo : pb <= pc ? upLo : upLeftLo)) &
+                    0xff;
+            out[i] = (hi << 8) | lo;
+            upLeftHi = upHi;
+            upLeftLo = upLo;
+        }
+    }
+    /** Indexed by the PNG filter type byte: None, Sub, Up, Average, Paeth. */
+    const ROW_FILTERS_16 = [
+        noneRow16,
+        subRow16,
+        upRow16,
+        averageRow16,
+        paethRow16,
+    ];
+    function unfilterGray8(raw, width, height, out) {
+        const rowBytes = width + 1;
+        const zeroRow = new Uint8Array(width);
+        for (let y = 0; y < height; y += 1) {
+            const filter = raw[y * rowBytes];
+            const unfilterRow = ROW_FILTERS_8[filter];
+            if (!unfilterRow) {
+                throw new RangeError(`PNG row ${y} has unknown filter ${filter}.`);
+            }
+            const o = y * width;
+            unfilterRow(raw, y * rowBytes + 1, out, o, o + width, y === 0 ? zeroRow : out, y === 0 ? 0 : o - width);
+        }
+    }
+    function noneRow8(raw, s, out, o, end) {
+        out.set(raw.subarray(s, s + end - o), o);
+    }
+    function subRow8(raw, s, out, o, end) {
+        let left = 0;
+        for (let i = o; i < end; i += 1, s += 1) {
+            left = (raw[s] + left) & 0xff;
+            out[i] = left;
+        }
+    }
+    function upRow8(raw, s, out, o, end, prev, p) {
+        for (let i = o; i < end; i += 1, s += 1, p += 1) {
+            out[i] = (raw[s] + prev[p]) & 0xff;
+        }
+    }
+    function averageRow8(raw, s, out, o, end, prev, p) {
+        let left = 0;
+        for (let i = o; i < end; i += 1, s += 1, p += 1) {
+            left = (raw[s] + ((left + prev[p]) >> 1)) & 0xff;
+            out[i] = left;
+        }
+    }
+    function paethRow8(raw, s, out, o, end, prev, p) {
+        let left = 0;
+        let upLeft = 0;
+        for (let i = o; i < end; i += 1, s += 1, p += 1) {
+            const up = prev[p];
+            const pa = Math.abs(up - upLeft);
+            const pb = Math.abs(left - upLeft);
+            const pc = Math.abs(left + up - upLeft - upLeft);
+            left =
+                (raw[s] + (pa <= pb && pa <= pc ? left : pb <= pc ? up : upLeft)) & 0xff;
+            out[i] = left;
+            upLeft = up;
+        }
+    }
+    const ROW_FILTERS_8 = [
+        noneRow8,
+        subRow8,
+        upRow8,
+        averageRow8,
+        paethRow8,
+    ];
+    /**
+     * WebGL unpacks rows on four-byte boundaries, so an odd width of two-byte
+     * texels needs one padding texel per row.
+     */
+    function padRows(values, width, height) {
+        const textureWidth = width + 1;
+        const padded = new Uint16Array(textureWidth * height);
+        for (let y = 0; y < height; y += 1) {
+            padded.set(values.subarray(y * width, (y + 1) * width), y * textureWidth);
+        }
+        return { bytes: new Uint8Array(padded.buffer), textureWidth };
+    }
+
+    /**
+     * Answers one decode request, in the worker or on the main thread: the reply
+     * and the buffers it can transfer. A file that does not decode is an error
+     * reply, never a thrown exception, so the caller can tell a bad file from a
+     * broken worker.
+     */
+    async function decodeDepthPreparationRequest(request) {
+        const requestId = request.requestId ?? 0;
+        try {
+            if (request.bitDepth === 8) {
+                const decoded = await decodePng8Gray(request.bytes);
+                return {
+                    response: {
+                        bitDepth: 8,
+                        height: decoded.height,
+                        requestId,
+                        type: DepthPreparationWorkerMessageType.Complete,
+                        values: decoded.values.buffer,
+                        width: decoded.width,
+                    },
+                    transfer: [decoded.values.buffer],
+                };
+            }
+            const decoded = await decodePng16(request.bytes, {
+                padRowsForWebGl: request.padRowsForWebGl,
+            });
+            const padded = decoded.paddedUpload;
+            const decimated = request.decimateBy !== undefined && request.decimateBy >= 2
+                ? decimateDepthUpload(decoded.values, decoded.width, decoded.height, Math.floor(request.decimateBy), request.padRowsForWebGl === true)
+                : null;
+            const transfer = [decoded.values.buffer];
+            if (padded)
+                transfer.push(padded.bytes.buffer);
+            if (decimated)
+                transfer.push(decimated.bytes.buffer);
+            return {
+                response: {
+                    bitDepth: 16,
+                    decimatedUpload: decimated
+                        ? { ...decimated, bytes: decimated.bytes.buffer }
+                        : undefined,
+                    height: decoded.height,
+                    paddedUpload: padded
+                        ? {
+                            bytes: padded.bytes.buffer,
+                            textureWidth: padded.textureWidth,
+                        }
+                        : undefined,
+                    requestId,
+                    type: DepthPreparationWorkerMessageType.Complete,
+                    values: decoded.values.buffer,
+                    width: decoded.width,
+                },
+                transfer,
+            };
+        }
+        catch (error) {
+            return {
+                response: {
+                    error: error instanceof Error ? error.message : "Unable to decode depth.",
+                    requestId,
+                    type: DepthPreparationWorkerMessageType.Error,
+                },
+                transfer: [],
+            };
+        }
+    }
+    /**
+     * Depth for a texture `factor` times smaller on each side, each texel the
+     * sample at its block's centre, as the renderer decimates a map larger than
+     * the GPU allows.
+     */
+    function decimateDepthUpload(values, width, height, factor, padRowsForWebGl) {
+        if (factor < 2)
+            return null;
+        const targetWidth = Math.ceil(width / factor);
+        const targetHeight = Math.ceil(height / factor);
+        // WebGL reads two-byte texels in rows of four bytes.
+        const textureWidth = padRowsForWebGl
+            ? targetWidth + (targetWidth % 2)
+            : targetWidth;
+        const texels = new Uint16Array(textureWidth * targetHeight);
+        const columns = new Uint32Array(targetWidth);
+        for (let x = 0; x < targetWidth; x += 1) {
+            columns[x] = Math.min(width - 1, Math.floor(((x + 0.5) * width) / targetWidth));
+        }
+        for (let y = 0; y < targetHeight; y += 1) {
+            const row = Math.min(height - 1, Math.floor(((y + 0.5) * height) / targetHeight)) *
+                width;
+            const target = y * textureWidth;
+            for (let x = 0; x < targetWidth; x += 1) {
+                texels[target + x] = values[row + columns[x]];
+            }
+        }
+        return {
+            bytes: new Uint8Array(texels.buffer),
+            height: targetHeight,
+            textureWidth,
+            width: targetWidth,
+        };
+    }
+
+    /** Formats whose first plane is 8-bit luma, which is the code as written. */
+    const PLANAR_8_BIT_FORMATS = new Set([
+        "I420",
+        "I420A",
+        "I422",
+        "I422A",
+        "I444",
+        "I444A",
+        "NV12",
+    ]);
+    const RGB_FORMATS = new Set(["RGBA", "RGBX", "BGRA", "BGRX"]);
+    /**
+     * Copies a decoded preview frame's luma codes out of it, mapped through
+     * `correction` when one is given. The frame stays open; its owner closes
+     * it.
+     */
+    async function readVideoFrameLuma(frame, scratch, correction = null) {
+        const rect = frame.visibleRect ?? {
+            height: frame.codedHeight,
+            width: frame.codedWidth,
+            x: 0,
+            y: 0,
+        };
+        const { width, height } = rect;
+        const format = frame.format;
+        const planar = format !== null && PLANAR_8_BIT_FORMATS.has(format);
+        let bytes;
+        let plane;
+        if (planar || (format !== null && RGB_FORMATS.has(format))) {
+            const size = frame.allocationSize({ rect });
+            if (scratch.buffer.byteLength < size)
+                scratch.buffer = new ArrayBuffer(size);
+            [plane] = await frame.copyTo(scratch.buffer, { rect });
+            bytes = new Uint8Array(scratch.buffer);
+        }
+        else {
+            // A frame in a layout no copy can read is drawn to a canvas, which
+            // converts it to RGB as the browser sees fit.
+            bytes = drawFrameRgba(frame, width, height);
+        }
+        const luma = new Uint8Array(width * height);
+        const stride = plane?.stride ?? (planar ? width : width * 4);
+        const offset = plane?.offset ?? 0;
+        if (!planar) {
+            // Every RGB layout keeps green second, and luma with neutral chroma
+            // converts to three equal channels.
+            for (let y = 0; y < height; y += 1) {
+                const row = offset + y * stride + 1;
+                const target = y * width;
+                for (let x = 0; x < width; x += 1) {
+                    luma[target + x] = bytes[row + x * 4];
+                }
+            }
+        }
+        else if (stride === width) {
+            luma.set(bytes.subarray(offset, offset + width * height));
+        }
+        else {
+            for (let y = 0; y < height; y += 1) {
+                luma.set(bytes.subarray(offset + y * stride, offset + y * stride + width), y * width);
+            }
+        }
+        if (correction) {
+            for (let index = 0; index < luma.length; index += 1) {
+                luma[index] = correction[luma[index]];
+            }
+        }
+        return { height, luma, path: planar ? "plane" : "rgb", width };
+    }
+    function drawFrameRgba(frame, width, height) {
+        const canvas = new OffscreenCanvas(width, height);
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context) {
+            throw new Error("The depth preview needs a 2D canvas to read this frame.");
+        }
+        context.drawImage(frame, 0, 0, width, height);
+        const { data } = context.getImageData(0, 0, width, height);
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+
     const workerScope = globalThis;
     workerScope.addEventListener("message", (event) => {
         const message = event.data;
@@ -1113,6 +1704,14 @@
             prepareHeatmap(message);
             return;
         }
+        if (message.type === DepthPreparationWorkerMessageType.Decode) {
+            void decodeDepthFrame(message);
+            return;
+        }
+        if (message.type === DepthPreparationWorkerMessageType.PreviewLuma) {
+            void copyPreviewLuma(message);
+            return;
+        }
         if (message.type !== MaskPreparationWorkerMessageType.Prepare) {
             return;
         }
@@ -1145,6 +1744,44 @@
             });
         }
     }
+    /** Decoding waits on the platform's inflate, so replies arrive out of order. */
+    async function decodeDepthFrame(message) {
+        const { response, transfer } = await decodeDepthPreparationRequest(message);
+        workerScope.postMessage(response, transfer);
+    }
+    const previewLumaScratch = {
+        buffer: new ArrayBuffer(0),
+    };
+    /** Frames arrive in order and are copied in order, through one scratch. */
+    let previewLumaQueue = Promise.resolve();
+    function copyPreviewLuma(message) {
+        previewLumaQueue = previewLumaQueue.then(async () => {
+            try {
+                const copied = await readVideoFrameLuma(message.frame, previewLumaScratch, message.correction);
+                workerScope.postMessage({
+                    height: copied.height,
+                    luma: copied.luma.buffer,
+                    path: copied.path,
+                    requestId: message.requestId,
+                    type: DepthPreparationWorkerMessageType.PreviewLumaComplete,
+                    width: copied.width,
+                }, [copied.luma.buffer]);
+            }
+            catch (error) {
+                workerScope.postMessage({
+                    error: error instanceof Error
+                        ? error.message
+                        : "Unable to copy the depth preview frame.",
+                    requestId: message.requestId,
+                    type: DepthPreparationWorkerMessageType.Error,
+                });
+            }
+            finally {
+                message.frame.close();
+            }
+        });
+        return previewLumaQueue;
+    }
     function prepareMaskFrame(message) {
         try {
             const regionMaskCoverage = createRegionMaskCoverageFrame(message.job.instructions);