@vincentt-xr/sdk 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/face-character/faceReprojection.d.ts

@@ -0,0 +1,273 @@
+import * as THREE from "three";
+/**
+ * Face reprojection (#199): the live camera face, moved into a face model's
+ * own UV layout so the model can wear it as a texture. Two steps:
+ *
+ * 1. **Unwrap** — the camera face is laid out flat in the canonical face UV
+ *    layout (`CANONICAL_FACE_UVS`): every landmark samples the camera image
+ *    where the tracker found it. The eye and mouth openings, holes in the
+ *    canonical surface, are filled so the eyes and the inside of the mouth
+ *    come along.
+ * 2. **Remap** — every vertex of the model is bound once to its closest point
+ *    on that (filled) canonical surface; drawn in its own UV layout, it reads
+ *    the unwrapped face there.
+ *
+ * This file is the pure part (geometry, per-frame weights, bindings, the
+ * material patch); `FaceReprojector` renders it.
+ */
+/** An opening in the canonical face surface, filled by the unwrap. */
+export type FaceOpening = "leftEye" | "rightEye" | "mouth";
+/** The canonical face surface with its openings filled, laid out for the unwrap. */
+export type FaceUnwrapMesh = {
+    /** Vertices: the 468 landmarks, then one centre per opening. */
+    count: number;
+    /** Canonical head frame, cm (a centre: the average of its ring). */
+    positions: Float32Array;
+    /** Canonical UV, v up (a centre: the average of its ring). */
+    uvs: Float32Array;
+    /** Triangles: the canonical face, then the opening fans. */
+    index: Uint16Array;
+    /** Triangles of the canonical face itself (the fans follow). */
+    faceTriangleCount: number;
+    /** Per vertex: 0 on the outer edge of the face, 1 inside (the unwrap fades out at the edge). */
+    feather: Float32Array;
+    /**
+     * Each opening: its landmark ring (in loop order), its centre vertex and its
+     * fan's triangles (`[first, count]` in `index / 3`).
+     */
+    openings: Record<FaceOpening, {
+        ring: Int32Array;
+        centre: number;
+        triangles: [number, number];
+    }>;
+};
+/** A landmark as the face tracker reports it: normalized image x / y (0..1, y down), z in x units. */
+export type FaceImageLandmark = {
+    x: number;
+    y: number;
+    z?: number;
+};
+/** The canonical face surface with its eye and mouth openings filled (built once). */
+export declare const getFaceUnwrapMesh: () => FaceUnwrapMesh;
+export type FaceUnwrapFrameOptions = {
+    /**
+     * How squarely a patch of skin must face the camera to be kept, as the
+     * cosine of its turn: fully below the first value (a cheek seen edge-on, its
+     * pixels smeared), fully kept above the second. Default `[0.05, 0.3]`.
+     */
+    facing?: readonly [number, number];
+    /**
+     * Drop the landmarks outside the image (weight 0): a point past the edge
+     * samples the clamped edge pixels, not the face. Each opening's centre
+     * follows its ring. `FaceReprojector` also drops every sample past the
+     * edge in its shader, so the cut is exact. Default `false`;
+     * `FaceReprojector` turns it on with `mirrorFill`, so the mirror twin fills
+     * those points.
+     */
+    inFrame?: boolean;
+};
+/** The default `facing` of the unwrap. */
+export declare const FACE_UNWRAP_FACING: readonly [number, number];
+/**
+ * How squarely each unwrap vertex faces the camera, 0..1, for the
+ * `getFaceUnwrapMesh().count` (471) vertices: each landmark takes the mean
+ * turn of its triangles (on-screen area over 3D area, the cosine of the turn
+ * away from the camera), through `smoothstep(facing[0], facing[1], cos)`; each
+ * opening's centre takes the mean of its ring. A mirrored image gives the same
+ * values (the face's side is the one most of its area shows). `aspect` is the
+ * image's width / height; `out` (at least 471 long) is written in place (no
+ * allocation). Throws when `out` or `landmarks` is too short.
+ */
+export declare const writeFaceFacing: (landmarks: ArrayLike<FaceImageLandmark>, aspect: number, facing: readonly [number, number], out: Float32Array) => void;
+/**
+ * One frame of the unwrap: where each unwrap vertex samples the camera image
+ * (`cameraUv`, texture space: x right, y up) and how much of it to keep
+ * (`weight`: the edge feather times `writeFaceFacing`, 0 outside the image
+ * with `inFrame`). The landmarks are the tracker's for this frame, in the
+ * camera image's own space (a mirrored webcam is mirrored before tracking,
+ * so they match the camera texture as it is). `aspect` is the camera image's
+ * width / height. `cameraUv` (942) and `weight` (471) are written in place.
+ */
+export declare const writeFaceUnwrapFrame: (landmarks: ArrayLike<FaceImageLandmark>, aspect: number, { facing, inFrame }: FaceUnwrapFrameOptions, cameraUv: Float32Array, weight: Float32Array) => void;
+/**
+ * The unwrap mesh's UVs in another per-landmark layout (`uvs`: ≥ 468 `[u, v]`
+ * pairs, v up), with each opening's centre at the mean of its ring, so the
+ * same mesh unwraps into that layout. `CANONICAL_FACE_UVS` (the default)
+ * gives `getFaceUnwrapMesh().uvs`; a layout it returned gives itself back.
+ * Cached per array (shared: do not mutate).
+ */
+export declare const getFaceUnwrapUvs: (uvs?: ArrayLike<number>) => Float32Array;
+/**
+ * Each unwrap vertex's mirror twin, the vertex at `(−x, y, z)`: the 468
+ * landmarks by `FACE_ATLAS_MIRROR` (exact, its own inverse), the eye centres
+ * swapped and the mouth centre on itself. Shared: do not mutate.
+ */
+export declare const getFaceUnwrapMirror: () => Int32Array;
+/**
+ * `mirrorFill` fills a point from its mirror twin only where the twin's
+ * weight is clearly better: not at all below the first difference, fully
+ * above the second (smoothstep between). Small differences (a face turned a
+ * few degrees, the two halves' triangulation) keep the point's own pixels,
+ * so asymmetric details (a mole, a parting) are not copied across.
+ */
+export declare const FACE_MIRROR_FILL_RAMP: readonly [number, number];
+/**
+ * The second unwrap draw of `mirrorFill`, from one frame of the first
+ * (`writeFaceUnwrapFrame`'s `cameraUv` and `weight`): each vertex samples its
+ * mirror twin's camera point, weighted to fill only what the first draw left
+ * uncovered. Drawn "under" the first (premultiplied, `dst + (1 − dst.a)·src`),
+ * a vertex ends at `w + r·(w_twin − w)`, `r` = `FACE_MIRROR_FILL_RAMP` of the
+ * difference (0 where its own weight is the better one):
+ * `w′ = r·(w_twin − w) / (1 − w)`. A face seen square on is all but unchanged.
+ */
+export declare const writeFaceMirrorFill: (cameraUv: Float32Array, weight: Float32Array, mirrorCameraUv: Float32Array, mirrorWeight: Float32Array) => void;
+/**
+ * A binding's per-vertex UV in another unwrap layout: where each vertex reads
+ * the unwrap of a `FaceReprojector` made with `uvs` (e.g. `FACE_ATLAS_UVS`).
+ * `binding.canonicalUv` is always the canonical layout; this is the same
+ * surface point (the barycentric blend of its bound triangle's corners) in
+ * `uvs` (≥ 468 `[u, v]` pairs per landmark, or a `getFaceUnwrapUvs` result).
+ * Unbound vertices read `(0, 0)`. Writes `out` (2 per vertex; made when not
+ * given) and returns it. Use it as the `faceUv` attribute of
+ * `patchFaceReprojectionMaterial(..., { attributes: true })` with that
+ * reprojector's `unwrapTexture`.
+ */
+export declare const writeFaceReprojectionLayoutUv: (binding: Pick<FaceReprojectionBinding, "triangle" | "weights">, uvs: ArrayLike<number>, out?: Float32Array) => Float32Array;
+/** Where each vertex of a face model reads the unwrapped face. Arrays are per vertex. */
+export type FaceReprojectionBinding = {
+    /** The bound triangle of the filled canonical face (`getFaceUnwrapMesh().index / 3`), or -1. */
+    triangle: Int32Array;
+    /** Barycentric weights of its three corners (flat, 3 per vertex). */
+    weights: Float32Array;
+    /**
+     * The canonical UV of its closest point on the (filled) canonical face
+     * (flat, v up). Always the canonical layout (`CANONICAL_FACE_UVS`), whatever
+     * a reprojector's `uvs`: `writeFaceReprojectionLayoutUv` gives the same
+     * point in another layout.
+     */
+    canonicalUv: Float32Array;
+    /** How much of the camera face it takes, 0..1 (fading with distance from that surface). */
+    coverage: Float32Array;
+    /** Signed distance from that surface point, cm (+ = in front of the face). */
+    distance: Float32Array;
+};
+export type FaceReprojectionBindingOptions = {
+    /**
+     * How far from the canonical face surface (cm, either side) a vertex still
+     * takes the camera face: fully up to the first value, not at all beyond the
+     * second. Default `[1, 3]` — a character's own proportions (a bigger nose, a
+     * deeper brow) still read the face; the back of the head does not. The
+     * unwrap already fades out at the edge of the face.
+     */
+    falloff?: readonly [number, number];
+    /**
+     * Which filled openings the vertices may bind to (the face skin itself
+     * always). Default all. Skin with eyelids that a blink morph closes should
+     * leave the eyes out (`["mouth"]`) — else a lid's edge, sitting in the eye
+     * opening, wears the eye; eyeballs take `["leftEye", "rightEye"]`.
+     */
+    openings?: readonly FaceOpening[];
+};
+/** The closest point on a triangle mesh: its triangle (or -1), barycentric weights, squared distance. */
+export type ClosestPoint = {
+    triangle: number;
+    u: number;
+    v: number;
+    w: number;
+    d2: number;
+};
+/**
+ * A closest-point search over a triangle mesh (`positions` flat xyz,
+ * `index` flat triangles; `skip[t]` leaves a triangle out). Triangles are
+ * bucketed in a uniform grid by their bounding boxes; a query visits cells in
+ * growing shells around the point and stops once no unvisited cell can be
+ * closer than the best hit — near-constant time per query instead of a scan of
+ * every triangle (a 7 500-vertex transfer onto a 4 600-triangle head: ~400 ms
+ * → a few ms). The returned function fills `out`.
+ */
+export declare const createClosestPointSearch: (positions: Float32Array, index: ArrayLike<number>, skip?: Uint8Array) => (px: number, py: number, pz: number, out: ClosestPoint) => ClosestPoint;
+/**
+ * Binds a face model's vertices (canonical head frame, cm, flat) to the
+ * filled canonical face: each takes the canonical UV of its closest surface
+ * point. Pure; run once per mesh.
+ */
+export declare const bindFaceReprojection: (positions: ArrayLike<number>, { falloff, openings }?: FaceReprojectionBindingOptions) => FaceReprojectionBinding;
+/**
+ * Which part of the camera face to take: the whole face, or only the eyes
+ * and / or the mouth (soft ellipses around the openings, eyelids and lips
+ * included) — the classic "your eyes and mouth on a character".
+ */
+export type FaceReprojectionRegion = "face" | "eyes" | "mouth" | "eyesAndMouth";
+/**
+ * The region ellipses in the canonical head frame (cm): `[x, y, radiusX,
+ * radiusY]` for the left eye, the right eye and the mouth.
+ */
+export declare const faceReprojectionRegionEllipses: () => [number, number, number, number][];
+/** Region switches `[leftEye, rightEye, mouth, all]` for a `FaceReprojectionRegion`. */
+export declare const faceReprojectionRegionMask: (region: FaceReprojectionRegion) => [number, number, number, number];
+/**
+ * How a model's material shows the reprojected face:
+ * - `"unlit"` (default) — as it is in the camera image (already lit by the
+ *   room), so it reads as the real face;
+ * - `"lit"` — as the material's base colour, shaded by the scene lights.
+ */
+export type FaceReprojectionShading = "unlit" | "lit";
+/** The uniforms a patched material reads (shared, so one update reaches every material). */
+export type FaceReprojectionUniforms = {
+    faceReprojectionMap: {
+        value: THREE.Texture | null;
+    };
+    /** 0..1, how much of the camera face shows. */
+    faceReprojectionAmount: {
+        value: number;
+    };
+    /** 1 = lit, 0 = unlit. */
+    faceReprojectionLit: {
+        value: number;
+    };
+    /** 0..1, skin fill beyond the face (materials patched with `fill`; needs a mipmapped map). */
+    faceReprojectionFill: {
+        value: number;
+    };
+    /** cm from the face where the fill has faded out (it fades over the last 20 %). */
+    faceReprojectionFillReach: {
+        value: number;
+    };
+    /** The map's texels per cm of canonical face (`faceUnwrapTexelsPerCm`): sets how fast the fill blurs. */
+    faceReprojectionFillTexelsPerCm: {
+        value: number;
+    };
+};
+export declare const createFaceReprojectionUniforms: () => FaceReprojectionUniforms;
+/** Default reach of the skin fill, cm from the face: the whole head and neck of a life-size model. */
+export declare const FACE_REPROJECTION_FILL_REACH = 30;
+/**
+ * Texels of an unwrap `resolution` px wide per cm of canonical face (the
+ * canonical layout's width in UV over its width in cm). The skin fill blurs
+ * by about one texel-cm per cm from the face.
+ */
+export declare const faceUnwrapTexelsPerCm: (resolution: number) => number;
+/**
+ * Patches a built-in three.js material (standard, physical, lambert, phong,
+ * toon, basic …) to wear a reprojected face texture over its own colour: the
+ * texture (premultiplied alpha, in the mesh's own UV layout) covers the base
+ * colour where its alpha is, unlit as emissive or lit as base colour. Use it
+ * on a material you own (clone a shared one first).
+ *
+ * `{ attributes: true }` reads the UV and the coverage from the geometry's
+ * `faceUv` / `faceCoverage` attributes instead (pass the UNWRAP texture as the
+ * map): a mesh bound to the face needs no remap pass. `faceUv` must be in the
+ * unwrap's layout: `binding.canonicalUv` for the default canonical layout,
+ * `writeFaceReprojectionLayoutUv(binding, uvs)` for a reprojector made with
+ * `uvs`. A mismatch draws a scrambled face, with no error.
+ *
+ * `{ attributes: true, fill: true }` also fills the skin beyond the face (the
+ * `faceReprojectionFill*` uniforms; see `FACE_REPROJECTION_FILL_GLSL`) and
+ * reads a `faceDistance` attribute: each vertex's distance from the
+ * canonical face, cm (`Math.abs(binding.distance[i])`). The map must be
+ * mipmapped for it.
+ */
+export declare const patchFaceReprojectionMaterial: (material: THREE.Material, uniforms: FaceReprojectionUniforms, { attributes, fill }?: {
+    attributes?: boolean;
+    fill?: boolean;
+}) => void;

package/dist/face-character/faceReprojector.d.ts

@@ -0,0 +1,171 @@
+import { FaceImageLandmark, FaceOpening, FaceReprojectionBindingOptions, FaceReprojectionRegion, FaceUnwrapFrameOptions } from './faceReprojection';
+import * as THREE from "three";
+/** One mesh to reproject onto: its geometry (with a `uv`) and its vertices in the canonical head frame. */
+export type FaceReprojectionTarget = {
+    geometry: THREE.BufferGeometry;
+    /** The geometry's vertices in the canonical head frame (cm, flat), for the binding. */
+    canonical: ArrayLike<number>;
+    /** Which filled openings it binds to (see `FaceReprojectionBindingOptions.openings`). Default all. */
+    openings?: readonly FaceOpening[];
+};
+export type FaceReprojectorOptions = FaceUnwrapFrameOptions & FaceReprojectionBindingOptions & {
+    /** The output texture's size (px, square). Default 1024. */
+    resolution?: number;
+    /** The unwrapped canonical face texture's size (px, square). Default 512. */
+    unwrapResolution?: number;
+    /** Edge padding around the model's UV islands, px (0–4). Default 2. */
+    padding?: number;
+    /**
+     * The unwrap's UV layout: one `[u, v]` per landmark (v up, at least 468
+     * pairs). Default `CANONICAL_FACE_UVS` (face characters, `FaceMorph`).
+     * Pass `FACE_ATLAS_UVS` to unwrap into the face atlas (face swap, makeup
+     * art). The remap reads the unwrap in the same layout, so targets
+     * (`setTargets`, `texture`) still get their own atlas.
+     *
+     * The canonical-layout paths do not follow it:
+     * `bindFaceReprojection(...).canonicalUv`, a `faceUv` attribute and
+     * `patchFaceReprojectionMaterial(..., { attributes: true })` read
+     * `unwrapTexture` in the canonical layout. With `uvs`, wear the face
+     * through `setTargets` / `texture`, or convert a binding with
+     * `writeFaceReprojectionLayoutUv(binding, uvs)`.
+     */
+    uvs?: ArrayLike<number>;
+    /** Mipmap the unwrap, for reading it smaller than it is (sRGB, so the mips average in linear light). Default `false`. */
+    unwrapMipmaps?: boolean;
+    /**
+     * Fill skin the camera does not see (the far side of a turned face) from
+     * the other side, once, when the unwrap is made: a second draw samples
+     * each point's mirror twin and fills only what the first draw left
+     * uncovered, so a face seen square on is unchanged. Points outside the
+     * image count as unseen (`inFrame` defaults to on with it), so the twin
+     * fills them too. Default `false`.
+     */
+    mirrorFill?: boolean;
+    /**
+     * Edge padding of the unwrap, px (0–16). Default 0. It pads alpha as
+     * well: coverage grows by up to this many px at the face's edge and into
+     * unseen holes (spots that neither the camera nor `mirrorFill` saw), so
+     * padded texels count as seen.
+     */
+    unwrapPadding?: number;
+};
+/** The largest `unwrapPadding` (px). */
+export declare const FACE_UNWRAP_MAX_PADDING = 16;
+/**
+ * The filled canonical face laid out in an unwrap layout (see
+ * `getFaceUnwrapUvs`): `position` = the layout UV (z 0), `canonical` = the
+ * rest position (cm), and per-frame `cameraUv` (2) and `weight` (1), ready
+ * for `writeFaceUnwrapFrame`. Shared attributes can be passed to make a
+ * second geometry over the same buffers (only `cameraUv` and `weight` are its
+ * own). The caller disposes it.
+ */
+export declare const createFaceUnwrapGeometry: (uvs?: ArrayLike<number>, share?: THREE.BufferGeometry) => THREE.BufferGeometry;
+/**
+ * Renders the live camera face into a face model's own UV layout (see
+ * `faceReprojection.ts`): `unwrapTexture` holds the camera face in the
+ * unwrap layout (`uvs`, default the canonical face UVs), `texture` the same
+ * face in the targets' layout. Both are premultiplied-alpha, transparent
+ * where there is no face. Call `render` once per new camera frame (or per new
+ * image); `dispose` when done. No React needed.
+ */
+export declare class FaceReprojector {
+    readonly unwrapTarget: THREE.WebGLRenderTarget;
+    readonly target: THREE.WebGLRenderTarget;
+    /** The remap before edge padding. */
+    private readonly remapTarget;
+    /** The unwrap before its edge padding (made on first use). */
+    private unwrapRawTarget;
+    private readonly padUniforms;
+    private readonly padScene;
+    private readonly padMaterial;
+    private readonly unwrapPadUniforms;
+    private readonly unwrapPadScene;
+    private readonly unwrapPadMaterial;
+    readonly unwrapUniforms: {
+        cameraMap: {
+            value: THREE.Texture | null;
+        };
+        regions: {
+            value: THREE.Vector4[];
+        };
+        regionMask: {
+            value: THREE.Vector4;
+        };
+        regionSoftness: {
+            value: number;
+        };
+        /** 1: drop samples past the image's edge (`inFrame`). */
+        inFrame: {
+            value: number;
+        };
+    };
+    readonly remapUniforms: {
+        unwrapMap: {
+            value: THREE.Texture | null;
+        };
+        maskMap: {
+            value: THREE.Texture | null;
+        };
+        useMask: {
+            value: number;
+        };
+        canonicalMaskMap: {
+            value: THREE.Texture | null;
+        };
+        useCanonicalMask: {
+            value: number;
+        };
+    };
+    private readonly camera;
+    private readonly unwrapScene;
+    private readonly remapScene;
+    private readonly unwrapGeometry;
+    private readonly unwrapMaterial;
+    /** `mirrorFill`'s second draw: the same mesh, sampling each vertex's mirror twin. */
+    private readonly mirrorGeometry;
+    private readonly mirrorMesh;
+    private readonly mirrorMaterial;
+    private readonly remapMaterial;
+    private remapMeshes;
+    /** Each remap mesh's binding (to re-lay its `canonicalUv` when `uvs` changes). */
+    private remapBindings;
+    /** The unwrap layout (`getFaceUnwrapUvs(options.uvs)`). */
+    private layout;
+    private options;
+    /** The frame options `render` passes on (one object, reused). */
+    private readonly frame;
+    constructor(options?: FaceReprojectorOptions);
+    /** The face model's texture: the camera face in the targets' UV layout. */
+    get texture(): THREE.Texture;
+    /** The camera face in the unwrap layout (`uvs`; default the canonical face UVs). */
+    get unwrapTexture(): THREE.Texture;
+    /**
+     * Changes the options. Sizes resize the textures; `uvs` re-lays the unwrap
+     * and the bound targets; a `falloff` change needs `setTargets` again.
+     */
+    setOptions(options: FaceReprojectorOptions): void;
+    /** Which part of the face to take (see `FaceReprojectionRegion`). */
+    setRegion(region: FaceReprojectionRegion): void;
+    /**
+     * Optional masks (their red channel): `mask` in the targets' own UV layout
+     * (loaded like the model's own map — glTF textures have `flipY = false`),
+     * `canonicalMask` in the unwrap layout (`uvs`; default the canonical face UVs).
+     */
+    setMasks(mask: THREE.Texture | null, canonicalMask: THREE.Texture | null): void;
+    /** The meshes whose UV layout the output follows (they share one atlas). Binds them (once). */
+    setTargets(targets: readonly FaceReprojectionTarget[]): void;
+    /** A remap mesh's `canonicalUv`: where each vertex reads the unwrap, in its layout. */
+    private writeRemapUv;
+    /**
+     * Renders one frame: `cameraTexture` is the session's camera image (as the
+     * tracker saw it), `landmarks` the tracked face's (≥ 468, normalized image
+     * space). Any image works the same way (a photo in a `CanvasTexture` with
+     * its detected landmarks). Leaves the renderer's target and clear colour as
+     * they were.
+     */
+    render(renderer: THREE.WebGLRenderer, cameraTexture: THREE.Texture, landmarks: ArrayLike<FaceImageLandmark>): void;
+    private rawUnwrapTarget;
+    private restore;
+    private clearTargets;
+    dispose(): void;
+}

package/dist/face-character/faceRig.d.ts

@@ -0,0 +1,176 @@
+import { LandmarkLead } from '../face-atlas/lead';
+import { FaceInfo, FaceInfoTarget } from '../face-info';
+import { LandmarkPoseSmoothingState } from '../components/HeadOccluder/useLandmarkPoseFit';
+import { XRModelNodeFaceTracking } from '../types/nodes';
+import * as THREE from "three";
+/** Number of expression channels (`FACE_MORPH_NAMES`). */
+export declare const FACE_MORPH_COUNT: number;
+/**
+ * Where a face rig stands: following a tracked face, holding its last pose
+ * through a short dropout, or lost (hidden).
+ */
+export type FaceRigTracking = "tracked" | "held" | "lost";
+export type FaceRigOptions = {
+    /**
+     * Per-frame EMA factor for the head pose while the head is still, `1` = no
+     * smoothing. Adaptive: fast head motion follows immediately (full speed at
+     * `FACE_RIG_FAST_TURN_DEG` per frame), so a quick shake does not trail.
+     * Default 0.5.
+     */
+    smoothing?: number;
+    /**
+     * Per-frame EMA factor for the expression (the per-landmark offsets), `1` =
+     * none. MediaPipe's landmark depth is noisy; a little smoothing keeps a
+     * bound mesh calm. Default 0.6.
+     */
+    expressionSmoothing?: number;
+    /** Keep the last pose and expression through dropouts shorter than this (ms). Default 250. */
+    holdMs?: number;
+    /**
+     * The face at rest, subtracted from the offsets so a model keeps its OWN
+     * shape and only the expression moves it:
+     * - `"auto"` (default) — captured over the first `neutralMs` after the face
+     *   is found (look at the camera with a relaxed face; `recalibrateFaceRig`
+     *   captures again);
+     * - `"none"` — keep the person's face shape too (the mesh conforms to the
+     *   face: wider eyes, a longer jaw …).
+     */
+    neutral?: "auto" | "none";
+    /** How long the neutral capture averages over (ms). Default 600. */
+    neutralMs?: number;
+    /**
+     * Landmark lead (ms), read by `FaceRig` / `stepFaceRigFromModel` (not by
+     * `stepFaceRig`). Inference runs below the render rate, so between two
+     * samples the landmarks hold while the camera image moves on. Above 0, the
+     * landmarks go through a `LandmarkLead` first: a One Euro filter (steady
+     * when still, quick when moving) plus a velocity lead of at most this long,
+     * so geometry drawn from the rig keeps up with the camera image. About one
+     * inference interval suits (33 ms at 30 Hz). Default 0: the raw landmarks,
+     * as before. Makeup's own rigs use 33 / 42 / 66 ms by quality tier.
+     */
+    leadMs?: number;
+};
+/**
+ * One face's live state in the canonical head frame, updated every frame by
+ * `stepFaceRig` (`FaceRig` does it from the tracker). Everything a face
+ * character needs: where the head is, and how the face has moved within it.
+ */
+export type FaceRigState = {
+    tracking: FaceRigTracking;
+    /** Which tracked face drives it (set by `FaceRig`). */
+    faceIndex: number;
+    /** Last time a face was seen (ms), or `null`. */
+    lastSeenMs: number | null;
+    /**
+     * The head pose, canonical centimetres → world: `world = position +
+     * quaternion · (scale · canonical)`. Smoothed; snaps on (re)acquire.
+     */
+    pose: LandmarkPoseSmoothingState;
+    /**
+     * The live landmarks in the head frame of THIS frame's raw fit (canonical
+     * cm, flat, 468 × 3): what the expression is measured on.
+     */
+    local: Float32Array;
+    /**
+     * The live landmarks in the frame of the SMOOTHED `pose` — where they are
+     * on screen once drawn inside the rig (cm, flat, 468 × 3). Content that must
+     * sit exactly on the camera image (a warped or morphing face, a pin on the
+     * skin) uses these: `local` drawn through the smoothed pose trails a fast
+     * turn.
+     */
+    view: Float32Array;
+    /**
+     * The expression: live minus the face at rest per landmark (canonical cm,
+     * flat, 468 × 3), smoothed — the rest being the captured neutral face (or
+     * the canonical face with `neutral: "none"`). Near zero on the rigid
+     * landmarks; the jaw, lips, cheeks, brows and lids carry it. Zero while the
+     * neutral is being captured and when lost.
+     */
+    residual: Float32Array;
+    /** The captured neutral offsets (person's face shape − canonical, cm, flat). */
+    neutral: Float32Array;
+    /**
+     * The expression channels, 0..1, in `FACE_MORPH_NAMES` order (MediaPipe
+     * blendshapes): smoothed, with the person's resting values removed (a
+     * resting squint of 0.1 reads 0; a full blink still reads 1). Zero while
+     * the neutral is being captured and when lost or without scores.
+     */
+    morphs: Float32Array;
+    /** The resting blendshape scores captured with the neutral. */
+    morphNeutral: Float32Array;
+    /**
+     * The latest raw face (MediaPipe's blendshapes as reported, the head
+     * rotation reading, landmarks) — for Face Actions and custom logic; kept
+     * through a hold, `null` when lost. `FaceRig` fills it; `stepFaceRig` only
+     * clears it.
+     */
+    face: FaceInfo | null;
+    /** `"capturing"` until the neutral is averaged, then `"ready"` (always `"ready"` with `neutral: "none"`). */
+    neutralState: "capturing" | "ready";
+    /** When the current neutral capture started (ms), or `null` before the first tracked frame. */
+    neutralSince: number | null;
+    /** Frames averaged into `neutral` so far. */
+    neutralFrames: number;
+};
+export declare const createFaceRigState: () => FaceRigState;
+/**
+ * Captures the neutral face again from the next tracked frames (call it while
+ * the person looks at the camera with a relaxed face). With `neutral: "auto"`
+ * this also happens on its own each time the face is found.
+ */
+export declare const recalibrateFaceRig: (state: FaceRigState) => void;
+/**
+ * Head motion per frame at which the pose stops smoothing and follows the
+ * tracker directly: this many degrees of turn, or `FACE_RIG_FAST_MOVE_CM` of
+ * travel. In between, the smoothing eases off in proportion.
+ */
+export declare const FACE_RIG_FAST_TURN_DEG = 6;
+export declare const FACE_RIG_FAST_MOVE_CM = 1.5;
+/**
+ * One frame of a face rig. `world` is the face's 468 landmarks in world space
+ * (flat; each unprojected on its own depth plane, as the head fit does), or
+ * `null` when no face is tracked this frame. Solves the head pose from the
+ * rigid landmarks, smooths it, re-expresses every landmark in the head frame
+ * and smooths the per-landmark expression offsets. `scores` are the face's
+ * blendshape scores in `FACE_MORPH_NAMES` order (0..1), when the tracker has
+ * them. Returns `"found"` / `"lost"` on a tracking edge, else `null`.
+ * Allocation-free.
+ */
+export declare const stepFaceRig: (state: FaceRigState, world: ArrayLike<number> | null, nowMs: number, { smoothing, expressionSmoothing, holdMs, neutral, neutralMs, }?: FaceRigOptions, scores?: ArrayLike<number> | null) => "found" | "lost" | null;
+/**
+ * One rig's working memory for `stepFaceRigFromModel`: the rig state plus
+ * the scratch it fills every frame. Create one per rig and keep it.
+ */
+export type FaceRigDriver = {
+    /** The rig it steps. */
+    readonly rig: FaceRigState;
+    /** The landmarks in world space, flat 468 × 3 (each on its own depth plane). */
+    readonly world: Float64Array;
+    /** Blendshape scores in `FACE_MORPH_NAMES` order. */
+    readonly scores: Float32Array;
+    /** Storage for `rig.face`. */
+    readonly faceInfo: FaceInfoTarget;
+    /** The landmark lead, created on the first step with `leadMs` > 0. */
+    lead: LandmarkLead | null;
+    /** The landmark array the lead last observed (a new array = a new inference). */
+    leadSample: unknown;
+};
+/** A driver for `rig` (a new rig state by default). */
+export declare const createFaceRigDriver: (rig?: FaceRigState) => FaceRigDriver;
+/**
+ * Restarts a driver's rig for another face source (a new camera, another
+ * video): captures the neutral again, snaps the pose and the landmark lead.
+ */
+export declare const resetFaceRigDriver: (driver: FaceRigDriver) => void;
+/**
+ * One frame of a face rig driven by the face model: `FaceRig`'s step without
+ * React. Reads face `faceIndex` from `node` (the shared face model's node),
+ * unprojects each landmark through `camera` on its own depth plane (the
+ * landmark z is in feed-width units around the head centre, as the head fit
+ * reads it), runs the landmark lead when `options.leadMs` > 0 (snapping it
+ * when a lost face is found again), then
+ * `stepFaceRig` with the blendshape scores, and refreshes `rig.face`. Returns
+ * `"found"` / `"lost"` on a tracking edge, else `null`. Allocation-free
+ * after the lead is created.
+ */
+export declare const stepFaceRigFromModel: (driver: FaceRigDriver, node: XRModelNodeFaceTracking | null | undefined, faceIndex: number, camera: THREE.Camera, nowMs: number, options?: FaceRigOptions) => "found" | "lost" | null;