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

package/dist/face-atlas/glsl/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * GLSL chunks for makeup shaders (FACE-1).
+ *
+ * `atlasVertex` is the whole vertex shader of a layer on the face-atlas
+ * surface (`FaceAtlasLayer`): it writes every varying the fragment chunks
+ * read. For the fragment shader, concatenate these in order, then your
+ * `main()`:
+ *
+ * `common` → `shading` → `sparkle` → `finish` → `shapes`
+ *
+ * ```glsl
+ * void main() {
+ *   MakeupSample s = makeupSample();           // first: it takes derivatives
+ *   float mask = blushShape(s.rest);           // or your own shape
+ *   makeupOutput(s, makeupFinish(s, makeupShade(s), mask));
+ * }
+ * ```
+ *
+ * With a mask, split the sample around an early out, so fragments outside
+ * the shape read no texture:
+ *
+ * ```glsl
+ * MakeupSample s = makeupSampleGeometry();     // derivatives, rest point, fades
+ * float mask = blushShape(s.rest);
+ * if (mask * s.fade < 1.0 / 255.0) discard;
+ * makeupSampleColor(s);                        // camera and skin, explicit LODs
+ * ```
+ *
+ * `common` alone with `shading` is enough for a matte layer:
+ * `makeupOutput(s, makeupDiffuse(s, uColor, uCoverage), mask * s.fade * uOpacity, vec3(0.0))`.
+ * Draw with `MAKEUP_BLENDING` (premultiplied over). A custom vertex side
+ * declares `MAKEUP_VARYINGS_GLSL` and writes every varying in it.
+ *
+ * `design` (after `common`) samples creator art in the face atlas
+ * (`MakeupDesign`): `makeupDesignSample(s.uv)` returns linear rgb and
+ * straight alpha, flipped on mirrored feeds so each side stays on the
+ * person's own side. Call it before any `discard`.
+ *
+ * `eyes` (after `shapes`) holds the eye regions' masks (`Eyeshadow`,
+ * `Eyeliner`, `Brows`): `eyelinerShape`, `eyeshadowZones` / `eyeshadowMask`
+ * / `eyeshadowColor`, and `browGeometry` / `browReach` / `browMask`, on the
+ * rest point in canonical cm, with blink fades from `uBlink`.
+ */
+export declare const MAKEUP_GLSL: Readonly<{
+    atlasVertex: string;
+    common: string;
+    shading: string;
+    sparkle: string;
+    finish: string;
+    shapes: string;
+    design: "\nuniform sampler2D uDesignMap;\nuniform float uDesignSrgb;\nuniform float uDesignPremultiplied;\n\n// The art's uv on this feed: (1 - u, v) on a mirrored feed (uPersonLeftSign < 0).\nvec2 makeupDesignUv(vec2 uv) {\n  return vec2(uPersonLeftSign < 0.0 ? 1.0 - uv.x : uv.x, uv.y);\n}\n\nvec3 makeupDesignDecode(vec3 c) {\n  vec3 low = c / 12.92;\n  vec3 high = pow((c + 0.055) / 1.055, vec3(2.4));\n  return mix(low, high, step(vec3(0.04045), c));\n}\n\n// The art at an atlas uv: linear rgb, straight alpha. Implicit derivatives: call before any discard.\nvec4 makeupDesignSample(vec2 uv) {\n  vec4 texel = texture(uDesignMap, makeupDesignUv(uv));\n  float a = clamp(texel.a, 0.0, 1.0);\n  vec3 c = uDesignPremultiplied > 0.5 ? texel.rgb / max(a, 1e-4) : texel.rgb;\n  c = clamp(c, 0.0, 1.0);\n  return vec4(uDesignSrgb > 0.5 ? makeupDesignDecode(c) : c, a);\n}\n";
+    eyes: string;
+}>;
+export { MAKEUP_VARYINGS_GLSL } from './common';
+export { FACE_ATLAS_ATTRIBUTES_GLSL, FACE_SKIN_STATS_TEXELS } from './atlasVertex';
+export { createMakeupShadingUniforms, type MakeupShadingUniforms } from './uniforms';
+export { createMakeupShapeUniforms, type MakeupShapeUniforms } from './shapes';
+export { createMakeupDesignUniforms, type MakeupDesignUniforms } from './design';
+export { createMakeupEyeUniforms, type MakeupEyeUniforms } from './eyes';

package/dist/face-atlas/glsl/shading.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `MAKEUP_GLSL.shading` (after `common`): skin-relative light terms, the
+ * diffuse (sheer / opaque coverage), auto shades and the output operator.
+ * Mirrors `makeupLighting`, `makeupDiffuse`, `makeupAutoShade` and
+ * `makeupOutput` in `lib/face-atlas/shading.ts`.
+ *
+ * - `S = lum(C) / lum(Rs)`: light on this pixel relative to the GLOBAL
+ *   settled skin, so a side-lit face keeps its shadow side and skin tone
+ *   never enters the paint.
+ * - `L` (local low-pass) only clips the skin's own shine out of the diffuse
+ *   (`Sd`) and measures the real highlight `Hcam`.
+ * - `makeupOutput` writes premultiplied `(k·enc(D) + enc(base+H) − enc(base), k)`;
+ *   draw it with `MAKEUP_BLENDING` (One, OneMinusSrcAlpha): opacity is linear.
+ */
+export declare const MAKEUP_SHADING_GLSL: string;

package/dist/face-atlas/glsl/shapes.d.ts

@@ -0,0 +1,66 @@
+import * as THREE from "three";
+/**
+ * `MAKEUP_GLSL.shapes` (after `common`, `shading`, `sparkle` and `finish`):
+ * the region shapes, evaluated per fragment on the rest position (canonical
+ * cm). Mirrors `lib/face-atlas/shapes.ts`.
+ *
+ * Face regions (blush, contour, highlighter) are up to `MAKEUP_SHAPE_MAX`
+ * soft tapered capsules, set as uniforms from the settings (shape, size,
+ * lift), so a shape or size change never recompiles:
+ *
+ * - `uShapeStart[i]` / `uShapeEnd[i]`: `xyz` the capsule's ends on the
+ *   canonical −X half (cm), `w` the radius there; `uShapeWeight[i]` its
+ *   strength; `uShapeCount` the capsules in use.
+ * - `uSoftness`: the edge profile, `1 − smoothstep(1 − s, 1 + s, d / r)`.
+ * - `uEyeGuard`: `(start, full)` in `eyeRing` hops: fades the shape off the
+ *   lash line and lids (start ≥ full: off).
+ * - `uLipGuard`: the `lipEdge` where the shape is full: fades it to 0 on the
+ *   outer lip line, where the lips' own triangles (never drawn by a face
+ *   region) begin, so no shape ends at a hard edge there (0: off).
+ *
+ * The rest point is folded onto the −X half (`x → −|x|`), so shapes are
+ * mirror-symmetric; `s.fade` (from `makeupSample()`) applies the person's
+ * own sides. Capsules combine as a soft union, `1 − Π(1 − wᵢ·mᵢ)`.
+ *
+ * `blushShape`, `contourShape` and `highlighterShape` are the region masks
+ * custom materials call (`blushShape(s.rest)`); all three read the same
+ * uniforms, which each region's material holds for its own shape.
+ */
+export declare const MAKEUP_SHAPES_GLSL: string;
+/**
+ * The uniforms `MAKEUP_GLSL.shapes` declares, empty (no capsules: the mask is
+ * 0). `uShapeStart` / `uShapeEnd` / `uShapeWeight` hold Float32Arrays whose
+ * identity never changes (`packMakeupShapePrimitives` writes into them).
+ */
+export declare const createMakeupShapeUniforms: () => {
+    /** `[x, y, z, radius]` per capsule: the start, canonical −X half, cm. */
+    uShapeStart: {
+        value: Float32Array<ArrayBuffer>;
+    };
+    /** `[x, y, z, radius]` per capsule: the end. */
+    uShapeEnd: {
+        value: Float32Array<ArrayBuffer>;
+    };
+    /** Each capsule's strength, 0..1. */
+    uShapeWeight: {
+        value: Float32Array<ArrayBuffer>;
+    };
+    /** Capsules in use. */
+    uShapeCount: {
+        value: number;
+    };
+    /** Edge feather, 0..1 (`softness`). */
+    uSoftness: {
+        value: number;
+    };
+    /** `(start, full)` of the eye guard in `eyeRing` hops; `(0, 0)` is off. */
+    uEyeGuard: {
+        value: THREE.Vector2;
+    };
+    /** The `lipEdge` where the shape is full (the lip guard); 0 is off. */
+    uLipGuard: {
+        value: number;
+    };
+};
+/** The uniforms `MAKEUP_GLSL.shapes` reads. */
+export type MakeupShapeUniforms = ReturnType<typeof createMakeupShapeUniforms>;

package/dist/face-atlas/glsl/sparkle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `MAKEUP_GLSL.sparkle` (after `common`): antialiased flakes for shimmer and
+ * glitter. Mirrors `makeupFlakes` in `lib/face-atlas/shading.ts` (the hash
+ * is integer PCG3D, bit-exact with the mirror).
+ *
+ * - Flakes hash 3D cells of the rest position (canonical cm), so they stick
+ *   to the skin. A flake is a sphere inside its cell; the rest-space facet
+ *   slices it into a disc whose edge ramp integrates to the disc's exact area,
+ *   so the mean coverage is the flake volume fraction (Delesse).
+ * - Flake normals follow a von Mises-Fisher distribution (concentration
+ *   kappa) around the rest-normal-times-pose, in a frame tied to the head's
+ *   up, so a still face keeps its sparkle pattern. The glint is
+ *   `exp(sharpness * (dot(nf, h) - 1))`, whose mean over the flake normals has
+ *   a closed form.
+ * - A flake smaller than `MAKEUP_FLAKES.resolveFullPx` (1.5 px) fades to that
+ *   expected value (fully at `resolveStartPx`, 0.75 px), so the mean energy is
+ *   the same at every pixel size. `quality` 0 always returns the expected value.
+ */
+export declare const MAKEUP_SPARKLE_GLSL: string;

package/dist/face-atlas/glsl/uniforms.d.ts

@@ -0,0 +1,106 @@
+import * as THREE from "three";
+/**
+ * Every uniform `MAKEUP_GLSL.common` and `MAKEUP_GLSL.atlasVertex` declare,
+ * with neutral defaults: a white matte layer at full opacity on both sides,
+ * no skin data (`uSkinMap` and `uSkinStats` null; the probe's readiness
+ * comes through the vertex stats). Colours are linear (`THREE.Color.set("#hex")`
+ * converts from sRGB). Spread `useFaceSkin().uniforms` after these to bind
+ * the probe (`uSkinMap`, `uSkinLod`, `uSkinSqrt`, `uSkinStats`,
+ * `uSkinStatsPacked`).
+ */
+export declare const createMakeupShadingUniforms: () => {
+    /** The camera feed (an sRGB texture, so samples are linear). */
+    uCameraMap: {
+        value: THREE.Texture | null;
+    };
+    /**
+     * The skin probe's statistics (`FACE_SKIN_STATS_TEXELS`), read by the
+     * atlas vertex chunk. Null binds three's 1×1 empty texture, which reads as
+     * "not ready"; a sampler missing from the material would read texture
+     * unit 0 (often the camera) as the probe.
+     */
+    uSkinStats: {
+        value: THREE.Texture | null;
+    };
+    /**
+     * 1 when `uSkinStats` is the packed RGBA8 layout (three bytes per value,
+     * `FaceSkinProbe.statsFormat` "packed"), 0 for float stats.
+     */
+    uSkinStatsPacked: {
+        value: number;
+    };
+    /** `FaceSkinProbe.skinMap`: atlas, premultiplied linear `(c·w, w)`, mipmapped. */
+    uSkinMap: {
+        value: THREE.Texture | null;
+    };
+    /** The low-pass mip of `uSkinMap`: `makeupSkinLod(probeSize)` (2 at 128², 1 at 64²). */
+    uSkinLod: {
+        value: number;
+    };
+    /** 1 when the probe fell back to RGBA8: rgb holds `w·√c` (the root before premultiplying). */
+    uSkinSqrt: {
+        value: number;
+    };
+    /** P: the shade, linear. */
+    uColor: {
+        value: THREE.Color;
+    };
+    /** `MAKEUP_AUTO_SHADE_ID`; 0 uses `uColor`. */
+    uAutoShade: {
+        value: number;
+    };
+    /**
+     * Pigment amount, linear: 0.8 renders 80%. Gloss highlights and glitter
+     * flakes follow the mask instead and fade out only below
+     * `MAKEUP_FINISH_MODEL.maskTermsFullOpacity`.
+     */
+    uOpacity: {
+        value: number;
+    };
+    /** 0 sheer (filters the person's colour, never lighter) … 1 opaque. */
+    uCoverage: {
+        value: number;
+    };
+    /** `MAKEUP_FINISH_ID`. */
+    uFinish: {
+        value: number;
+    };
+    /** Finish highlight strength, 0..1. */
+    uShine: {
+        value: number;
+    };
+    /** Flake colour, linear (used when `uSparkleAuto` is 0). */
+    uSparkleColor: {
+        value: THREE.Color;
+    };
+    /** 1 derives the flake colour from the shade (`sparkleColor: ""`). */
+    uSparkleAuto: {
+        value: number;
+    };
+    /** Flake density, 0..1. */
+    uSparkleDensity: {
+        value: number;
+    };
+    /** Flake diameter, mm. */
+    uSparkleSize: {
+        value: number;
+    };
+    /** 1 on the high and medium tiers, 0 on low. */
+    uSparkleQuality: {
+        value: number;
+    };
+    /** `(leftOn, rightOn)`: the person's own sides. */
+    uSide: {
+        value: THREE.Vector2;
+    };
+    /** #298 `personLeftSign(mirrored)`: +1 unmirrored, −1 on the mirrored webcam. */
+    uPersonLeftSign: {
+        value: number;
+    };
+    /** The hold / hide fade, 0..1. */
+    uPresence: {
+        value: number;
+    };
+};
+/** The uniforms `MAKEUP_GLSL.common` reads. */
+export type MakeupShadingUniforms = ReturnType<typeof createMakeupShadingUniforms>;

package/dist/face-atlas/guide.d.ts

@@ -0,0 +1,51 @@
+import { FaceAtlasRegion } from './regions';
+/**
+ * Atlas UV → pixel in a `size`-pixel square image. Images load with `flipY`,
+ * so `v = 1` is the image's top row.
+ */
+export declare const faceAtlasUvToPixel: (u: number, v: number, size: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * The same point of the face on the other side: `(1 − u, v)`. Exact for the
+ * face atlas (its layout is symmetric to 0.001), so art can be mirrored by
+ * flipping the image horizontally. Not valid for `CANONICAL_FACE_UVS`.
+ */
+export declare const mirrorFaceAtlasUv: (u: number, v: number) => {
+    u: number;
+    v: number;
+};
+export type FaceAtlasGuideOptions = {
+    /** Pixel size of the square canvas the guide represents. Default 1024. */
+    size?: number;
+    /** Regions to outline and tint. Default every region except `face` and `skin`. */
+    regions?: readonly FaceAtlasRegion[];
+    /** Draw the whole triangle wireframe. Default true. */
+    wireframe?: boolean;
+    /** Draw the title, region names and side labels. Default true. */
+    labels?: boolean;
+    /** Fill the canvas with a colour. Omit for a transparent background. */
+    background?: string;
+};
+export declare const FACE_ATLAS_GUIDE_COLORS: Readonly<Record<FaceAtlasRegion | "wireframe" | "text" | "frame", string>>;
+/**
+ * A creator template of the face atlas as an SVG string: every region's
+ * triangles tinted and outlined, the wireframe, and which side of the image
+ * is which side of the person. Derived from the bundled atlas data, so it
+ * registers exactly with what the SDK samples.
+ */
+export declare const createFaceAtlasGuideSvg: (options?: FaceAtlasGuideOptions) => string;
+/** The guide as an `image/svg+xml` data URL, loadable with `THREE.TextureLoader` or an `<img>`. */
+export declare const createFaceAtlasGuideDataUrl: (options?: FaceAtlasGuideOptions) => string;
+/**
+ * Rasterize a square guide SVG to a PNG `Blob` in the browser (an `<img>` and
+ * a 2D canvas). Shared by the atlas guide and the face-texture guide; `name`
+ * prefixes the error messages.
+ */
+export declare const rasterizeGuideSvg: (svg: string, size: number, name: string) => Promise<Blob>;
+/**
+ * Rasterize the guide to a PNG `Blob` in the browser (an `<img>` and a 2D
+ * canvas), for download or as a texture. Transparent unless `background` is set.
+ */
+export declare const createFaceAtlasGuidePngBlob: (options?: FaceAtlasGuideOptions) => Promise<Blob>;

package/dist/face-atlas/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The face atlas: the SDK's one texture layout for painting on the face
+ * (makeup, face swap, faceless, LipEffect designs). It is the canonical face
+ * OBJ's `vt` layout, bundled as generated data, plus regions, feature lines,
+ * static vertex attributes, masks and the creator guide. SDK modules import
+ * from here; the public subset is re-exported from `entries/face-effects.ts`.
+ * The live-surface registry (`./registry`) and the GLSL chunks (`./glsl`)
+ * are imported by path: they pull in the face rig and generated shader
+ * text, which a consumer of the atlas data alone should not bundle.
+ */
+export { FACE_ATLAS_EYE_FILLS, FACE_ATLAS_EYE_RINGS, FACE_ATLAS_LIP_RINGS, FACE_ATLAS_MIRROR, FACE_ATLAS_MOUTH_FILL, FACE_ATLAS_NOSTRILS, FACE_ATLAS_OVAL_RING, FACE_ATLAS_SOURCE, FACE_ATLAS_TRIANGLES, FACE_ATLAS_UVS, } from './faceAtlas.generated';
+export { faceAtlasOpenTriangles, getFaceAtlasAttributes, getFaceAtlasLipBand, type FaceAtlasAttributes, } from './attributes';
+export { collectRingBandTriangles, computeEdgeDistance, computeHopDistance, computeRingDistance, computeVertexNormals, triangleIdsToVertices, } from './topology';
+export { FACE_ATLAS_ANCHORS, FACE_ATLAS_POLYLINES, FACE_ATLAS_POLYLINE_NAMES, createFaceAtlasPolylineGlsl, faceAtlasAnchorPosition, mirrorFaceAtlasPolyline, type FaceAtlasAnchorName, type FaceAtlasPolyline, type FaceAtlasPolylineName, } from './polylines';
+export { FACE_ATLAS_REGIONS, getFaceAtlasRegionBounds, getFaceAtlasRegionIndices, getFaceAtlasRegionTriangles, type FaceAtlasRegion, type FaceAtlasRegionSelection, type FaceAtlasUvBounds, } from './regions';
+export { createFaceAtlasMask, createFaceAtlasMaskTexture, faceAtlasMaskToRgba, type FaceAtlasMask, type FaceAtlasMaskOptions, type FaceAtlasMaskTextureOptions, } from './masks';
+export { FACE_ATLAS_CM_PER_UV, FACE_SKIN_MASK, createFaceSkinMask, getFaceSkinMaskTexture, } from './skinMask';
+export { FACE_ATLAS_GUIDE_COLORS, createFaceAtlasGuideDataUrl, createFaceAtlasGuidePngBlob, createFaceAtlasGuideSvg, faceAtlasUvToPixel, mirrorFaceAtlasUv, type FaceAtlasGuideOptions, } from './guide';
+export { LANDMARK_LEAD, LANDMARK_LEAD_COUNT, LandmarkLead, createFaceLandmarkLead, createLandmarkNeighbours, getFaceLandmarkNeighbours, type LandmarkLeadPoint, type LandmarkLeadStep, type LandmarkLeadTuning, type LandmarkNeighbours, } from './lead';
+export { FACE_ATLAS_SURFACE, FACE_ATLAS_SURFACE_ATTRIBUTES, FaceAtlasSurface, faceAtlasSelectionIndices, writeFaceAtlasNormals, type FaceAtlasSurfaceAttributeName, type FaceAtlasSurfaceInput, type FaceAtlasSurfaceTracking, type FaceAtlasTriangleSelection, } from './surface';
+export { FACE_ATLAS_STENCIL, FACE_RETOUCH_RENDER_ORDER, MAKEUP_BLENDING, MAKEUP_RENDER_ORDER, faceAtlasLayerSelfOccludes, } from './renderState';
+export { FACE_ATLAS_PREPASS_STATE, FACE_ATLAS_RESTORE_STATE, createFaceAtlasPrepassMaterial, createFaceAtlasRestoreMaterial, faceAtlasTargetHasStencil, guardFaceAtlasStencilDraw, } from './selfOcclusion';
+export { FACE_ATLAS_QUALITY, resolveFaceAtlasQualityKey, type FaceAtlasQualityKey, } from './quality';
+export { FACE_ATLAS_BLINK_MORPHS, faceAtlasDesignFlipU, faceAtlasSideHalves, makeupSideWeights, type FaceAtlasSide, } from './sides';
+export { MAKEUP_SHAPE_MAX, MAKEUP_SHAPE_SOFTNESS_MIN, createMakeupShapePrimitives, evaluateMakeupShapeMask, faceAtlasSurfacePoint, makeupCapsuleDistance, makeupEyeGuard, makeupLipGuard, makeupShapeProfile, packMakeupShapePrimitives, selectFaceAtlasTriangles, type MakeupCapsule, type MakeupShapePrimitives, } from './shapes';

package/dist/face-atlas/lead.d.ts

@@ -0,0 +1,117 @@
+/** The face mesh landmarks a lead follows by default (MediaPipe's 468, without the iris points). */
+export declare const LANDMARK_LEAD_COUNT = 468;
+/**
+ * Tuning of `LandmarkLead`, set on synthetic jitter and motion at 30 Hz
+ * inference: a still face's jitter drops more than 3×, a steady motion is
+ * followed within a pixel while the lead covers the gap, and on the face
+ * mesh a mouth opening 6 px at 1–3 Hz and a blink trail by under a pixel
+ * (RMS over the inner lips and lash lines). Device tuning may change it.
+ */
+export declare const LANDMARK_LEAD: Readonly<{
+    /** One Euro cutoff (Hz) of a still point: heavy smoothing of MediaPipe's jitter. */
+    minCutoffHz: 0.5;
+    /** Cutoff added per feed width per second of the point's speed: little lag while it moves. */
+    beta: 200;
+    /** Cutoff (Hz) of the speed estimate the cutoff adapts to. */
+    derivativeCutoffHz: 2;
+    /**
+     * Speed (feed widths per second, about 19 px/s on a 640 px feed) below
+     * which a point counts as still: the jitter's own apparent speed, so it
+     * does not open the filter.
+     */
+    speedFloor: 0.03;
+    /** Blend of each sample's velocity into the lead velocity (1 = the last sample's alone). */
+    velocityBlend: 0.5;
+    /** Samples further apart than this (ms) snap: the face was not followed in between. */
+    maxGapMs: 500;
+    /** A jump of the face's centre larger than this (feed widths) snaps: another face. */
+    snapJump: 0.1;
+}>;
+/** The tunable numbers of a `LandmarkLead` (`LANDMARK_LEAD` by default). */
+export type LandmarkLeadTuning = {
+    -readonly [K in keyof typeof LANDMARK_LEAD]: number;
+};
+/**
+ * Each point's mesh neighbours, compressed: the neighbours of point `i` are
+ * `indices[offsets[i] … offsets[i + 1] − 1]` (`createLandmarkNeighbours`).
+ */
+export type LandmarkNeighbours = {
+    offsets: Uint32Array;
+    indices: Uint16Array;
+};
+/** The edge neighbours of every vertex of a triangle list (flat vertex indices, three per triangle). */
+export declare const createLandmarkNeighbours: (triangles: ArrayLike<number>, count: number) => LandmarkNeighbours;
+/** What one `observe` did: snapped to the raw points, filtered them, or skipped the sample. */
+export type LandmarkLeadStep = "snap" | "smooth" | "skip";
+/** A landmark as the face model reports it (`z` optional). */
+export type LandmarkLeadPoint = {
+    x: number;
+    y: number;
+    z?: number;
+};
+/**
+ * One Euro filter plus a capped velocity lead over the first `count` face
+ * landmarks. Call `observe` once per NEW landmark array (not every frame),
+ * then `apply(nowMs, leadMs)` every frame and read `points`.
+ *
+ * ```ts
+ * const lead = new LandmarkLead();
+ * // in useFrame:
+ * if (landmarks !== last) lead.observe(landmarks, performance.now(), aspect);
+ * const points = lead.apply(performance.now(), 33); // x, y, z per landmark
+ * ```
+ */
+export declare class LandmarkLead {
+    /** Points filtered and led: the first `count` landmarks of every sample. */
+    readonly count: number;
+    /** The led points, `count × 3` (x, y, z), written by `apply`. */
+    readonly points: Float32Array;
+    /** The filtered points at the last sample. */
+    private readonly filtered;
+    /** One Euro speed estimate per coordinate (feed units per second). */
+    private readonly derivative;
+    /** Lead velocity per coordinate (feed units per second). */
+    private readonly velocity;
+    /** The filter's lag behind a steadily moving point, per landmark (ms). */
+    private readonly lagMs;
+    private readonly tuning;
+    private readonly neighbours;
+    private initialized;
+    private sampleMs;
+    private centreX;
+    private centreY;
+    constructor(count?: number, { neighbours, ...tuning }?: Partial<LandmarkLeadTuning> & {
+        neighbours?: LandmarkNeighbours | null;
+    });
+    /** False until the first sample and after `reset`: the next sample snaps. */
+    get ready(): boolean;
+    /** Time of the last sample (ms). */
+    get lastSampleMs(): number;
+    /** The next sample snaps (a new face, a new camera source, a reacquired face). */
+    reset(): void;
+    /**
+     * A new landmark sample taken at `timeMs`. Snaps on the first sample, after
+     * `reset`, after a gap over `maxGapMs` and on a face-centre jump over
+     * `snapJump`; skips a sample with too few points or no time step.
+     */
+    observe(landmarks: ArrayLike<LandmarkLeadPoint>, timeMs: number, aspect?: number): LandmarkLeadStep;
+    /**
+     * Writes the led points for `nowMs` into `points` and returns it: each
+     * filtered point moved along its velocity for its filter lag plus the time
+     * since the sample, at most `leadMs`. `leadMs` 0 gives the filtered points.
+     * Before the first sample the points are left as they are.
+     */
+    apply(nowMs: number, leadMs: number): Float32Array;
+    private snap;
+}
+/**
+ * The face mesh's landmark neighbours, built once: the edges of
+ * `FACE_ATLAS_TRIANGLES` without the eye and mouth fills
+ * (`faceAtlasOpenTriangles`). The fills join each lip to the other lip and
+ * each lid to the other lid; those move apart when the mouth or an eye
+ * opens, so their speeds would cancel and hold the filter shut exactly
+ * where the lips and lash lines move.
+ */
+export declare const getFaceLandmarkNeighbours: () => LandmarkNeighbours;
+/** A `LandmarkLead` over the 468 face landmarks, its speeds averaged over mesh neighbours. */
+export declare const createFaceLandmarkLead: (tuning?: Partial<LandmarkLeadTuning>) => LandmarkLead;

package/dist/face-atlas/madeUpCamera.d.ts

@@ -0,0 +1,125 @@
+import * as THREE from "three";
+/**
+ * The made-up camera (FACE-1): the camera image with the makeup drawn over
+ * it, in a feed-size texture laid out exactly as the camera texture (same
+ * uv, same aspect, sRGB). Components that sample the camera image (a face
+ * inset, a face warp or morph, a face swap's live source) can sample it
+ * instead and show the makeup. Opt-in: one shared target per renderer,
+ * rendered once per frame while anyone holds it (`<MadeUpCamera>`,
+ * `useMadeUpCamera`).
+ *
+ * Each frame (`MadeUpCameraTarget.render`):
+ * 1. **Draw** into a working target (RGBA8, depth and stencil): the camera
+ *    image, then the scene through `MADE_UP_CAMERA_LAYER` only, which holds
+ *    every face-atlas layer drawn between `MAKEUP_RENDER_ORDER.prepass` and
+ *    `.restore` (makeup regions, lips, designs, the self-occlusion passes;
+ *    re-marked every frame) plus `HandCutout`, lit by the lights the main
+ *    camera sees (put on the layer for the pass). The working target is flagged
+ *    as three.js flags WebXR targets, so materials write sRGB-encoded colour
+ *    and blend exactly as they do on the canvas, with the same shader
+ *    programs. Faces riding a warp draw unwarped (where the camera sees
+ *    them).
+ * 2. **Copy** it into the output texture (SRGB8_ALPHA8), decoding on the way,
+ *    so the output samples like the camera texture (linear, decoded by the
+ *    GPU).
+ */
+/**
+ * The three.js layer the made-up camera's pass renders (30; 31 is
+ * `EXTERNAL_BACKGROUND_RENDER_LAYER`).
+ * The face-atlas makeup layers are put on it every frame; add your own
+ * objects to the made-up feed with `object.layers.enable(MADE_UP_CAMERA_LAYER)`.
+ * Keep it free for this: anything on it is drawn into the made-up camera.
+ */
+export declare const MADE_UP_CAMERA_LAYER = 30;
+/**
+ * Frame priority of the made-up pass: after the face-atlas surfaces update
+ * (-0.4), before default-priority frame callbacks (0) that read the texture.
+ * A reader that runs earlier (a face swap's live map, -0.75) gets the
+ * previous frame's image.
+ */
+export declare const MADE_UP_CAMERA_FRAME_PRIORITY = -0.3;
+/** Whether a face-atlas mesh at `renderOrder` is drawn into the made-up camera (the makeup orders, pre-pass to restore). */
+export declare const madeUpCameraDraws: (renderOrder: number) => boolean;
+/**
+ * Puts the makeup meshes of every face of `scene` on `MADE_UP_CAMERA_LAYER`
+ * (and every other face-atlas mesh off it), and draws warped faces unwarped
+ * while `unwarped` is true. The made-up pass calls it with `true` before
+ * drawing and `false` after.
+ */
+export declare const markMadeUpCameraLayers: (scene: THREE.Object3D, unwarped: boolean) => void;
+/** The shader sources, for the static tests. */
+export declare const MADE_UP_CAMERA_GLSL: Readonly<{
+    vertex: "\nvarying vec2 vUv;\nvoid main() {\n  vUv = position.xy * 0.5 + 0.5;\n  gl_Position = vec4(position.xy, 0.0, 1.0);\n}\n";
+    camera: "\nuniform sampler2D uMap;\nvarying vec2 vUv;\nvoid main() {\n  gl_FragColor = vec4(texture2D(uMap, vUv).rgb, 1.0);\n  #include <colorspace_fragment>\n}\n";
+    decode: "\nuniform sampler2D uMap;\nvarying vec2 vUv;\nvoid main() {\n  gl_FragColor = vec4(sRGBTransferEOTF(texture2D(uMap, vUv)).rgb, 1.0);\n}\n";
+}>;
+/**
+ * The working target: 8-bit storage holding sRGB-encoded colour. Tagged
+ * sRGB and flagged `isXRRenderTarget` (three.js then writes and tone-maps
+ * for it as for the canvas: `outputColorSpace` = the texture's), with an
+ * explicit `RGBA8` internal format (no GPU sRGB conversion), so blending
+ * happens on encoded values exactly as on the canvas.
+ */
+export declare const createMadeUpCameraWorkTarget: (width: number, height: number) => THREE.WebGLRenderTarget<THREE.Texture>;
+/** The output: SRGB8_ALPHA8 (decoded by the GPU when sampled, as the camera texture is). */
+export declare const createMadeUpCameraOutputTarget: (width: number, height: number) => THREE.WebGLRenderTarget<THREE.Texture>;
+/**
+ * A feed texture's content version: the made-up camera's pass count for its
+ * texture (a render target's texture never bumps `version`), else
+ * `texture.version` (the camera texture bumps it on every new frame).
+ * Compare it from frame to frame to skip work when the image is unchanged.
+ */
+export declare const feedTextureVersion: (texture: THREE.Texture) => number;
+/** The camera image with the makeup over it, feed size. See the module doc. */
+export declare class MadeUpCameraTarget {
+    private readonly work;
+    private readonly output;
+    private readonly cameraPass;
+    private readonly decodePass;
+    private readonly quadCamera;
+    private passes;
+    /** The last pass drew an image (false again once the camera is gone). */
+    private live;
+    private stamp;
+    constructor();
+    /**
+     * The made-up feed: the camera texture's layout (uv, aspect, image top at
+     * v = 1), sRGB, decoded by the GPU when sampled. The same object for the
+     * target's life (a resize keeps it).
+     */
+    get texture(): THREE.Texture;
+    /** Passes rendered (0: nothing yet, the texture is empty). */
+    get frame(): number;
+    /**
+     * The texture holds the current camera image: a pass has run and the
+     * camera has not gone since (`render` without a camera texture ends it).
+     */
+    get ready(): boolean;
+    get width(): number;
+    get height(): number;
+    /** `render` once per `stamp` (R3F's `clock.elapsedTime`), whoever calls first. Returns whether it rendered. */
+    renderOnce(stamp: number, renderer: THREE.WebGLRenderer, scene: THREE.Object3D, camera: THREE.Camera, cameraTexture: THREE.Texture | null): boolean;
+    /**
+     * One pass: `cameraTexture` (the session camera) with the scene's
+     * `MADE_UP_CAMERA_LAYER` drawn over it through `camera`, into the
+     * texture. Feed size: the camera image's (the canvas's drawing buffer
+     * when it has none). Leaves the renderer's target, clear colour,
+     * `autoClear`, XR and shadow state, the camera's layers and the scene's
+     * background and override material as they were. Returns false (nothing
+     * drawn) without a camera texture.
+     */
+    render(renderer: THREE.WebGLRenderer, scene: THREE.Object3D, camera: THREE.Camera, cameraTexture: THREE.Texture | null): boolean;
+    dispose(): void;
+    /** Both targets at the camera image's size (capped at the GPU's texture limit). */
+    private fitSize;
+}
+/** The renderer's shared made-up camera, with one more holder (made on first use). Pair with `releaseMadeUpCamera`. */
+export declare const acquireMadeUpCamera: (renderer: THREE.WebGLRenderer) => MadeUpCameraTarget;
+/** One holder fewer; the last one disposes the target. */
+export declare const releaseMadeUpCamera: (renderer: THREE.WebGLRenderer, target: MadeUpCameraTarget) => void;
+/**
+ * The renderer's made-up camera when someone holds it and it has rendered
+ * (never starts one): for shared consumers that serve several components,
+ * such as a face's live map.
+ */
+export declare const peekMadeUpCamera: (renderer: THREE.WebGLRenderer) => MadeUpCameraTarget | null;

package/dist/face-atlas/masks.d.ts

@@ -0,0 +1,53 @@
+import { DataTexture } from 'three';
+import { FaceAtlasRegionSelection } from './regions';
+export type FaceAtlasMaskOptions = {
+    /** Regions painted white (their union). */
+    include: FaceAtlasRegionSelection;
+    /** Regions cut back out of `include`. */
+    exclude?: FaceAtlasRegionSelection;
+    /** Width and height in pixels. Default 256. */
+    size?: number;
+    /**
+     * Edge softness as a fraction of the atlas width: the edge fades over about
+     * this distance (0.02 = 2 % of the width). Default 0 (antialiased edge only).
+     */
+    feather?: number;
+    /**
+     * Where row 0 sits. `"top"` (default): row 0 is `v = 1`, as in an image, an
+     * `ImageData` or a canvas. `"bottom"`: row 0 is `v = 0`, as a
+     * `THREE.DataTexture` samples it (`flipY` is false for data textures); use
+     * `createFaceAtlasMaskTexture`, which sets this for you.
+     */
+    origin?: "top" | "bottom";
+};
+/** A single-channel coverage mask in atlas space (0 outside, 255 inside). */
+export type FaceAtlasMask = {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/**
+ * Rasterize face atlas regions into a coverage mask in plain JavaScript (no
+ * canvas, no `ctx.filter`, so it works in workers, Node and iOS Safari):
+ * `include` minus `exclude`, 2×2 supersampled, then feathered by a
+ * three-pass box blur. Row 0 is `v = 1` by default, ready for an
+ * `ImageData` via `faceAtlasMaskToRgba`. For the GPU, use
+ * `createFaceAtlasMaskTexture` (or pass `origin: "bottom"` before building
+ * your own `THREE.DataTexture`, whose `flipY` is false), or the mask lands
+ * upside down.
+ */
+export declare const createFaceAtlasMask: (options: FaceAtlasMaskOptions) => FaceAtlasMask;
+/** Options of `createFaceAtlasMaskTexture`: the mask options without `origin`. */
+export type FaceAtlasMaskTextureOptions = Omit<FaceAtlasMaskOptions, "origin">;
+/**
+ * Rasterize face atlas regions straight into a single-channel
+ * `THREE.DataTexture` (`RedFormat`, linear filtering, read `.r` in a shader)
+ * sampled with the atlas UVs: rows are stored from `v = 0`, so no flip is
+ * needed. The caller owns the texture and disposes it.
+ */
+export declare const createFaceAtlasMaskTexture: (options: FaceAtlasMaskTextureOptions) => DataTexture;
+/**
+ * Expand a mask to RGBA (`color` RGB, alpha = coverage), e.g.
+ * `new ImageData(faceAtlasMaskToRgba(mask), mask.width, mask.height)`.
+ */
+export declare const faceAtlasMaskToRgba: (mask: FaceAtlasMask, color?: readonly [number, number, number]) => Uint8ClampedArray;