supervision 0.2.7 → 0.2.9

package/dist/index.js

@@ -1,4 +1,4 @@
-import { copySortedDetectionFrames, detectionFrameOverlapsRange, sortedDetectionFrames, projectDetectionFrameForTracking, createSortTracker, createOCSortTracker, createCBIoUTracker, createByteTrackTracker, MediaErrorKind, includeDefined, createDepthColormapLut, parseDepthManifest, validateDepthMap, resolveDepthFrameFile, PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS, decodeCompressedRleMask, decodeCompressedRleCounts, createIdMaskFrame, encodeBinaryMask, rasterizePolygonToMask, resolveIdMaskPaletteId, canReuseMaskStyleArtifacts, getBufferedDetectionTimelineFrameSnapshot, MediaSourceStatus, MediaRendererPlaybackState, MediaRendererFit, createDefaultAnnotationPresentation, createProjectedDetectionFrameSource, createArrayDetectionFrameSource, createBufferedDetectionTimeline, resolveAnnotationRendererPresentation, PlaybackGateReach, createIdleDetectionBufferState, MediaInteractionMode, MAX_ID_MASK_PALETTE_ENTRIES, StrokeAlignment, BaseBoxStyle, centerRectToTopLeftRect, BoxShape, depthPreviewTopCode, resolveDepthColorMapping, resolveDepthQuantity, computeDepthPercentileRange, BaseFocusStyle, extractDetectionMaskRectRuns, AnnotationGestureStateKind, AnnotationHandleKind, getDetectionRect, DetectionPickTarget, createDetectionPickKey, rebaseDetectionPickToFrame, pickDetectionAtPoint, followDetectionPickAcrossFrames, haveSameDetectionPickIdentities, pickAnnotationHandle, getAnnotationHandles, MAX_ID_MASK_STROKE_WIDTH, LabelPlacement, BasePolygonStyle, BasePolylineStyle, BaseKeypointStyle, ShapeInstructionKind, sampleEllipseArc, resolveEllipseSegmentCount, KeypointMarkerShape, MarkerSizeSpace, MarkerShape, resolveMarkerGeometry, BaseInteractionStyle, DetectionInteractionState, writeIdMaskPaletteEntry, resolveIdMaskStrokeTexels, DetectionBufferStatus, resolveMaskStyleOpacity, pickDetectionByMaskId, BoxStrokeAlignment, RegionRendererMediaEffectKind, RegionRendererSourceKind, RegionRendererCoverageKind, RegionRendererSizeSpace, resolveStyleValue, resolveAnnotationStyleState, lightenColor, resolveAnnotationRendererStyleFields, annotationRendererKinds, createViewportController, MediaSessionMode, DetectionFrameRetentionMode, createMemoryColdDetectionFrameStore, createWritableDetectionFrameSource, createCompositeDetectionFrameSource, MediaSessionActivityStatus, MediaSessionActivityKind, MediaSessionStatus, createSourceAwarePresentation, projectDetectionFrames, DetectionFrameSelectionMode } from 'supervision-js-core';
+import { copySortedDetectionFrames, detectionFrameOverlapsRange, sortedDetectionFrames, projectDetectionFrameForTracking, createSortTracker, createOCSortTracker, createCBIoUTracker, createByteTrackTracker, MediaErrorKind, includeDefined, createDepthColormapLut, parseDepthManifest, validateDepthMap, resolveDepthFrameFile, PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS, decodeCompressedRleMask, decodeCompressedRleCounts, createIdMaskFrame, encodeBinaryMask, rasterizePolygonToMask, resolveIdMaskPaletteId, canReuseMaskStyleArtifacts, getBufferedDetectionTimelineFrameSnapshot, MediaSourceStatus, MediaRendererPlaybackState, MediaRendererFit, createDefaultAnnotationPresentation, createProjectedDetectionFrameSource, createArrayDetectionFrameSource, createBufferedDetectionTimeline, resolveAnnotationRendererPresentation, PlaybackGateReach, createIdleDetectionBufferState, MediaInteractionMode, MAX_ID_MASK_PALETTE_ENTRIES, StrokeAlignment, BaseBoxStyle, centerRectToTopLeftRect, BoxShape, depthPreviewTopCode, resolveDepthColorMapping, resolveDepthQuantity, computeDepthPercentileRange, BaseFocusStyle, extractDetectionMaskRectRuns, AnnotationGestureStateKind, AnnotationHandleKind, getDetectionRect, DetectionPickTarget, rebaseDetectionPickToFrame, pickDetectionAtPoint, createDetectionPickKey, followDetectionPickAcrossFrames, haveSameDetectionPickIdentities, pickAnnotationHandle, getAnnotationHandles, MAX_ID_MASK_STROKE_WIDTH, LabelPlacement, BasePolygonStyle, BasePolylineStyle, BaseKeypointStyle, ShapeInstructionKind, sampleEllipseArc, resolveEllipseSegmentCount, KeypointMarkerShape, MarkerSizeSpace, MarkerShape, resolveMarkerGeometry, BaseInteractionStyle, DetectionInteractionState, writeIdMaskPaletteEntry, resolveIdMaskStrokeTexels, DetectionBufferStatus, resolveMaskStyleOpacity, pickDetectionByMaskId, BoxStrokeAlignment, RegionRendererMediaEffectKind, RegionRendererSourceKind, RegionRendererCoverageKind, RegionRendererSizeSpace, resolveStyleValue, resolveAnnotationStyleState, lightenColor, resolveAnnotationRendererStyleFields, annotationRendererKinds, createViewportController, MediaSessionMode, DetectionFrameRetentionMode, createMemoryColdDetectionFrameStore, createWritableDetectionFrameSource, createCompositeDetectionFrameSource, MediaSessionActivityStatus, MediaSessionActivityKind, MediaSessionStatus, createSourceAwarePresentation, projectDetectionFrames, DetectionFrameSelectionMode } from 'supervision-js-core';
 export { BaseBoxCornerStyle, BaseBoxStyle, BaseFocusStyle, BaseInteractionStyle, BaseKeypointStyle, BaseLabelStyle, BaseMarkerStyle, BaseMaskStyle, BaseOrientedBoxStyle, BasePercentageBarStyle, BasePolygonStyle, BasePolylineStyle, BoxShape, BoxStrokeAlignment, DEFAULT_DETECTION_CLASS_STYLES, DEFAULT_DETECTION_COLOR_SEQUENCE, DepthColormap, DepthMapKind, DepthPreviewLevels, DepthQuantity, DepthSampling, DetectionBufferStatus, DetectionFrameRetentionMode, DetectionFrameSelectionMode, DetectionInteractionState, DetectionMaskEncoding, DetectionPickTarget, FocusTargetMode, KeypointMarkerShape, KeypointVisibility, LabelPlacement, LabelVisibilityMode, MarkerShape, MarkerSizeSpace, MaskRenderMode, MediaErrorKind, MediaInteractionMode, MediaRendererFit, MediaRendererPlaybackState, MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, MediaSourceStatus, PercentageBarPlacement, PlaybackGateReach, RegionRendererComposeMode, RegionRendererCoverageKind, RegionRendererMediaEffectKind, RegionRendererRegionKind, RegionRendererSizeSpace, RegionRendererSourceKind, SUPERVISION_ROBOFLOW_COLOR, TrackingGeometry, annotationRendererKinds, annotationRenderers, computeDepthPercentileRange, createArrayDetectionFrameSource, createBufferedDetectionTimeline, createByteTrackTracker, createCBIoUTracker, createColdDetectionFrameSource, createCompositeDetectionFrameSource, createDefaultAnnotationPresentation, createMemoryColdDetectionFrameStore, createOCSortTracker, createProjectedDetectionFrameSource, createSortTracker, createWritableDetectionFrameSource, depthColormapColors, detectionPostProcessors, normalizeDetectionClassName, parseDepthManifest, pickDetectionAtPoint, projectDetectionFrame, projectDetectionFrameForTracking, projectDetectionFrames, readDepthAt, resolveDetectionClassColorStyle } from 'supervision-js-core';
 import { c as createMediaFrameClock, M as MediaSourceError, t as toMediaSourceError, r as resolveDisplayPixelRatio } from './video-engine-media-source-DOFsuGS4.js';
 export { a as createWebVideoEngineMediaRendererSource, g as getMediaErrorKind, i as isMediaSourceError, o as openWebVideoEngineMediaSource } from './video-engine-media-source-DOFsuGS4.js';
@@ -10132,6 +10132,9 @@ async function createMediaRendererCore(options, providers) {
             polygonStyle: currentPresentation.polygonStyle,
             polylineStyle: currentPresentation.polylineStyle,
             presentedFrames: protectedPresentedFrames?.source,
+            // A source with no duration, such as a still image, has one frame to
+            // show and nothing to play.
+            stillFrame: metadata.duration === 0,
             regionRenderers: resolveRegionRenderers(currentPresentation),
             heatmapRenderers: resolveHeatmapRenderers(currentPresentation),
             depthRenderers: resolveDepthRenderers(currentPresentation),
@@ -10647,6 +10650,260 @@ function matches(left, right) {
         left.every((value, index) => Object.is(value, right[index])));
 }
 
+const BINS = 256;
+const TILE_COUNT = 8;
+const CLIP_LIMIT = 2;
+function computeMediaClahe(rgba, width, height) {
+    const tilesX = Math.min(TILE_COUNT, width);
+    const tilesY = Math.min(TILE_COUNT, height);
+    const luts = new Uint8Array(tilesX * tilesY * BINS);
+    const histogram = new Uint32Array(BINS);
+    for (let ty = 0; ty < tilesY; ty++) {
+        const y0 = Math.floor((ty * height) / tilesY);
+        const y1 = Math.floor(((ty + 1) * height) / tilesY);
+        for (let tx = 0; tx < tilesX; tx++) {
+            const x0 = Math.floor((tx * width) / tilesX);
+            const x1 = Math.floor(((tx + 1) * width) / tilesX);
+            histogram.fill(0);
+            for (let y = y0; y < y1; y++) {
+                for (let x = x0; x < x1; x++) {
+                    const pixel = (y * width + x) * 4;
+                    const luma = Math.round(0.299 * rgba[pixel] +
+                        0.587 * rgba[pixel + 1] +
+                        0.114 * rgba[pixel + 2]);
+                    histogram[luma]++;
+                }
+            }
+            const area = (x1 - x0) * (y1 - y0);
+            const limit = Math.max(1, Math.floor((CLIP_LIMIT * area) / BINS));
+            let excess = 0;
+            for (let i = 0; i < BINS; i++) {
+                if (histogram[i] > limit) {
+                    excess += histogram[i] - limit;
+                    histogram[i] = limit;
+                }
+            }
+            const perBin = Math.floor(excess / BINS);
+            let residual = excess - perBin * BINS;
+            for (let i = 0; i < BINS; i++)
+                histogram[i] += perBin;
+            const residualStep = Math.max(Math.floor(BINS / Math.max(residual, 1)), 1);
+            for (let i = 0; i < BINS && residual > 0; i += residualStep, residual--) {
+                histogram[i]++;
+            }
+            const offset = (ty * tilesX + tx) * BINS;
+            let cumulative = 0;
+            for (let i = 0; i < BINS; i++) {
+                cumulative += histogram[i];
+                luts[offset + i] = Math.round((cumulative * (BINS - 1)) / area);
+            }
+        }
+    }
+    return { luts, tilesX, tilesY };
+}
+
+/**
+ * Pixi keys its program cache by source, so one program is shared by every
+ * shader built from it. `destroy(true)` takes that program with it, leaving
+ * both the peers still rendering through it and the next shader built from the
+ * same source bound to nothing.
+ */
+function destroyShaderKeepingProgram(shader) {
+    try {
+        shader.destroy();
+    }
+    catch {
+        // Pixi has already invalidated this shader's resource group.
+    }
+}
+/**
+ * Pixi uploads a placeholder while it builds a shader's first bind group, and
+ * WebGPU rejects a canvas that was never given a rendering context.
+ */
+function createShaderPlaceholderCanvas() {
+    if (typeof document === "undefined") {
+        return { height: 1, width: 1 };
+    }
+    const canvas = document.createElement("canvas");
+    canvas.height = 1;
+    canvas.width = 1;
+    canvas.getContext("2d");
+    return canvas;
+}
+
+const HISTOGRAM_MAX_DIMENSION = 1024;
+const vertex = `
+in vec2 aPosition;
+out vec2 vTextureCoord;
+out vec2 vImageCoord;
+uniform vec4 uInputSize;
+uniform vec4 uOutputFrame;
+uniform vec4 uOutputTexture;
+uniform mat3 uImageMatrix;
+void main() {
+  vec2 position = aPosition * uOutputFrame.zw + uOutputFrame.xy;
+  position.x = position.x * (2.0 / uOutputTexture.x) - 1.0;
+  position.y = position.y * (2.0 * uOutputTexture.z / uOutputTexture.y) - uOutputTexture.z;
+  gl_Position = vec4(position, 0.0, 1.0);
+  vTextureCoord = aPosition * (uOutputFrame.zw * uInputSize.zw);
+  vImageCoord = (uImageMatrix * vec3(vTextureCoord, 1.0)).xy;
+}
+`;
+const fragment = `
+in vec2 vTextureCoord;
+in vec2 vImageCoord;
+out vec4 finalColor;
+uniform sampler2D uTexture;
+uniform sampler2D uLut;
+uniform vec2 uTiles;
+uniform float uGamma;
+uniform float uAuto;
+float lookup(vec2 tile, float luma) {
+  float row = tile.y * uTiles.x + tile.x;
+  return texture(uLut, vec2((luma * 255.0 + 0.5) / 256.0,
+    (row + 0.5) / (uTiles.x * uTiles.y))).r;
+}
+void main() {
+  vec4 color = texture(uTexture, vTextureCoord);
+  if (color.a == 0.0) { finalColor = color; return; }
+  vec3 rgb = color.rgb / color.a;
+  if (uAuto > 0.5) {
+    float luma = dot(rgb, vec3(0.299, 0.587, 0.114));
+    vec2 tilePosition = clamp(vImageCoord, 0.0, 1.0) * uTiles - 0.5;
+    vec2 t0 = floor(tilePosition);
+    vec2 f = tilePosition - t0;
+    vec2 t1 = clamp(t0 + 1.0, vec2(0.0), uTiles - 1.0);
+    t0 = clamp(t0, vec2(0.0), uTiles - 1.0);
+    float top = mix(lookup(t0, luma), lookup(vec2(t1.x, t0.y), luma), f.x);
+    float bottom = mix(lookup(vec2(t0.x, t1.y), luma), lookup(t1, luma), f.x);
+    rgb = clamp(rgb + (mix(top, bottom, f.y) - luma), 0.0, 1.0);
+  }
+  finalColor = vec4(pow(rgb, vec3(1.0 / uGamma)) * color.a, color.a);
+}
+`;
+const gpuSource = `
+struct GlobalFilterUniforms {
+  uInputSize: vec4<f32>, uInputPixel: vec4<f32>, uInputClamp: vec4<f32>,
+  uOutputFrame: vec4<f32>, uGlobalFrame: vec4<f32>, uOutputTexture: vec4<f32>,
+};
+struct InspectionUniforms {
+  uImageMatrix: mat3x3<f32>, uTiles: vec2<f32>, uGamma: f32, uAuto: f32,
+};
+@group(0) @binding(0) var<uniform> gfu: GlobalFilterUniforms;
+@group(0) @binding(1) var uTexture: texture_2d<f32>;
+@group(0) @binding(2) var uSampler: sampler;
+@group(1) @binding(0) var<uniform> inspectionUniforms: InspectionUniforms;
+@group(1) @binding(1) var uLut: texture_2d<f32>;
+@group(1) @binding(2) var uLutSampler: sampler;
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>, @location(1) image: vec2<f32>,
+};
+@vertex fn mainVertex(@location(0) aPosition: vec2<f32>) -> VertexOutput {
+  var position = aPosition * gfu.uOutputFrame.zw + gfu.uOutputFrame.xy;
+  position.x = position.x * (2.0 / gfu.uOutputTexture.x) - 1.0;
+  position.y = position.y * (2.0 * gfu.uOutputTexture.z / gfu.uOutputTexture.y) - gfu.uOutputTexture.z;
+  let uv = aPosition * (gfu.uOutputFrame.zw * gfu.uInputSize.zw);
+  return VertexOutput(vec4(position, 0.0, 1.0), uv,
+    (inspectionUniforms.uImageMatrix * vec3(uv, 1.0)).xy);
+}
+fn lookup(tile: vec2<f32>, luma: f32) -> f32 {
+  let tiles = inspectionUniforms.uTiles;
+  let row = tile.y * tiles.x + tile.x;
+  return textureSampleLevel(uLut, uLutSampler,
+    vec2((luma * 255.0 + 0.5) / 256.0, (row + 0.5) / (tiles.x * tiles.y)), 0.0).r;
+}
+@fragment fn mainFragment(input: VertexOutput) -> @location(0) vec4<f32> {
+  let color = textureSample(uTexture, uSampler, input.uv);
+  if (color.a == 0.0) { return color; }
+  var rgb = color.rgb / color.a;
+  if (inspectionUniforms.uAuto > 0.5) {
+    let luma = dot(rgb, vec3(0.299, 0.587, 0.114));
+    let tiles = inspectionUniforms.uTiles;
+    let tilePosition = clamp(input.image, vec2(0.0), vec2(1.0)) * tiles - 0.5;
+    let unbounded = floor(tilePosition);
+    let f = tilePosition - unbounded;
+    let t0 = clamp(unbounded, vec2(0.0), tiles - 1.0);
+    let t1 = clamp(unbounded + 1.0, vec2(0.0), tiles - 1.0);
+    let top = mix(lookup(t0, luma), lookup(vec2(t1.x, t0.y), luma), f.x);
+    let bottom = mix(lookup(vec2(t0.x, t1.y), luma), lookup(t1, luma), f.x);
+    rgb = clamp(rgb + (mix(top, bottom, f.y) - luma), vec3(0.0), vec3(1.0));
+  }
+  return vec4(pow(rgb, vec3(1.0 / inspectionUniforms.uGamma)) * color.a, color.a);
+}
+`;
+function createPixiMediaInspectionFilter(sprite, pixi) {
+    const { BufferImageSource, Filter, Matrix } = pixi;
+    const pixels = new Uint8Array(256 * 64 * 4);
+    const lutSource = new BufferImageSource({
+        resource: pixels,
+        width: 256,
+        height: 64,
+        scaleMode: "linear",
+        alphaMode: "no-premultiply-alpha",
+    });
+    const filter = Filter.from({
+        gl: { vertex: vertex, fragment: fragment },
+        gpu: {
+            vertex: { source: gpuSource, entryPoint: "mainVertex" },
+            fragment: { source: gpuSource, entryPoint: "mainFragment" },
+        },
+        resolution: "inherit",
+        resources: {
+            inspectionUniforms: {
+                uImageMatrix: { value: new Matrix(), type: "mat3x3<f32>" },
+                uTiles: { value: new Float32Array([8, 8]), type: "vec2<f32>" },
+                uGamma: { value: 1, type: "f32" },
+                uAuto: { value: 0, type: "f32" },
+            },
+            uLut: lutSource,
+            uLutSampler: lutSource.style,
+        },
+    });
+    const uniforms = filter.resources.inspectionUniforms.uniforms;
+    let hasHistogram = false;
+    filter.apply = (manager, input, output, clear) => {
+        // The filter input is clipped by the viewport; lookup tiles stay anchored
+        // to the full image when the user zooms or pans.
+        manager.calculateSpriteMatrix(uniforms.uImageMatrix, sprite);
+        manager.applyFilter(filter, input, output, clear);
+    };
+    return {
+        filter,
+        invalidateImage() {
+            hasHistogram = false;
+        },
+        update(gamma, autoContrast, image) {
+            uniforms.uGamma = Math.max(gamma, 0.0001);
+            if (autoContrast && image && !hasHistogram) {
+                const scale = Math.min(1, HISTOGRAM_MAX_DIMENSION / Math.max(image.width, image.height));
+                const sample = document.createElement("canvas");
+                sample.width = Math.max(1, Math.round(image.width * scale));
+                sample.height = Math.max(1, Math.round(image.height * scale));
+                const context = sample.getContext("2d", { willReadFrequently: true });
+                context.drawImage(image, 0, 0, sample.width, sample.height);
+                const { luts, tilesX, tilesY } = computeMediaClahe(context.getImageData(0, 0, sample.width, sample.height).data, sample.width, sample.height);
+                for (let i = 0; i < luts.length; i++) {
+                    pixels[i * 4] = luts[i];
+                    pixels[i * 4 + 1] = luts[i];
+                    pixels[i * 4 + 2] = luts[i];
+                    pixels[i * 4 + 3] = 255;
+                }
+                uniforms.uTiles.set([tilesX, tilesY]);
+                lutSource.resource = pixels.subarray(0, luts.length * 4);
+                lutSource.resize(256, tilesX * tilesY);
+                lutSource.update();
+                hasHistogram = true;
+            }
+            uniforms.uAuto = autoContrast && hasHistogram ? 1 : 0;
+        },
+        destroy() {
+            destroyShaderKeepingProgram(filter);
+            lutSource.destroy();
+        },
+    };
+}
+
 /**
  * Which frame a media time draws and how much of it is cooked, as two separate
  * facts. Reporting readiness is what the snapshot and the token are for; a
@@ -10786,35 +11043,6 @@ void main(void) {
 }
 `;
 
-/**
- * Pixi keys its program cache by source, so one program is shared by every
- * shader built from it. `destroy(true)` takes that program with it, leaving
- * both the peers still rendering through it and the next shader built from the
- * same source bound to nothing.
- */
-function destroyShaderKeepingProgram(shader) {
-    try {
-        shader.destroy();
-    }
-    catch {
-        // Pixi has already invalidated this shader's resource group.
-    }
-}
-/**
- * Pixi uploads a placeholder while it builds a shader's first bind group, and
- * WebGPU rejects a canvas that was never given a rendering context.
- */
-function createShaderPlaceholderCanvas() {
-    if (typeof document === "undefined") {
-        return { height: 1, width: 1 };
-    }
-    const canvas = document.createElement("canvas");
-    canvas.height = 1;
-    canvas.width = 1;
-    canvas.getContext("2d");
-    return canvas;
-}
-
 /**
  * The halo a detection actually paints, or `undefined`. A style may answer an
  * instruction that draws nothing, and both the coverage the halo prepares and
@@ -13562,7 +13790,6 @@ function createPixiInteractionLayer(options) {
     let hoveredPick = null;
     let hoveredPickKey = null;
     let selectedPick = null;
-    let selectedPickKey = null;
     let selectedPicks = [];
     let marqueeStart = null;
     let marqueeRect = null;
@@ -13615,9 +13842,19 @@ function createPixiInteractionLayer(options) {
                 setSelectedPick(null);
                 return null;
             }
-            const nextPick = createPickFromSelection(selection);
-            setSelectedPick(nextPick);
-            return nextPick;
+            const nextPicks = selection.detectionIds
+                ? [...new Set(selection.detectionIds)].flatMap((detectionId) => {
+                    const pick = createPickFromSelection({
+                        detectionId,
+                        mediaTime: selection.mediaTime,
+                        point: selection.point,
+                        target: selection.target,
+                    });
+                    return pick ? [pick] : [];
+                })
+                : [createPickFromSelection(selection)].filter((pick) => pick !== null);
+            setSelectedPicks(nextPicks);
+            return nextPicks.at(-1) ?? null;
         },
         getState() {
             return createState();
@@ -13744,6 +13981,18 @@ function createPixiInteractionLayer(options) {
             if (event.button !== undefined && event.button !== 0) {
                 return;
             }
+            if (options.interaction.multiSelect &&
+                event.shiftKey &&
+                pick &&
+                !options.editingEngine.hasCreationTool() &&
+                options.editingEngine.getState().kind ===
+                    AnnotationGestureStateKind.Idle) {
+                // Selection modifiers must run before the editing engine captures a
+                // move. The following pointertap belongs to this same toggle.
+                toggleSelectedPick(pick);
+                suppressNextTap = true;
+                return;
+            }
             // Keep selection owned by this layer. The editing engine deliberately
             // treats a click as a cancelled move, so it cannot establish selection
             // itself; selecting here also makes resize handles available on the next
@@ -13783,7 +14032,7 @@ function createPixiInteractionLayer(options) {
         if (!marqueeStart)
             return;
         if (didDragMarquee && marqueeRect && activeFrame) {
-            selectedPicks = activeFrame.detections.flatMap((detection, detectionIndex) => {
+            const nextPicks = activeFrame.detections.flatMap((detection, detectionIndex) => {
                 if (!canPickDetection(detection))
                     return [];
                 const rect = getDetectionRect(detection);
@@ -13804,10 +14053,7 @@ function createPixiInteractionLayer(options) {
                     },
                 ];
             });
-            selectedPick = selectedPicks.at(-1) ?? null;
-            selectedPickKey = createDetectionPickKey(selectedPick);
-            options.interaction.onSelect?.(selectedPick);
-            options.interaction.onSelectionChange?.(selectedPicks);
+            setSelectedPicks(nextPicks);
         }
         marqueeStart = null;
         marqueeRect = null;
@@ -13903,7 +14149,6 @@ function createPixiInteractionLayer(options) {
         if (nextKeys === currentKeys) {
             return;
         }
-        selectedPickKey = createDetectionPickKey(selectedPick);
         // A followed pick re-bases onto every new frame, so its full pick key
         // changes at playback rate. The scene's normal frame path consumes this
         // refreshed state immediately; emitting onStateChange here would redraw
@@ -13935,15 +14180,17 @@ function createPixiInteractionLayer(options) {
         return true;
     }
     function setSelectedPick(nextPick) {
-        const nextKey = createDetectionPickKey(nextPick);
-        if (nextKey === selectedPickKey) {
-            selectedPick = nextPick;
+        setSelectedPicks(nextPick ? [nextPick] : []);
+    }
+    function setSelectedPicks(nextPicks) {
+        const unchanged = selectedPicks.length === nextPicks.length &&
+            selectedPicks.every((pick, index) => createDetectionPickKey(pick) ===
+                createDetectionPickKey(nextPicks[index]));
+        selectedPicks = nextPicks;
+        selectedPick = nextPicks.at(-1) ?? null;
+        if (unchanged)
             return;
-        }
-        selectedPick = nextPick;
-        selectedPicks = nextPick ? [nextPick] : [];
-        selectedPickKey = nextKey;
-        options.interaction.onSelect?.(nextPick);
+        options.interaction.onSelect?.(selectedPick);
         options.interaction.onSelectionChange?.(selectedPicks);
         notifyStateChange();
     }
@@ -13962,17 +14209,20 @@ function createPixiInteractionLayer(options) {
     function toggleSelectedPick(pick) {
         if (!pick)
             return;
-        const key = createDetectionPickKey(pick);
-        const index = selectedPicks.findIndex((candidate) => createDetectionPickKey(candidate) === key);
-        selectedPicks =
-            index >= 0
-                ? selectedPicks.filter((_, candidateIndex) => candidateIndex !== index)
-                : [...selectedPicks, pick];
-        selectedPick = selectedPicks.at(-1) ?? null;
-        selectedPickKey = createDetectionPickKey(selectedPick);
-        options.interaction.onSelect?.(selectedPick);
-        options.interaction.onSelectionChange?.(selectedPicks);
-        notifyStateChange();
+        const key = createSelectionKey(pick);
+        const index = selectedPicks.findIndex((candidate) => createSelectionKey(candidate) === key);
+        setSelectedPicks(index >= 0
+            ? selectedPicks.filter((_, candidateIndex) => candidateIndex !== index)
+            : [...selectedPicks, pick]);
+    }
+    function createSelectionKey(pick) {
+        // Selection toggles the detection, regardless of whether its body, label,
+        // or keypoint was hit. Keep the picker's frame/index fallback for duplicate ids.
+        return createDetectionPickKey({
+            ...pick,
+            geometryIndex: undefined,
+            target: DetectionPickTarget.Box,
+        });
     }
     function getPoint(event) {
         if (!container)
@@ -17438,6 +17688,13 @@ function createPixiRegionLayer(options) {
             }
             return { activeDetectionIndexes: [...activeDetectionIndexes] };
         },
+        hasAnimatedDisplay() {
+            for (const entry of entries.values()) {
+                if (isAnimatedDisplay(entry.display))
+                    return true;
+            }
+            return false;
+        },
         releaseMaskTexture(texture) {
             if (destroyed)
                 return;
@@ -17760,12 +18017,15 @@ function destroyEntry(entry) {
     // lightweight crop texture; the scene destroys the shared source.
     entry.ownedTexture?.destroy(false);
 }
+function isAnimatedDisplay(display) {
+    return "play" in display && typeof display.play === "function";
+}
 function pauseAnimatedDisplay(display) {
     if ("stop" in display && typeof display.stop === "function")
         display.stop();
 }
 function resumeAnimatedDisplay(display) {
-    if ("play" in display && typeof display.play === "function")
+    if (isAnimatedDisplay(display))
         display.play();
 }
 function matchesTarget(renderer, detection, context) {
@@ -18466,6 +18726,11 @@ function observePixiContainerResize(container, resize) {
  * sample it wants, hands it to `presentSample`, and Pixi's ticker paints the
  * scene every frame.
  *
+ * A still frame is pulled once and then renders on change the way push
+ * presentation does, with the sample it presents as one more change. The
+ * ticker runs only while a looping GIF region or a loading spinner is on the
+ * frame.
+ *
  * Push presentation engages when the opened source carries a presented-frame
  * channel. The producer then decides which frame is on screen and announces it,
  * so the ticker paints nothing and every render is an explicit answer to a
@@ -18496,6 +18761,18 @@ async function createPixiMediaScene(options) {
     let maxTextureSide;
     const maxTextureSize = () => (maxTextureSide ??= queryMaxTextureSize(app.renderer));
     const frameChannel = options.presentedFrames;
+    /**
+     * A still frame has nothing to play, so it renders on change exactly as push
+     * presentation does. The ticker runs only while something on the frame
+     * animates by the clock.
+     */
+    const stillFrame = frameChannel === undefined && options.stillFrame === true;
+    const rendersOnChange = frameChannel !== undefined || stillFrame;
+    let stillFrameTickerRunning = false;
+    /** The content of the `previewOverlay` answer the overlay on screen drew. */
+    let drawnPreviewOverlayContent = null;
+    /** The editing state the overlay on screen was drawn from. */
+    let drawnEditingState;
     let currentFocusStyle = options.focusStyle ?? null;
     let currentLabelStyle = options.labelStyle ?? null;
     let currentMaskStyle = options.maskStyle ?? null;
@@ -18520,6 +18797,9 @@ async function createPixiMediaScene(options) {
     let isScrubbing = false;
     let displayBrightness = 1;
     let displayContrast = 1;
+    let displayGamma = 1;
+    let displayAutoContrast = false;
+    let inspectionFilter;
     let viewportScale = 1;
     let hasPresentedSample = false;
     let mediaHeight = 0;
@@ -18736,7 +19016,7 @@ async function createPixiMediaScene(options) {
         : undefined;
     await app.init({
         autoDensity: true,
-        autoStart: frameChannel === undefined,
+        autoStart: !rendersOnChange,
         backgroundColor: options.backgroundColor ?? 0x111111,
         /* Only the video-engine media path supplies a presented-frame channel, so
          * which reader opens the clip is also what decides which backend draws. */
@@ -18755,7 +19035,10 @@ async function createPixiMediaScene(options) {
     if (!stagingContext) {
         throw new Error("Unable to create staging canvas context.");
     }
-    const renderScheduler = createSceneRenderScheduler(() => app.render());
+    const renderScheduler = createSceneRenderScheduler(() => {
+        app.render();
+        syncStillFrameTicker();
+    });
     const maskBrushPreview = options.maskBrush
         ? createPixiMaskBrushPreview({
             CanvasSource,
@@ -18764,7 +19047,7 @@ async function createPixiMediaScene(options) {
             Sprite,
             Texture,
             preview: options.maskBrush,
-            onInvalidate: frameChannel ? renderNow : undefined,
+            onInvalidate: rendersOnChange ? renderNow : undefined,
         })
         : undefined;
     let appliedPresentation;
@@ -18933,6 +19216,17 @@ async function createPixiMediaScene(options) {
             labelLayer?.drawFrame(currentMediaTime, viewportScale);
             renderNow();
         }
+        // With no ticker to pick it up, an edit the host drives itself, such as a
+        // cancel or a commit, reaches the screen through this notification. A
+        // pointer gesture draws and renders its own state before the microtask
+        // runs, which then finds nothing left to draw or render.
+        if (rendersOnChange) {
+            queueMicrotask(() => {
+                if (isDestroyed || isPresenting)
+                    return;
+                renderOnChange();
+            });
+        }
     });
     const handleKeyDown = (event) => {
         if (event.key === "Tab" && interactionLayer) {
@@ -19122,15 +19416,17 @@ async function createPixiMediaScene(options) {
             renderScene();
     };
     let unsubscribeDetectionTimeline;
-    if (frameChannel) {
-        frameChannel.onPresentedFrame(handlePresentedFrame);
+    if (rendersOnChange) {
         document.addEventListener?.("visibilitychange", handleVisibilityChange);
         // A detection load landing moves what the window covers exactly as a cook
         // landing does. Nothing else brings that to a resting playhead: the layers
         // read the timeline only while drawing, and this is what makes the draw.
         unsubscribeDetectionTimeline = options.detectionTimeline.subscribe?.(handlePreparedWindowChange);
     }
-    else {
+    if (frameChannel) {
+        frameChannel.onPresentedFrame(handlePresentedFrame);
+    }
+    else if (!stillFrame) {
         app.ticker.add(updateMediaSceneFit);
         app.ticker.add(drawAnnotationOverlayNow);
         app.ticker.add(tickFocusLayer);
@@ -19200,7 +19496,9 @@ async function createPixiMediaScene(options) {
         advanceFocus: () => undefined,
         drawAnnotationOverlay: frameChannel
             ? presentLayers.drawAnnotationOverlay
-            : () => undefined,
+            : stillFrame
+                ? (mediaTime) => drawAnnotationOverlay(mediaTime, overlayNow())
+                : () => undefined,
     };
     // A viewport-style redraw covers the layers whose geometry is a function of
     // the viewport scale. Mask outlines reuse the artifact already on screen;
@@ -19250,7 +19548,7 @@ async function createPixiMediaScene(options) {
     };
     return {
         getRenderCount() {
-            return frameChannel ? renderScheduler.getRenderCount() : null;
+            return rendersOnChange ? renderScheduler.getRenderCount() : null;
         },
         getPreparedAnnotationWindow() {
             return frameChannel ? annotationWindow.getSnapshot() : null;
@@ -19359,10 +19657,12 @@ async function createPixiMediaScene(options) {
                 if (!collectFrameTimings) {
                     sample.draw(stagingContext, 0, 0, mediaWidth, mediaHeight);
                     presentedSampleTimestamp = sample.timestamp;
+                    refreshInspectionImage();
                     stagingTextureSource?.update();
                     stagingTexture?.update();
                     const { boxState, regionState } = drawFramePresentLayers(annotationDrawLayers, sample.timestamp);
                     updateMediaSceneFit();
+                    renderOnChange();
                     return {
                         ...createPresentedSampleState(sample.timestamp, boxState, regionState),
                         duration: sample.duration,
@@ -19373,11 +19673,13 @@ async function createPixiMediaScene(options) {
                 const mediaUploadMs = measure(() => {
                     sample.draw(stagingContext, 0, 0, mediaWidth, mediaHeight);
                     presentedSampleTimestamp = sample.timestamp;
+                    refreshInspectionImage();
                     stagingTextureSource?.update();
                     stagingTexture?.update();
                 });
                 const { boxState, regionState } = drawFramePresentLayers(measuredAnnotationDrawLayers, sample.timestamp);
                 const fitMs = measure(updateMediaSceneFit);
+                renderOnChange();
                 return {
                     ...createPresentedSampleState(sample.timestamp, boxState, regionState),
                     duration: sample.duration,
@@ -19435,15 +19737,27 @@ async function createPixiMediaScene(options) {
         },
         setDisplayAdjustments(adjustments) {
             void import('pixi.js').then(({ ColorMatrixFilter }) => {
+                if (isDestroyed)
+                    return;
                 const brightness = adjustments.brightness ?? 1;
                 const contrast = adjustments.contrast ?? 1;
                 const filter = new ColorMatrixFilter();
                 // Preserve the renderer's pixel grid through the adjustment pass.
                 filter.resolution = "inherit";
                 filter.brightness(brightness, false);
-                filter.contrast(contrast - 1, true);
-                if (mediaSprite)
-                    mediaSprite.filters = [filter];
+                displayGamma = adjustments.gamma ?? 1;
+                displayAutoContrast = stillFrame && adjustments.autoContrast === true;
+                filter.contrast(displayAutoContrast ? 0 : contrast - 1, true);
+                if (mediaSprite) {
+                    if (displayGamma !== 1 || displayAutoContrast) {
+                        inspectionFilter ??= createPixiMediaInspectionFilter(mediaSprite, pixi);
+                        inspectionFilter.update(displayGamma, displayAutoContrast, hasPresentedSample ? stagingCanvas : null);
+                        mediaSprite.filters = [inspectionFilter.filter, filter];
+                    }
+                    else {
+                        mediaSprite.filters = [filter];
+                    }
+                }
                 displayBrightness = brightness;
                 displayContrast = contrast;
                 renderOnChange();
@@ -19750,6 +20064,7 @@ async function createPixiMediaScene(options) {
             // a decoder buffer in a producer that outlives the scene.
             frameChannel?.onPresentedFrame((presented) => presented.frame.close());
             destroyBatchTextureBindings();
+            inspectionFilter?.destroy();
             mediaCompositor?.destroy();
             interactionLayer?.destroy();
             interactionPresentationLayer?.destroy();
@@ -20256,7 +20571,7 @@ async function createPixiMediaScene(options) {
             return;
         }
         const { boxState, regionState } = drawAnnotationFrame(currentMediaTime);
-        if (frameChannel) {
+        if (rendersOnChange) {
             const signature = describeSceneRender();
             if (forceRender)
                 renderScheduler.render(signature);
@@ -20313,6 +20628,13 @@ async function createPixiMediaScene(options) {
         labelLayer?.drawCreationPreview(editingState?.kind === AnnotationGestureStateKind.Creating
             ? editingState.preview
             : null, mediaTime, viewportScale);
+        const previewOverlay = options.previewOverlay?.() ?? null;
+        drawnEditingState = editingState;
+        // Only a scene that renders on change compares signatures.
+        if (rendersOnChange) {
+            drawnPreviewOverlayContent =
+                describePreviewOverlayContent(previewOverlay);
+        }
         annotationOverlayLayer.draw({
             frame,
             marquee: interactionState?.marqueeRect ?? null,
@@ -20320,7 +20642,7 @@ async function createPixiMediaScene(options) {
             mediaWidth,
             now: overlayNowMs,
             pointer: interactionState?.pointerPoint ?? null,
-            previewOverlay: options.previewOverlay?.() ?? null,
+            previewOverlay,
             selectedDetectionIds: (interactionState?.selectedPicks ?? []).flatMap(({ detection }) => (detection.id === undefined ? [] : [detection.id])),
             viewportScale,
             visibility: currentVisibility,
@@ -20328,8 +20650,9 @@ async function createPixiMediaScene(options) {
     }
     /**
      * Milliseconds for animations that are not annotation geometry. A pull scene
-     * has a ticker and reads the wall clock; a push scene has the presented media
-     * time and nothing else, so its animations move only when the media does.
+     * has a ticker and reads the wall clock, as does a still frame while its
+     * ticker runs; a push scene has the presented media time and nothing else,
+     * so its animations move only when the media does.
      */
     function overlayNow() {
         return frameChannel ? currentMediaTime * MILLISECONDS_PER_SECOND : now();
@@ -20378,8 +20701,21 @@ async function createPixiMediaScene(options) {
         focusLayer.tick(focusAnimationTimeMs);
     }
     function renderScene() {
+        drawOverlayForEditingState();
         renderScheduler.render(describeSceneRender());
     }
+    /**
+     * The render signature names the editing state, so a render must not record
+     * a state the overlay has not drawn: the redraw that follows would match the
+     * recorded signature and be skipped, leaving the old preview on screen.
+     */
+    function drawOverlayForEditingState() {
+        const editingState = options.editingEngine?.getState();
+        if (editingState === undefined || editingState === drawnEditingState) {
+            return;
+        }
+        drawAnnotationOverlay(currentMediaTime, overlayNow());
+    }
     /**
      * Renders a present at most once per display refresh. Frames arrive as
      * messages from the producer's own thread, so a main thread that falls
@@ -20405,15 +20741,52 @@ async function createPixiMediaScene(options) {
         presentFrameNow(deferred);
     }
     function renderNow() {
-        if (frameChannel)
+        if (rendersOnChange)
             renderScene();
     }
     function renderOnChange() {
-        if (!frameChannel)
+        if (!rendersOnChange)
             return;
         settleFocusAnimation();
+        drawOverlayForEditingState();
         renderScheduler.renderOnChange(describeSceneRender());
     }
+    /**
+     * Runs the ticker on a still frame for as long as something on it moves by
+     * the clock: a looping GIF region or a loading spinner. Pixi renders on
+     * every tick it runs, and the overlay redraws so the spinner turns. Each
+     * render checks again, so the ticker stops with the render that removes the
+     * last of them.
+     */
+    function syncStillFrameTicker() {
+        if (!stillFrame || isDestroyed)
+            return;
+        const animating = hasPresentedSample &&
+            (regionLayer.hasAnimatedDisplay() || hasLoadingDetections());
+        if (animating === stillFrameTickerRunning)
+            return;
+        stillFrameTickerRunning = animating;
+        if (animating) {
+            app.ticker.add(drawAnnotationOverlayNow);
+            app.ticker.start();
+        }
+        else {
+            app.ticker.stop();
+            app.ticker.remove(drawAnnotationOverlayNow);
+        }
+    }
+    function refreshInspectionImage() {
+        if (!stillFrame || !inspectionFilter)
+            return;
+        inspectionFilter.invalidateImage();
+        inspectionFilter.update(displayGamma, displayAutoContrast, stagingCanvas);
+    }
+    function hasLoadingDetections() {
+        const loading = currentVisibility?.loadingDetectionIds;
+        if (!loading)
+            return false;
+        return "size" in loading ? loading.size > 0 : loading.length > 0;
+    }
     /**
      * Everything a render would put on screen, as values that can be compared.
      * Styles are opaque resolvers, so they are compared by identity: handing the
@@ -20439,6 +20812,8 @@ async function createPixiMediaScene(options) {
             app.renderer.resolution,
             displayBrightness,
             displayContrast,
+            displayGamma,
+            displayAutoContrast,
             ...RENDERED_PRESENTATION_FIELDS.map((field) => appliedPresentation?.[field]),
             // Styles above compare by identity; mask opacity is applied after
             // preparation, so a host can move it inside a style object it keeps.
@@ -20451,6 +20826,9 @@ async function createPixiMediaScene(options) {
             interactionState?.marqueeRect,
             options.editingEngine?.getState(),
             options.editingEngine ? interactionState?.pointerPoint : null,
+            // The host's preview is read when the overlay draws, and a host may edit
+            // its arrays in place, so its content is what tells a redraw it changed.
+            drawnPreviewOverlayContent,
         ];
     }
     /**
@@ -20789,6 +21167,37 @@ function elapsedSince(start) {
 function now() {
     return globalThis.performance?.now?.() ?? Date.now();
 }
+/**
+ * A key for what a preview overlay draws, hashed from its coordinates rather
+ * than its arrays, so a preview the host edits in place still changes it.
+ * Coordinates count to a 256th of a media pixel, finer than anything drawn.
+ */
+function describePreviewOverlayContent(overlay) {
+    if (!overlay)
+        return null;
+    let hash = 0x811c9dc5;
+    const mix = (value) => {
+        hash = Math.imul(hash ^ value, 0x01000193);
+    };
+    const mixPoint = (point) => {
+        mix(Math.round(point.x * 256));
+        mix(Math.round(point.y * 256));
+    };
+    for (const polygons of [overlay.hoverPolygons, overlay.draftPolygons]) {
+        mix(polygons?.length ?? -1);
+        for (const polygon of polygons ?? []) {
+            mix(polygon.length);
+            for (const point of polygon)
+                mixPoint(point);
+        }
+    }
+    mix(overlay.points?.length ?? -1);
+    for (const point of overlay.points ?? []) {
+        mixPoint(point);
+        mix(point.positive ? 1 : 0);
+    }
+    return hash;
+}
 /**
  * Fills the container and paints the margin around the canvas in the colour the
  * renderer clears to. The scene owns this element so the canvas is positioned