@driftengine/capture 4.0.0

package/dist/scene.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Every stage of a capture assembled into one `.drft`, and the proposals read back out of it.
+ *
+ * **One file, because a capture that arrives as six is a capture somebody has to reassemble.** The
+ * cloud draws, the mesh is what a body collides with, the decode program is the surface's material,
+ * the polygon mesh is the way across it, and the proposals are what a scene might make of the
+ * regions. They were produced by five stages that know nothing about each other; what they have in
+ * common is the capture, and that is what a container is for.
+ *
+ * **The proposals are written as a scene, and they are still proposals.** `ENTS` carries them under
+ * a component this package declares — not under a consumer's `transform`, whose field ids belong to
+ * that consumer and which this package has no way to know. So a capture proposes in its own words,
+ * an editor accepts or rejects, and what a scene ends up holding is the consumer's decision. The
+ * schema is written out here rather than built, because `@driftengine/capture` does not depend on
+ * the entity model and must not: the file is data, and the data is what the two sides share.
+ *
+ * **What is not written is the collision mesh**, and that is a payload decision with a reason: it
+ * is the drawn mesh with its degenerate triangles removed, which `collisionMesh` does in a
+ * millisecond at load. A second copy of the same triangles in the file is a second copy to
+ * download. Hulls *are* written, because a convex decomposition is not something to redo on a
+ * player's machine.
+ */
+import { type DrftMaterial, type DrftSplats, type DtexEntry, type EntsScene, type MeshData, type NavPolyMesh } from '@driftengine/drft';
+import type { EntityProposal } from './propose.ts';
+export interface CaptureScene {
+    /** The surface a capture produced, as it is drawn. */
+    readonly mesh: MeshData;
+    /** The materials the mesh refers to. A decode program names one of them by index. */
+    readonly materials?: readonly DrftMaterial[];
+    /** A material as a decode program over a latent, from the texture stage. */
+    readonly material?: DtexEntry;
+    /** The cloud, for what a mesh cannot show. */
+    readonly splats?: DrftSplats;
+    /** A prop's convex hulls, from `propHulls`. Three floats a point. */
+    readonly hulls?: readonly Float32Array[];
+    /** The way across the scene, with the placement it was built at. */
+    readonly navigation?: NavPolyMesh;
+    /** What a scene might make of each region. */
+    readonly proposals?: readonly EntityProposal[];
+}
+/** The component a capture proposes in. Named for what it is: a proposal, not a thing. */
+export declare const PROPOSAL_COMPONENT = "captureProposal";
+/**
+ * The fields a proposal carries, by stable id.
+ *
+ * **Six numbers rather than a bounds array**, because the field types an entity model declares are
+ * scalars and a strings — there is no list among them, and inventing one here would be inventing a
+ * type system for a single consumer. `label` is empty where nobody named the region, and
+ * `components` is the suggested set joined by spaces, which is what an editor offers and what it is
+ * free to ignore.
+ */
+export declare const PROPOSAL_SCHEMA: {
+    readonly name: "captureProposal";
+    readonly fields: readonly [{
+        readonly id: 'capture::proposal::label';
+        readonly name: 'label';
+        readonly type: 'String';
+    }, {
+        readonly id: 'capture::proposal::components';
+        readonly name: 'components';
+        readonly type: 'String';
+    }, {
+        readonly id: 'capture::proposal::walkable';
+        readonly name: 'walkable';
+        readonly type: 'bool';
+    }, {
+        readonly id: 'capture::proposal::minX';
+        readonly name: 'minX';
+        readonly type: 'f32';
+    }, {
+        readonly id: 'capture::proposal::minY';
+        readonly name: 'minY';
+        readonly type: 'f32';
+    }, {
+        readonly id: 'capture::proposal::minZ';
+        readonly name: 'minZ';
+        readonly type: 'f32';
+    }, {
+        readonly id: 'capture::proposal::maxX';
+        readonly name: 'maxX';
+        readonly type: 'f32';
+    }, {
+        readonly id: 'capture::proposal::maxY';
+        readonly name: 'maxY';
+        readonly type: 'f32';
+    }, {
+        readonly id: 'capture::proposal::maxZ';
+        readonly name: 'maxZ';
+        readonly type: 'f32';
+    }];
+};
+/** The proposals as a scene, keyed by field id — the form `serializeWorld` writes. */
+export declare function proposalScene(proposals: readonly EntityProposal[]): EntsScene;
+/**
+ * The proposals a scene carries, in the order they were written.
+ *
+ * **The way back, and it is here rather than in an editor** because the two halves have to agree
+ * about the field ids and one module holding both is how they stay that way. An entity that carries
+ * no proposal is skipped: a consumer may have added its own things to the same scene, and a capture
+ * reading a file is a guest in it.
+ */
+export declare function readProposals(scene: EntsScene): EntityProposal[];
+/** Every stage of `scene` as one `.drft`. */
+export declare function captureFile(scene: CaptureScene): ArrayBuffer;

package/dist/scene.js

@@ -0,0 +1,109 @@
+/**
+ * Every stage of a capture assembled into one `.drft`, and the proposals read back out of it.
+ *
+ * **One file, because a capture that arrives as six is a capture somebody has to reassemble.** The
+ * cloud draws, the mesh is what a body collides with, the decode program is the surface's material,
+ * the polygon mesh is the way across it, and the proposals are what a scene might make of the
+ * regions. They were produced by five stages that know nothing about each other; what they have in
+ * common is the capture, and that is what a container is for.
+ *
+ * **The proposals are written as a scene, and they are still proposals.** `ENTS` carries them under
+ * a component this package declares — not under a consumer's `transform`, whose field ids belong to
+ * that consumer and which this package has no way to know. So a capture proposes in its own words,
+ * an editor accepts or rejects, and what a scene ends up holding is the consumer's decision. The
+ * schema is written out here rather than built, because `@driftengine/capture` does not depend on
+ * the entity model and must not: the file is data, and the data is what the two sides share.
+ *
+ * **What is not written is the collision mesh**, and that is a payload decision with a reason: it
+ * is the drawn mesh with its degenerate triangles removed, which `collisionMesh` does in a
+ * millisecond at load. A second copy of the same triangles in the file is a second copy to
+ * download. Hulls *are* written, because a convex decomposition is not something to redo on a
+ * player's machine.
+ */
+import { writeDrft, } from '@driftengine/drft';
+/** The component a capture proposes in. Named for what it is: a proposal, not a thing. */
+export const PROPOSAL_COMPONENT = 'captureProposal';
+/**
+ * The fields a proposal carries, by stable id.
+ *
+ * **Six numbers rather than a bounds array**, because the field types an entity model declares are
+ * scalars and a strings — there is no list among them, and inventing one here would be inventing a
+ * type system for a single consumer. `label` is empty where nobody named the region, and
+ * `components` is the suggested set joined by spaces, which is what an editor offers and what it is
+ * free to ignore.
+ */
+export const PROPOSAL_SCHEMA = {
+    name: PROPOSAL_COMPONENT,
+    fields: [
+        { id: 'capture::proposal::label', name: 'label', type: 'String' },
+        { id: 'capture::proposal::components', name: 'components', type: 'String' },
+        { id: 'capture::proposal::walkable', name: 'walkable', type: 'bool' },
+        { id: 'capture::proposal::minX', name: 'minX', type: 'f32' },
+        { id: 'capture::proposal::minY', name: 'minY', type: 'f32' },
+        { id: 'capture::proposal::minZ', name: 'minZ', type: 'f32' },
+        { id: 'capture::proposal::maxX', name: 'maxX', type: 'f32' },
+        { id: 'capture::proposal::maxY', name: 'maxY', type: 'f32' },
+        { id: 'capture::proposal::maxZ', name: 'maxZ', type: 'f32' },
+    ],
+};
+const BOUNDS = ['minX', 'minY', 'minZ', 'maxX', 'maxY', 'maxZ'];
+/** The proposals as a scene, keyed by field id — the form `serializeWorld` writes. */
+export function proposalScene(proposals) {
+    return {
+        version: 1,
+        schemas: { [PROPOSAL_COMPONENT]: PROPOSAL_SCHEMA },
+        entities: proposals.map((proposal) => {
+            const fields = {
+                'capture::proposal::label': proposal.label ?? '',
+                'capture::proposal::components': proposal.components.join(' '),
+                'capture::proposal::walkable': proposal.walkable,
+            };
+            BOUNDS.forEach((name, at) => {
+                fields[`capture::proposal::${name}`] = proposal.bounds[at];
+            });
+            return { components: { [PROPOSAL_COMPONENT]: fields } };
+        }),
+    };
+}
+/**
+ * The proposals a scene carries, in the order they were written.
+ *
+ * **The way back, and it is here rather than in an editor** because the two halves have to agree
+ * about the field ids and one module holding both is how they stay that way. An entity that carries
+ * no proposal is skipped: a consumer may have added its own things to the same scene, and a capture
+ * reading a file is a guest in it.
+ */
+export function readProposals(scene) {
+    const out = [];
+    scene.entities.forEach((entity, at) => {
+        const fields = entity.components[PROPOSAL_COMPONENT];
+        if (fields === undefined)
+            return;
+        const bounds = new Float64Array(6);
+        BOUNDS.forEach((name, slot) => {
+            bounds[slot] = Number(fields[`capture::proposal::${name}`] ?? 0);
+        });
+        const label = String(fields['capture::proposal::label'] ?? '');
+        const components = String(fields['capture::proposal::components'] ?? '');
+        out.push({
+            region: at,
+            bounds,
+            label: label === '' ? null : label,
+            components: components === '' ? [] : components.split(' '),
+            walkable: fields['capture::proposal::walkable'] === true,
+        });
+    });
+    return out;
+}
+/** Every stage of `scene` as one `.drft`. */
+export function captureFile(scene) {
+    return writeDrft({
+        meshes: [scene.mesh],
+        materials: scene.materials,
+        dtex: scene.material === undefined ? undefined : [scene.material],
+        splats: scene.splats,
+        colliders: scene.hulls,
+        navigation: scene.navigation,
+        entities: scene.proposals === undefined ? undefined : proposalScene(scene.proposals),
+    });
+}

package/dist/segment.d.ts

@@ -0,0 +1,40 @@
+import type { MeshData } from '@driftengine/drft';
+/** What a region is, once something has decided where it is. */
+export interface Region {
+    /** Triangles belonging to it. */
+    readonly triangles: readonly number[];
+    /** `minX, minY, minZ, maxX, maxY, maxZ`, in the capture's world. */
+    readonly bounds: Float64Array;
+    /** Its area-weighted mean normal, which is what makes a floor a floor. */
+    readonly normal: Float64Array;
+    readonly area: number;
+    /** A label somebody attached, or null — which is the ordinary case. */
+    readonly label: string | null;
+}
+export interface SegmentOptions {
+    /**
+     * How far two triangles' normals may turn and still be one surface, in degrees.
+     *
+     * **The one number that decides what a region is.** Too small and a gently curved wall becomes a
+     * hundred slivers; too large and a floor swallows the skirting board.
+     */
+    readonly creaseDegrees?: number;
+    /** Below this area a run of triangles is not a region. */
+    readonly minimumArea?: number;
+}
+/**
+ * Regions from the geometry alone: runs of triangles that share a plane.
+ *
+ * Two triangles join when they share an edge and their normals agree within the crease angle. Two
+ * surfaces that are parallel but apart — a table top and the floor under it — stay apart because
+ * they share no edge, not because anything measured the gap.
+ *
+ * **A plane offset is deliberately not compared, and the reason is worth keeping.** It was, and the
+ * check could never say what it claimed: two triangles either side of a shared edge both contain
+ * that edge, so equal normals force equal offsets, and unequal normals make the difference grow
+ * with distance from *the origin* — the same crease would join near the origin and split far from
+ * it, on a capture whose origin is wherever the first camera happened to stand.
+ */
+export declare function segmentGeometry(mesh: MeshData, options?: SegmentOptions): Region[];
+export declare function planeOf(mesh: MeshData, face: number, planes: Float64Array, areas: Float64Array): void;
+export declare function regionOf(mesh: MeshData, faces: readonly number[], planes: Float64Array, areas: Float64Array): Region;

package/dist/segment.js

@@ -0,0 +1,184 @@
+/**
+ * A captured mesh cut into surfaces, by its geometry alone.
+ *
+ * **This is what a consumer with no weights gets, and it is not a degraded version of anything.**
+ * Connected runs of triangles that share a plane find a room's floor, its walls and the top of a
+ * table without knowing what any of them *is* — which is most of what a scene needs to be useful,
+ * and is available to every build where a licence does not permit shipping a model. `masks.ts` is
+ * the other source of regions, not the real one.
+ *
+ * **Deterministic.** A mesh segmented twice gives the same regions in the same order, because a
+ * region's number ends up in a file and a consumer's scene refers to it.
+ */
+import { exactCos } from '@driftengine/core';
+const DEFAULT_CREASE = 20;
+const DEFAULT_MINIMUM_AREA = 0.02;
+/**
+ * Regions from the geometry alone: runs of triangles that share a plane.
+ *
+ * Two triangles join when they share an edge and their normals agree within the crease angle. Two
+ * surfaces that are parallel but apart — a table top and the floor under it — stay apart because
+ * they share no edge, not because anything measured the gap.
+ *
+ * **A plane offset is deliberately not compared, and the reason is worth keeping.** It was, and the
+ * check could never say what it claimed: two triangles either side of a shared edge both contain
+ * that edge, so equal normals force equal offsets, and unequal normals make the difference grow
+ * with distance from *the origin* — the same crease would join near the origin and split far from
+ * it, on a capture whose origin is wherever the first camera happened to stand.
+ */
+export function segmentGeometry(mesh, options = {}) {
+    const crease = exactCos(((options.creaseDegrees ?? DEFAULT_CREASE) * Math.PI) / 180);
+    const minimumArea = options.minimumArea ?? DEFAULT_MINIMUM_AREA;
+    const triangles = mesh.indices.length / 3;
+    const planes = new Float64Array(triangles * 4);
+    const areas = new Float64Array(triangles);
+    for (let face = 0; face < triangles; face += 1)
+        planeOf(mesh, face, planes, areas);
+    /* Which triangles share an edge: the pair on each undirected edge of the mesh. */
+    const parent = new Int32Array(triangles);
+    for (let face = 0; face < triangles; face += 1)
+        parent[face] = face;
+    const owner = new Map();
+    const vertices = mesh.positions.length / 3;
+    const welded = weldPositions(mesh);
+    for (let face = 0; face < triangles; face += 1) {
+        for (let slot = 0; slot < 3; slot += 1) {
+            const a = welded[mesh.indices[face * 3 + slot]];
+            const b = welded[mesh.indices[face * 3 + ((slot + 1) % 3)]];
+            const key = a < b ? a * vertices + b : b * vertices + a;
+            const held = owner.get(key);
+            if (held === undefined) {
+                owner.set(key, face);
+                continue;
+            }
+            if (joins(planes, held, face, crease))
+                union(parent, held, face);
+        }
+    }
+    /* Gathered in the order their lowest triangle appears, so the numbering is the mesh's own. */
+    const members = new Map();
+    for (let face = 0; face < triangles; face += 1) {
+        const root = find(parent, face);
+        const held = members.get(root);
+        if (held === undefined)
+            members.set(root, [face]);
+        else
+            held.push(face);
+    }
+    const out = [];
+    for (const [, faces] of members) {
+        const region = regionOf(mesh, faces, planes, areas);
+        if (region.area < minimumArea)
+            continue;
+        out.push(region);
+    }
+    /* Largest first, so a consumer reading a prefix reads the parts of the scene that matter. */
+    out.sort((a, b) => b.area - a.area);
+    return out;
+}
+/**
+ * One vertex per distinct position, so a mesh whose faces do not share vertices still has edges.
+ *
+ * **Flat shading splits every vertex**, and so does any export that keeps a hard crease: each face
+ * arrives with its own copy of each corner. Joining by vertex index alone then finds no shared edge
+ * anywhere on such a mesh and answers *every triangle is its own region* — a segmentation that
+ * found nothing, returned with a straight face. What it gives up: two surfaces that touch without
+ * being joined in the file are joined here, which is what the crease and offset tests are for.
+ *
+ * Welded on the exact bits of the position rather than within a tolerance, because that is what a
+ * duplicate is — a copy — and a tolerance would make the result depend on which vertex was met
+ * first. This engine's own marching welds already, so on a capture's own mesh it is a no-op.
+ */
+function weldPositions(mesh) {
+    const vertices = mesh.positions.length / 3;
+    const out = new Int32Array(vertices);
+    const seen = new Map();
+    for (let v = 0; v < vertices; v += 1) {
+        const key = `${mesh.positions[v * 3]},${mesh.positions[v * 3 + 1]},${mesh.positions[v * 3 + 2]}`;
+        const held = seen.get(key);
+        if (held === undefined) {
+            seen.set(key, v);
+            out[v] = v;
+        }
+        else
+            out[v] = held;
+    }
+    return out;
+}
+export function planeOf(mesh, face, planes, areas) {
+    const a = mesh.indices[face * 3];
+    const b = mesh.indices[face * 3 + 1];
+    const c = mesh.indices[face * 3 + 2];
+    const ux = mesh.positions[b * 3] - mesh.positions[a * 3];
+    const uy = mesh.positions[b * 3 + 1] - mesh.positions[a * 3 + 1];
+    const uz = mesh.positions[b * 3 + 2] - mesh.positions[a * 3 + 2];
+    const vx = mesh.positions[c * 3] - mesh.positions[a * 3];
+    const vy = mesh.positions[c * 3 + 1] - mesh.positions[a * 3 + 1];
+    const vz = mesh.positions[c * 3 + 2] - mesh.positions[a * 3 + 2];
+    const nx = uy * vz - uz * vy;
+    const ny = uz * vx - ux * vz;
+    const nz = ux * vy - uy * vx;
+    const length = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    areas[face] = length / 2;
+    if (!(length > 0))
+        return;
+    planes[face * 4] = nx / length;
+    planes[face * 4 + 1] = ny / length;
+    planes[face * 4 + 2] = nz / length;
+    planes[face * 4 + 3] =
+        (nx / length) * mesh.positions[a * 3] +
+            (ny / length) * mesh.positions[a * 3 + 1] +
+            (nz / length) * mesh.positions[a * 3 + 2];
+}
+function joins(planes, first, second, crease) {
+    let facing = 0;
+    for (let k = 0; k < 3; k += 1) {
+        facing += planes[first * 4 + k] * planes[second * 4 + k];
+    }
+    return facing >= crease;
+}
+export function regionOf(mesh, faces, planes, areas) {
+    const bounds = Float64Array.from([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+    const normal = new Float64Array(3);
+    let area = 0;
+    for (const face of faces) {
+        const weight = areas[face];
+        area += weight;
+        for (let k = 0; k < 3; k += 1) {
+            normal[k] = normal[k] + planes[face * 4 + k] * weight;
+        }
+        for (let slot = 0; slot < 3; slot += 1) {
+            const vertex = mesh.indices[face * 3 + slot];
+            for (let k = 0; k < 3; k += 1) {
+                const value = mesh.positions[vertex * 3 + k];
+                bounds[k] = Math.min(bounds[k], value);
+                bounds[k + 3] = Math.max(bounds[k + 3], value);
+            }
+        }
+    }
+    const length = Math.sqrt(normal[0] * normal[0] +
+        normal[1] * normal[1] +
+        normal[2] * normal[2]);
+    if (length > 0)
+        for (let k = 0; k < 3; k += 1)
+            normal[k] = normal[k] / length;
+    return { triangles: [...faces].sort((a, b) => a - b), bounds, normal, area, label: null };
+}
+function find(parent, at) {
+    let root = at;
+    while (parent[root] !== root)
+        root = parent[root];
+    let walk = at;
+    while (parent[walk] !== root) {
+        const next = parent[walk];
+        parent[walk] = root;
+        walk = next;
+    }
+    return root;
+}
+function union(parent, a, b) {
+    const first = find(parent, a);
+    const second = find(parent, b);
+    if (first !== second)
+        parent[second] = first;
+}

package/dist/testScene.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Analytic scenes rendered on the CPU, so a capture's stages can be held to geometry that is known
+ * before anything runs.
+ *
+ * **It ships rather than sitting in a test**, as `@driftengine/nav`'s test field does: a consumer
+ * porting this, or checking a device against the reference, needs the same scenes the engine's own
+ * tests use, and a fixture that exists only under `*.test.ts` cannot be imported.
+ *
+ * **A ray cast rather than a rasteriser.** Every pixel's answer is the distance along its own ray,
+ * so the depth written beside the colour is the truth rather than an interpolation — which is what
+ * makes it a fixture for depth, for triangulation and for the pose that comes out of them. The
+ * shapes are boxes and planes, which intersect in closed form, and the surfaces are a procedural
+ * checker with a seeded value noise on top: **a corner detector needs something to find**, and a
+ * flat colour would make every later test pass for the wrong reason.
+ *
+ * **What it gives up**: no shadows, no reflections, one directional light. Nothing in a capture
+ * cares — what is measured is where things are, not how they look.
+ */
+export interface TestCamera {
+    readonly width: number;
+    readonly height: number;
+    /** `fx`, `fy`, `cx`, `cy`. */
+    readonly intrinsics: readonly [number, number, number, number];
+    /** 3 × 4 row-major, world to camera. */
+    readonly worldToCamera: Float64Array;
+}
+export interface TestBox {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+    readonly seed: number;
+}
+export interface TestPlane {
+    readonly normal: readonly [number, number, number];
+    /** The plane is `normal · x = offset`. */
+    readonly offset: number;
+    readonly seed: number;
+}
+export interface TestScene {
+    readonly boxes: readonly TestBox[];
+    readonly planes: readonly TestPlane[];
+}
+/**
+ * A world-to-camera for an eye looking at a target, with the world's up.
+ *
+ * **The camera's axes are the ones an image has**: x to the right, **y downward** and z forward, so
+ * row zero of a frame is the top of it. Taking y upward instead renders every scene upside down,
+ * which a test of a corner's position finds and a test of a colour does not.
+ */
+export declare function lookAt(eye: readonly [number, number, number], target: readonly [number, number, number], up?: readonly [number, number, number]): Float64Array;
+/**
+ * `scene` through `camera` into `out`, RGBA, and the distance along the camera's own axis into
+ * `depth` where one
+ * is given — zero where the ray met nothing.
+ */
+export declare function renderTestScene(scene: TestScene, camera: TestCamera, out: Uint8Array, depth?: Float32Array): void;