@driftengine/capture 4.0.0

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/capture` — a video to a playable scene, on the player's own device.
+ *
+ * **What is here so far is the models a capture runs**, each written as a definition the engine's
+ * one neural runtime builds a graph from: `@driftengine/texture` holds the operators and the rule
+ * that every weight is read or set aside by name, and this package says which weights a model reads
+ * and how. A definition is run over a checkpoint once, when it is converted, and over the converted
+ * file afterwards whenever a clip needs the graph at a new size — every device kernel bakes its
+ * shapes, and a clip's aspect ratio decides the patch grid.
+ *
+ * **Depth Anything 3**: depth, its confidence and a camera per view, from one view or several at
+ * once. **Depth Anything V2 Small**, the lighter fallback: relative depth from one view.
+ * **MobileSAM**: masks from a point or a box, an encoder run once an image and a decoder once a
+ * prompt. **SAM 2.1**: the same, and objects tracked through a video by a memory of the frames before.
+ * **OWLv2**: boxes for things named in words, an image graph and a text graph joined on the host,
+ * with CLIP's tokenizer. Each answers as its upstream's own code does on a seeded miniature of its
+ * layout, the fixtures shipped beside them.
+ */
+export { eachFrame, selectFrames } from './frames.ts';
+export type { FrameChoice, FrameSize, FrameSource } from './frames.ts';
+export { cholesky, choleskySolve, levenbergMarquardt, svd3, svdN, symmetricEigen, } from './math/dense.ts';
+export type { FitOptions, LeastSquares } from './math/dense.ts';
+export { schurSolve } from './math/schur.ts';
+export type { BlockNormals } from './math/schur.ts';
+export { DESCRIPTOR_BYTES, createFeatureSet, describeFeatures, detectFeatures, matchFeatures, } from './features.ts';
+export type { Descriptors, FeatureSet } from './features.ts';
+export { estimatePoses } from './poses.ts';
+export type { CaptureFrame, PoseOptions, PoseResult } from './poses.ts';
+export { relativePose, triangulate } from './twoView.ts';
+export type { RelativePoseOut, RelativePoseResult } from './twoView.ts';
+export { lookAt, renderTestScene } from './testScene.ts';
+export type { TestBox, TestCamera, TestPlane, TestScene } from './testScene.ts';
+export { createDepthEstimator } from './depth.ts';
+export type { DepthEstimate, DepthEstimator, DepthView, RawFrame } from './depth.ts';
+export type { GraphRun } from './run.ts';
+export { DEPTH_PIXEL_MEAN, DEPTH_PIXEL_STD, longestSideSize, prepareDepthFrame, prepareOwlv2Frame, prepareSam2Frame, prepareSamFrame, } from './prepare.ts';
+export type { PreparedFrame } from './prepare.ts';
+export { areaResize, triangleResize, PILLOW_PRECISION, TORCHVISION_PRECISION } from './resample.ts';
+export { browserFrameSource } from './browserFrames.ts';
+export type { BrowserClip } from './browserFrames.ts';
+export { DEPTH_ANYTHING_3, decodeCamera, decodeDepth, depthAnything3, } from './models/depthAnything3.ts';
+export type { DepthAnything3Config } from './models/depthAnything3.ts';
+export { DEPTH_ANYTHING_2_SMALL, depthAnything2 } from './models/depthAnything2.ts';
+export type { DepthAnything2Config } from './models/depthAnything2.ts';
+export type { HeadConfig } from './models/dualDpt.ts';
+export type { VitConfig } from './models/vit.ts';
+export { MINIATURE_CASES, MINIATURE_DEPTH_ANYTHING_2, MINIATURE_DEPTH_ANYTHING_3, MINIATURE_SEED, miniatureCheckpoint, miniatureCheckpoint2, miniatureImages, } from './models/miniature.ts';
+export { MOBILE_SAM, SAM_PIXEL_MEAN, SAM_PIXEL_STD, mobileSamDecoder, mobileSamEncoder, samMasksToImage, } from './models/mobileSam.ts';
+export type { MobileSamConfig } from './models/mobileSam.ts';
+export type { SamDecoderConfig } from './models/samDecoder.ts';
+export { SAM2_PROMPT, SAM2_VIDEO_PROMPT, SAM_PROMPT, samGridPositions, samInputSize, samPromptTokens, samTokenCount, stabilityScore, } from './models/samPrompt.ts';
+export type { SamPrompt, SamPromptLayout } from './models/samPrompt.ts';
+export { MINIATURE_MOBILE_SAM, MINIATURE_SAM_IMAGE, MINIATURE_SAM_PROMPTS, miniatureSamCheckpoint, } from './models/samMiniature.ts';
+export type { TinyVitConfig } from './models/tinyVit.ts';
+export { SAM_21_TINY, sam21Decoder, sam21Encoder } from './models/sam21.ts';
+export type { Sam21Config, Sam21MemoryConfig } from './models/sam21.ts';
+export { sam21MasksToImage, sam21MemoryAttention, sam21MemoryEncoder, sam21Upscale, } from './models/sam21Video.ts';
+export { Sam21Tracker } from './models/sam2Tracker.ts';
+export type { Sam21Frame, Sam21Video, Sam21Weights } from './models/sam2Tracker.ts';
+export type { HieraConfig } from './models/hiera.ts';
+export { MINIATURE_SAM_21, MINIATURE_SAM_21_IMAGE, MINIATURE_SAM_21_PROMPTS, miniatureSam21Checkpoint, } from './models/sam21Miniature.ts';
+export { OWLV2_BASE, OWLV2_PIXEL_MEAN, OWLV2_PIXEL_STD, owlv2BoxBias, owlv2Image, owlv2Text, } from './models/owlv2.ts';
+export type { Owlv2Config } from './models/owlv2.ts';
+export type { ClipTowerConfig } from './models/clipTower.ts';
+export { owlv2Detections, owlv2Logits } from './models/owlv2Detect.ts';
+export type { Owlv2Detection, Owlv2Patches } from './models/owlv2Detect.ts';
+export { clipTokenizer, owlv2Tokens } from './models/clipTokenizer.ts';
+export type { ClipTokenizer } from './models/clipTokenizer.ts';
+export { MINIATURE_OWLV2, MINIATURE_OWLV2_IMAGE, MINIATURE_OWLV2_MERGES, MINIATURE_OWLV2_QUERIES, miniatureOwlv2Checkpoint, } from './models/owlv2Miniature.ts';
+export { optimiseGaussians } from './gaussians/optimise.ts';
+export type { OptimiseOptions } from './gaussians/optimise.ts';
+export { projectGaussian, visibleGaussians, LOW_PASS, REACH } from './gaussians/project.ts';
+export type { GaussianSet, Projected, RasterCamera } from './gaussians/project.ts';
+export { rasteriseGaussians } from './gaussians/rasterise.ts';
+export type { Frame } from './gaussians/rasterise.ts';
+export { accumulateGradients, createGradients, imageLoss } from './gaussians/gradients.ts';
+export type { GaussianGradients } from './gaussians/gradients.ts';
+export { sh1Basis, splatColour, SH1_COEFFICIENTS, SH_C1 } from './gaussians/harmonics.ts';
+export { structuralSimilarity, SIMILARITY_WINDOW } from './gaussians/similarity.ts';
+export { renderDepth } from './gaussians/depth.ts';
+export { createVolume, fuseDepth } from './fusion.ts';
+export type { FuseOptions, SurfaceView, Volume } from './fusion.ts';
+export { marchVolume } from './marching.ts';
+export type { MarchOptions } from './marching.ts';
+export { decimate } from './decimate.ts';
+export type { DecimateOptions } from './decimate.ts';
+export { collisionMesh, propHulls } from './collide.ts';
+export type { CollisionOptions, CollisionSource, PropHulls } from './collide.ts';
+export { createDelightOut, delight } from './delight.ts';
+export type { DelightOptions, DelightOut, DelightView } from './delight.ts';
+export { interpolate, nearestHit, renderLit } from './delightScene.ts';
+export type { Light, LitScene, MeshHit } from './delightScene.ts';
+export { segmentGeometry } from './segment.ts';
+export type { Region, SegmentOptions } from './segment.ts';
+export { labelMasks, liftMasks, promptGrid } from './masks.ts';
+export type { MaskView } from './masks.ts';
+export { MOVABLE_COMPONENTS, SCENERY_COMPONENTS, WALKABLE_COMPONENTS, proposeEntities, } from './propose.ts';
+export type { EntityProposal, ProposeOptions } from './propose.ts';
+export { PROPOSAL_COMPONENT, PROPOSAL_SCHEMA, captureFile, proposalScene, readProposals, } from './scene.ts';
+export type { CaptureScene } from './scene.ts';

package/dist/index.js

@@ -0,0 +1,96 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/capture` — a video to a playable scene, on the player's own device.
+ *
+ * **What is here so far is the models a capture runs**, each written as a definition the engine's
+ * one neural runtime builds a graph from: `@driftengine/texture` holds the operators and the rule
+ * that every weight is read or set aside by name, and this package says which weights a model reads
+ * and how. A definition is run over a checkpoint once, when it is converted, and over the converted
+ * file afterwards whenever a clip needs the graph at a new size — every device kernel bakes its
+ * shapes, and a clip's aspect ratio decides the patch grid.
+ *
+ * **Depth Anything 3**: depth, its confidence and a camera per view, from one view or several at
+ * once. **Depth Anything V2 Small**, the lighter fallback: relative depth from one view.
+ * **MobileSAM**: masks from a point or a box, an encoder run once an image and a decoder once a
+ * prompt. **SAM 2.1**: the same, and objects tracked through a video by a memory of the frames before.
+ * **OWLv2**: boxes for things named in words, an image graph and a text graph joined on the host,
+ * with CLIP's tokenizer. Each answers as its upstream's own code does on a seeded miniature of its
+ * layout, the fixtures shipped beside them.
+ */
+export { eachFrame, selectFrames } from './frames.js';
+export { cholesky, choleskySolve, levenbergMarquardt, svd3, svdN, symmetricEigen, } from './math/dense.js';
+export { schurSolve } from './math/schur.js';
+export { DESCRIPTOR_BYTES, createFeatureSet, describeFeatures, detectFeatures, matchFeatures, } from './features.js';
+export { estimatePoses } from './poses.js';
+export { relativePose, triangulate } from './twoView.js';
+export { lookAt, renderTestScene } from './testScene.js';
+export { createDepthEstimator } from './depth.js';
+export { DEPTH_PIXEL_MEAN, DEPTH_PIXEL_STD, longestSideSize, prepareDepthFrame, prepareOwlv2Frame, prepareSam2Frame, prepareSamFrame, } from './prepare.js';
+export { areaResize, triangleResize, PILLOW_PRECISION, TORCHVISION_PRECISION } from './resample.js';
+export { browserFrameSource } from './browserFrames.js';
+export { DEPTH_ANYTHING_3, decodeCamera, decodeDepth, depthAnything3, } from './models/depthAnything3.js';
+export { DEPTH_ANYTHING_2_SMALL, depthAnything2 } from './models/depthAnything2.js';
+export { MINIATURE_CASES, MINIATURE_DEPTH_ANYTHING_2, MINIATURE_DEPTH_ANYTHING_3, MINIATURE_SEED, miniatureCheckpoint, miniatureCheckpoint2, miniatureImages, } from './models/miniature.js';
+export { MOBILE_SAM, SAM_PIXEL_MEAN, SAM_PIXEL_STD, mobileSamDecoder, mobileSamEncoder, samMasksToImage, } from './models/mobileSam.js';
+export { SAM2_PROMPT, SAM2_VIDEO_PROMPT, SAM_PROMPT, samGridPositions, samInputSize, samPromptTokens, samTokenCount, stabilityScore, } from './models/samPrompt.js';
+export { MINIATURE_MOBILE_SAM, MINIATURE_SAM_IMAGE, MINIATURE_SAM_PROMPTS, miniatureSamCheckpoint, } from './models/samMiniature.js';
+export { SAM_21_TINY, sam21Decoder, sam21Encoder } from './models/sam21.js';
+export { sam21MasksToImage, sam21MemoryAttention, sam21MemoryEncoder, sam21Upscale, } from './models/sam21Video.js';
+export { Sam21Tracker } from './models/sam2Tracker.js';
+export { MINIATURE_SAM_21, MINIATURE_SAM_21_IMAGE, MINIATURE_SAM_21_PROMPTS, miniatureSam21Checkpoint, } from './models/sam21Miniature.js';
+export { OWLV2_BASE, OWLV2_PIXEL_MEAN, OWLV2_PIXEL_STD, owlv2BoxBias, owlv2Image, owlv2Text, } from './models/owlv2.js';
+export { owlv2Detections, owlv2Logits } from './models/owlv2Detect.js';
+export { clipTokenizer, owlv2Tokens } from './models/clipTokenizer.js';
+export { MINIATURE_OWLV2, MINIATURE_OWLV2_IMAGE, MINIATURE_OWLV2_MERGES, MINIATURE_OWLV2_QUERIES, miniatureOwlv2Checkpoint, } from './models/owlv2Miniature.js';
+/*
+ * **Gaussians.** A reference rasteriser that projects the way `@driftengine/splats`' shader does,
+ * its analytic gradients, and the fit that descends them into a `SplatSource` the engine draws.
+ * `optimiseGaussians` is what a caller wants; the rest is exported because a caller measuring or
+ * extending a fit needs the same pieces the fit is built from.
+ */
+export { optimiseGaussians } from './gaussians/optimise.js';
+export { projectGaussian, visibleGaussians, LOW_PASS, REACH } from './gaussians/project.js';
+export { rasteriseGaussians } from './gaussians/rasterise.js';
+export { accumulateGradients, createGradients, imageLoss } from './gaussians/gradients.js';
+export { sh1Basis, splatColour, SH1_COEFFICIENTS, SH_C1 } from './gaussians/harmonics.js';
+export { structuralSimilarity, SIMILARITY_WINDOW } from './gaussians/similarity.js';
+/*
+ * **Splats to a surface.** A cloud's depth, many views of it fused into one volume, that volume's
+ * crossing as a mesh facing outwards, and the mesh brought down to a budget — which is what a game
+ * stands on, rather than the cloud, which only draws.
+ */
+export { renderDepth } from './gaussians/depth.js';
+export { createVolume, fuseDepth } from './fusion.js';
+export { marchVolume } from './marching.js';
+export { decimate } from './decimate.js';
+/*
+ * **A surface to stand on.** The drawn mesh cleaned for collision, and a prop's convex hulls inside
+ * the container's own caps — which is where a capture stops being a picture.
+ */
+export { collisionMesh, propHulls } from './collide.js';
+/*
+ * **A surface's material, separated from the light it was photographed under.** Multi-view inverse
+ * rendering with a classical separation: what stays the same across views is the material, what
+ * moves is the light, and a chromaticity that holds across an intensity jump is a shadow. Every
+ * surface gets a confidence, and `delight.ts` states plainly what that confidence does and does not
+ * grade. `renderLit` is the lit fixture the measurements are made against.
+ */
+export { createDelightOut, delight } from './delight.js';
+export { interpolate, nearestHit, renderLit } from './delightScene.js';
+/*
+ * **A mesh cut into regions, and each region proposed as something a scene could hold.** Stage four
+ * and labelled as such: with a model loaded the masks are voted onto the mesh, and with none the
+ * geometry answers on its own. Nothing here decides what an object *is* — a region nobody labelled
+ * comes back as scenery, which is drawn, solid, and doing nothing.
+ */
+export { segmentGeometry } from './segment.js';
+export { labelMasks, liftMasks, promptGrid } from './masks.js';
+export { MOVABLE_COMPONENTS, SCENERY_COMPONENTS, WALKABLE_COMPONENTS, proposeEntities, } from './propose.js';
+/*
+ * **Every stage in one file.** A capture that arrives as six files is a capture somebody has to
+ * reassemble; this writes the mesh, its materials and decode program, the cloud, a prop's hulls,
+ * the way across the scene and the proposals into one `.drft`. The proposals travel under a
+ * component this package declares — a capture proposes in its own words, and what a scene ends up
+ * holding is the consumer's decision.
+ */
+export { PROPOSAL_COMPONENT, PROPOSAL_SCHEMA, captureFile, proposalScene, readProposals, } from './scene.js';

package/dist/marching.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A volume's zero crossing as a mesh, facing outwards.
+ *
+ * **Tetrahedra rather than cubes, and the reason is watertightness rather than taste.** Marching
+ * cubes classifies a cube's eight corners into 256 cases, and a handful of those are *ambiguous*:
+ * the same corner signs admit two different surfaces, and two neighbouring cubes that resolve one
+ * the two different ways leave a hole between them. Every implementation patches this, and the
+ * patches are the part that gets subtly wrong. A tetrahedron has four corners and sixteen cases,
+ * **none of them ambiguous** — a plane through a tetrahedron cuts it one way — so a mesh built this
+ * way is closed wherever the volume is known, by construction rather than by a table of exceptions.
+ *
+ * What it costs is triangles: roughly twice what marching cubes emits for the same surface, because
+ * a cube is cut six ways rather than once. `decimate` is the answer to that, and it is a better
+ * answer than an ambiguity table because it is driven by the error it introduces.
+ *
+ * **A cube with an unknown corner is not marched at all.** A sample no view ever saw has no
+ * distance, and a surface built through it is one the capture invented — which is exactly the
+ * spurious closing surface an open scene must not grow. The boundary of what was seen is left open,
+ * and that is the honest shape of a clip that walked through a room rather than around an object.
+ *
+ * **Normals come from the volume's gradient, and their sign is checked against it.** An inverted
+ * mesh collides inside-out: a character walks through the floor and falls out of the world, which
+ * reads as a physics fault and is a meshing one.
+ */
+import type { MeshData } from '@driftengine/drft';
+import type { Volume } from './fusion.ts';
+export interface MarchOptions {
+    /** A sample with less evidence than this is treated as unknown, and its cube is not marched. */
+    readonly minimumWeight?: number;
+}
+/**
+ * `volume`'s surface, welded so that neighbours share vertices exactly.
+ *
+ * A vertex belongs to the *edge* it was found on, so two tetrahedra meeting along an edge find the
+ * same one — which is what closes the mesh. Answers the mesh; a volume with no crossing answers an
+ * empty one rather than throwing, because a capture of nothing is a real thing to have.
+ */
+export declare function marchVolume(volume: Volume, options?: MarchOptions): MeshData;

package/dist/marching.js

@@ -0,0 +1,258 @@
+/**
+ * The six tetrahedra a cube is cut into, by corner index.
+ *
+ * Corner `n` is the one at `(n & 1, (n >> 1) & 1, (n >> 2) & 1)`. Every tetrahedron holds corners
+ * 0 and 7 — the cube's main diagonal — which is what makes the cut the same for every cube and so
+ * agrees across their shared faces. A cut chosen per cube would leave the faces between them
+ * triangulated two different ways, which is the hole this arrangement exists to avoid.
+ */
+const TETRAHEDRA = [
+    [0, 7, 1, 3],
+    [0, 7, 3, 2],
+    [0, 7, 2, 6],
+    [0, 7, 6, 4],
+    [0, 7, 4, 5],
+    [0, 7, 5, 1],
+];
+/** The six edges of a tetrahedron, as pairs of its own corner slots. */
+const TETRA_EDGES = [
+    [0, 1],
+    [0, 2],
+    [0, 3],
+    [1, 2],
+    [1, 3],
+    [2, 3],
+];
+const DEFAULT_WEIGHT = 1e-6;
+/**
+ * How far a crossing is kept from either end of the edge it is on, as a fraction of that edge.
+ *
+ * **A surface passing exactly through a sample is the one degenerate case tetrahedra do not save
+ * you from.** Every edge out of that sample crosses at its very end, so several crossings land on
+ * the same point and the triangles between them have no area at all — measured on a sphere whose
+ * radius is a whole number of samples: **280 faces of 3,960 with zero area**, and 256 of those with
+ * no direction to wind by, because a degenerate triangle has no normal. They cannot simply be
+ * dropped: their edges are shared with real faces, and dropping them opens the mesh.
+ *
+ * So the crossing is held a thousandth of an edge away from each end instead. At a tenth-metre
+ * spacing that is a tenth of a millimetre of geometry given up, and it makes the case stop
+ * existing rather than handling it.
+ */
+const MARGIN = 1e-3;
+/**
+ * `volume`'s surface, welded so that neighbours share vertices exactly.
+ *
+ * A vertex belongs to the *edge* it was found on, so two tetrahedra meeting along an edge find the
+ * same one — which is what closes the mesh. Answers the mesh; a volume with no crossing answers an
+ * empty one rather than throwing, because a capture of nothing is a real thing to have.
+ */
+export function marchVolume(volume, options = {}) {
+    const [nx, ny, nz] = volume.dims;
+    const minimumWeight = options.minimumWeight ?? DEFAULT_WEIGHT;
+    const positions = [];
+    const normals = [];
+    const indices = [];
+    /* Which vertex each crossed edge already has, keyed by its two sample indices. */
+    const vertexOf = new Map();
+    const corner = new Int32Array(8);
+    const value = new Float64Array(8);
+    for (let k = 0; k + 1 < nz; k += 1) {
+        for (let j = 0; j + 1 < ny; j += 1) {
+            for (let i = 0; i + 1 < nx; i += 1) {
+                let known = true;
+                for (let n = 0; n < 8; n += 1) {
+                    const at = (((k + ((n >> 2) & 1)) * ny + (j + ((n >> 1) & 1))) * nx +
+                        (i + (n & 1)));
+                    corner[n] = at;
+                    value[n] = volume.distance[at];
+                    if (volume.weight[at] < minimumWeight)
+                        known = false;
+                }
+                if (!known)
+                    continue;
+                for (const tetra of TETRAHEDRA) {
+                    marchTetrahedron(volume, corner, value, tetra, vertexOf, positions, normals, indices);
+                }
+            }
+        }
+    }
+    const colors = new Float32Array(positions.length).fill(1);
+    return {
+        positions: Float32Array.from(positions),
+        normals: Float32Array.from(normals),
+        colors,
+        /*
+         * **One float a vertex, which is what `MeshData` means by emissive** — how much of the
+         * surface's own colour it emits — rather than a colour of its own. It was three, and nothing
+         * noticed until a captured mesh was written to a file: every consumer of it so far measured
+         * geometry, and the container is the first thing that checks an attribute's length against
+         * the vertex count. A short attribute buffer is the failure `writeDrft` refuses by name,
+         * because a driver handed one may draw zeroes or drop the draw.
+         */
+        emissive: new Float32Array(positions.length / 3),
+        indices: Uint32Array.from(indices),
+    };
+}
+function marchTetrahedron(volume, corner, value, tetra, vertexOf, positions, normals, indices) {
+    /* Which of the four corners are inside, as a four-bit pattern. */
+    let pattern = 0;
+    for (let slot = 0; slot < 4; slot += 1) {
+        if (value[tetra[slot]] < 0)
+            pattern |= 1 << slot;
+    }
+    if (pattern === 0 || pattern === 15)
+        return;
+    /* The edges this pattern crosses: one end inside, the other out. */
+    const crossings = [];
+    for (const [a, b] of TETRA_EDGES) {
+        const insideA = (pattern & (1 << a)) !== 0;
+        const insideB = (pattern & (1 << b)) !== 0;
+        if (insideA === insideB)
+            continue;
+        crossings.push(vertexOn(volume, corner[tetra[a]], corner[tetra[b]], value[tetra[a]], value[tetra[b]], vertexOf, positions, normals));
+    }
+    /*
+     * Three crossings where one corner is alone on its side of the surface, four where they are two
+     * against two — a quadrilateral, which becomes two triangles. There is no other case: this is the
+     * whole of the ambiguity marching cubes has and tetrahedra do not.
+     */
+    if (crossings.length === 3) {
+        emit(volume, positions, normals, indices, crossings[0], crossings[1], crossings[2]);
+        return;
+    }
+    if (crossings.length !== 4)
+        return;
+    /*
+     * The four are in edge order, which walks the quadrilateral as 0–1–3–2 rather than 0–1–2–3: the
+     * edges opposite each other in the list share no corner. Taking them in the listed order would
+     * fold the quad into a bowtie, which is a pair of triangles that overlap and leave a hole.
+     */
+    emit(volume, positions, normals, indices, crossings[0], crossings[1], crossings[3]);
+    emit(volume, positions, normals, indices, crossings[0], crossings[3], crossings[2]);
+}
+/** The crossing on the edge between two samples, made once and shared by everything that meets it. */
+function vertexOn(volume, a, b, valueA, valueB, vertexOf, positions, normals) {
+    /* Keyed by the pair, smaller first, so the two tetrahedra either side agree on the key. */
+    const low = a < b ? a : b;
+    const high = a < b ? b : a;
+    const key = low * volume.distance.length + high;
+    const held = vertexOf.get(key);
+    if (held !== undefined)
+        return held;
+    const first = low === a ? valueA : valueB;
+    const second = low === a ? valueB : valueA;
+    /* Where the line between the two samples is zero; a pair that does not straddle takes the middle. */
+    const span = second - first;
+    const found = span === 0 ? 0.5 : first / -span;
+    const t = found < MARGIN ? MARGIN : found > 1 - MARGIN ? 1 - MARGIN : found;
+    const index = positions.length / 3;
+    const [nx, ny] = volume.dims;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const from = sampleAxis(low, axis, nx, ny);
+        const to = sampleAxis(high, axis, nx, ny);
+        positions.push(volume.origin[axis] + (from + (to - from) * t) * volume.spacing);
+    }
+    const normal = gradientAt(volume, low, high, t);
+    normals.push(normal[0], normal[1], normal[2]);
+    vertexOf.set(key, index);
+    return index;
+}
+function sampleAxis(at, axis, nx, ny) {
+    if (axis === 0)
+        return at % nx;
+    if (axis === 1)
+        return Math.floor(at / nx) % ny;
+    return Math.floor(at / (nx * ny));
+}
+/**
+ * The volume's gradient partway along an edge, normalised: which way is out.
+ *
+ * Taken at each end and blended, rather than at the point, because the gradient is only defined at
+ * samples. A gradient of nothing — a flat patch of volume — answers the edge's own direction, which
+ * is the one thing that is certainly not tangent to the surface there.
+ */
+function gradientAt(volume, low, high, t) {
+    const first = gradientAtSample(volume, low);
+    const second = gradientAtSample(volume, high);
+    const out = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis += 1) {
+        out[axis] = first[axis] * (1 - t) + second[axis] * t;
+    }
+    const length = Math.sqrt(out[0] * out[0] +
+        out[1] * out[1] +
+        out[2] * out[2]);
+    if (length > 1e-12) {
+        for (let axis = 0; axis < 3; axis += 1)
+            out[axis] = out[axis] / length;
+        return out;
+    }
+    const [nx, ny] = volume.dims;
+    const fallback = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis += 1) {
+        fallback[axis] = sampleAxis(high, axis, nx, ny) - sampleAxis(low, axis, nx, ny);
+    }
+    const span = Math.sqrt(fallback[0] * fallback[0] +
+        fallback[1] * fallback[1] +
+        fallback[2] * fallback[2]);
+    return span > 0 ? fallback.map((value) => value / span) : [0, 0, 1];
+}
+/** A central difference where both neighbours exist, and a one-sided one at the volume's edge. */
+function gradientAtSample(volume, at) {
+    const [nx, ny, nz] = volume.dims;
+    const x = at % nx;
+    const y = Math.floor(at / nx) % ny;
+    const z = Math.floor(at / (nx * ny));
+    const here = volume.distance[at];
+    const out = [0, 0, 0];
+    const steps = [1, nx, nx * ny];
+    const limits = [
+        [x, nx],
+        [y, ny],
+        [z, nz],
+    ];
+    for (let axis = 0; axis < 3; axis += 1) {
+        const [position, size] = limits[axis];
+        const step = steps[axis];
+        const low = position > 0 ? volume.distance[at - step] : here;
+        const high = position + 1 < size ? volume.distance[at + step] : here;
+        const span = (position > 0 ? 1 : 0) + (position + 1 < size ? 1 : 0);
+        out[axis] = span === 0 ? 0 : (high - low) / (span * volume.spacing);
+    }
+    return out;
+}
+/**
+ * One triangle, wound so that its own normal agrees with the volume's gradient.
+ *
+ * **This is the check the whole module exists to pass.** A mesh whose faces point inwards collides
+ * inside-out — a character walks through the floor and out of the world — and it looks entirely
+ * correct until something stands on it.
+ */
+function emit(volume, positions, normals, indices, a, b, c) {
+    if (a === b || b === c || a === c)
+        return;
+    const ax = positions[a * 3];
+    const ay = positions[a * 3 + 1];
+    const az = positions[a * 3 + 2];
+    const ux = positions[b * 3] - ax;
+    const uy = positions[b * 3 + 1] - ay;
+    const uz = positions[b * 3 + 2] - az;
+    const vx = positions[c * 3] - ax;
+    const vy = positions[c * 3 + 1] - ay;
+    const vz = positions[c * 3 + 2] - az;
+    const fx = uy * vz - uz * vy;
+    const fy = uz * vx - ux * vz;
+    const fz = ux * vy - uy * vx;
+    /* The three vertices' own normals, which came from the gradient, say which way out is. */
+    let outward = 0;
+    for (const vertex of [a, b, c]) {
+        outward +=
+            fx * normals[vertex * 3] +
+                fy * normals[vertex * 3 + 1] +
+                fz * normals[vertex * 3 + 2];
+    }
+    if (outward >= 0)
+        indices.push(a, b, c);
+    else
+        indices.push(a, c, b);
+    void volume;
+}

package/dist/masks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A segmentation model's masks brought onto the mesh, and a detector's names brought onto the masks.
+ *
+ * **Where a region comes from when weights are loaded.** A prompt lattice asks the model what is in
+ * the frame, the masks that come back are voted onto the mesh across every view that saw a
+ * triangle, and a detector's boxes put names to the mask indices. Nothing here runs a model: masks
+ * and detections arrive as data, so this module is the same code whether they were produced on a
+ * device, on a native host, or by hand in a test.
+ *
+ * **Voting rather than taking the best view**, because a mask boundary is where a model is least
+ * sure and every view puts it somewhere slightly different — and **a triangle no view claimed is
+ * left unassigned**, which is what keeps an unlabelled region unlabelled rather than absorbed.
+ */
+import type { MeshData } from '@driftengine/drft';
+import type { Owlv2Detection } from './models/owlv2Detect.ts';
+import { type Region } from './segment.ts';
+/** Where a model is prompted, and what came back for each prompt. */
+export interface MaskView {
+    /** One mask index per pixel, or −1 where the model claimed nothing. */
+    readonly mask: Int32Array;
+    readonly width: number;
+    readonly height: number;
+    /** 3 × 4 row-major world-to-camera. */
+    readonly worldToCamera: Float64Array;
+    /** `fx`, `fy`, `cx`, `cy`. */
+    readonly intrinsics: readonly [number, number, number, number];
+}
+/**
+ * A lattice of prompt points over an image, seeded.
+ *
+ * **A lattice rather than a scatter**, because a scatter leaves gaps a small object falls into and
+ * a lattice does not; the seeded jitter is there so that a repeated object does not land on the
+ * same part of every instance, which is how a grid misses the same feature twice. Two per pixel
+ * pair — `x` then `y` — in reading order, which is the order a model's masks come back in.
+ */
+export declare function promptGrid(width: number, height: number, across: number, down: number, random: () => number): Float32Array;
+/**
+ * Masks from several views lifted onto the mesh, by what most of the views that saw a triangle say.
+ *
+ * **Voting rather than taking the best view**, because a mask boundary is where a model is least
+ * sure and every view puts it somewhere slightly different. A triangle no view claimed is left
+ * unassigned rather than given to its neighbour, which is what keeps an unlabelled region
+ * unlabelled.
+ */
+export declare function liftMasks(views: readonly MaskView[], mesh: MeshData, labels: readonly string[]): Region[];
+/**
+ * A name for each mask index, from a detector's boxes.
+ *
+ * **The join between the two models a capture runs**: one says *where the things are* and the other
+ * says *what they are called*, and neither can do the other's half. A mask takes the name of the
+ * detection it agrees with most, measured as intersection over union between the mask's own pixels
+ * and the box — the mask's pixels rather than the box around them, because the box around an
+ * L-shaped mask is mostly not the mask.
+ *
+ * **A mask that agrees with nothing gets no name, and that is a result.** `null` here reaches
+ * `proposeEntities` as scenery, which is the safe answer; a name taken from the nearest box
+ * whatever the overlap is how a chair becomes a table. `overlap` is where a caller draws that line.
+ */
+export declare function labelMasks(view: MaskView, detections: readonly Owlv2Detection[], queries: readonly string[], overlap?: number): (string | null)[];