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

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

@@ -0,0 +1,396 @@
+import { FaceSwapSettings } from '../components/FaceSwap/settings';
+import { FaceImageLandmark } from './faceReprojection';
+import { FaceTexture, FaceTextureStatistics } from './faceTexture';
+import { FaceTransferLevel } from './faceTransferGeometry';
+import * as THREE from "three";
+/**
+ * Face texture transfer (FACE-2): any face texture drawn on any face.
+ *
+ * The first half of this file is the colour, edge and layout maths of the
+ * transfer shaders, as plain TypeScript. These functions are the reference:
+ * the GLSL is built from `FACE_TRANSFER_MATH_GLSL`, which embeds the same
+ * constants, and the tests pin the behaviour. Change the maths here first.
+ * The second half is the engine: the target's live map
+ * (`writeFaceTransferLiveMap`), the shaders and `FaceTransfer`.
+ *
+ * Colour is a gain per channel in linear light, computed per vertex:
+ * - **tone** `tM / sM`: the global skin-tone, exposure and white-balance
+ *   ratio of the two skin means (`matchSkinTone`);
+ * - **light**: the local low-frequency lighting ratio (`matchLighting`), at
+ *   full strength for brightness and `FACE_TRANSFER_CHROMA` strength for
+ *   colour, so coloured light does not tint the skin;
+ * - a band inside the face edge, `FACE_TRANSFER_EDGE_BAND × edgeSoftness`
+ *   wide after the inset, always takes the target's tone and light by
+ *   `edgeMatch`, so no seam shows;
+ * - the gain is clamped to `FACE_TRANSFER_GAIN_RANGE`.
+ */
+/** Clamp of the colour gain, per channel. */
+export declare const FACE_TRANSFER_GAIN_RANGE: readonly [0.25, 4];
+/**
+ * Coverage (blurred alpha) of a `low` statistics read: below the first value
+ * the skin mean is used instead, above the second the local value, blended
+ * smoothly between (no hard seam in the gain).
+ */
+export declare const FACE_TRANSFER_LOW_COVERAGE: readonly [0.15, 0.3];
+/** Strength of the colour (chroma) part of the local lighting ratio. Brightness is at full strength. */
+export declare const FACE_TRANSFER_CHROMA = 0.5;
+/** The colour edge band is this many `edgeSoftness` wide (the alpha fade is one). */
+export declare const FACE_TRANSFER_EDGE_BAND = 2;
+/** Luminance weights of linear sRGB / Rec. 709 primaries. */
+export declare const FACE_TRANSFER_LUMA: readonly [0.2126, 0.7152, 0.0722];
+/** Floor of every division. */
+export declare const FACE_TRANSFER_EPSILON = 0.0001;
+/** Mip LOD bias at `detail` 0 (none at `detail` 1). */
+export declare const FACE_TRANSFER_DETAIL_MAX_BIAS = 2;
+/** One RGBA read of a statistics texture: linear light, premultiplied by its skin coverage (alpha). */
+export type FaceStatsSample = readonly [number, number, number, number];
+export type FaceTransferGainStats = {
+    /** The source's `mean` (1×1). */
+    sourceMean: FaceStatsSample;
+    /** The target's `mean` (1×1). */
+    targetMean: FaceStatsSample;
+    /**
+     * The source's `low` (64²) at the UV the source is read at, or its mirror
+     * twin's where the source was not seen there (`faceTransferSourceLow`).
+     */
+    sourceLow: FaceStatsSample;
+    /** The target's `low` at the vertex's own face atlas UV (the geometry's `uv`). */
+    targetLow: FaceStatsSample;
+    /** cm inside the smoothed face outline (the geometry's `edge`). */
+    edge: number;
+};
+export type FaceTransferGainSettings = {
+    matchSkinTone: number;
+    matchLighting: number;
+    edgeMatch: number;
+    edgeInset: number;
+    edgeSoftness: number;
+};
+/**
+ * The colour gain the transfer multiplies the source by, per channel, in
+ * linear light. The CPU reference of `faceTransferGain` in
+ * `FACE_TRANSFER_MATH_GLSL` (the vertex shader runs it per vertex).
+ */
+export declare const faceTransferGain: (stats: FaceTransferGainStats, settings: FaceTransferGainSettings, out?: [number, number, number]) => [number, number, number];
+/**
+ * The source's local skin a vertex divides out (the `sourceLow` of
+ * `faceTransferGain`): the source's `low` where its map is read (`read`),
+ * falling back to the `low` of that point's mirror twin (`twin`) where the
+ * source's own skin was not seen there. A mirror-filled map (a turned live
+ * face, a photo) holds the twin's pixels in that place, with the twin's
+ * light baked in, so the twin's light is what must be divided out. Blended
+ * by the read's coverage over `FACE_TRANSFER_LOW_COVERAGE` (the twin below
+ * the first value, the read above the second). Where neither was seen the
+ * result keeps a low coverage and the gain falls back to the mean. The CPU
+ * reference of `faceTransferSourceLow` in `FACE_TRANSFER_MATH_GLSL`.
+ */
+export declare const faceTransferSourceLow: (read: FaceStatsSample, twin: FaceStatsSample, out?: [number, number, number, number]) => [number, number, number, number];
+export type FaceTransferAlphaInput = {
+    /** The source map's alpha where it is read (its coverage: 0 where the source face was not seen). */
+    coverage: number;
+    /** How squarely the target faces the camera there, 0..1. */
+    facing: number;
+    /** cm inside the smoothed face outline. */
+    edge: number;
+    /** cm outside the nearest eye ring (0 on the ring). */
+    eyeCm: number;
+    /** cm outside the inner-lip ring (0 on the ring). */
+    mouthCm: number;
+};
+export type FaceTransferAlphaSettings = {
+    amount: number;
+    edgeInset: number;
+    edgeSoftness: number;
+    ownEyes: boolean;
+    ownMouth: boolean;
+    featureSoftness: number;
+};
+/**
+ * The transfer's alpha: amount × source coverage × facing × the edge fade
+ * (`edgeInset`, then `edgeSoftness` wide) × soft rims around the target's
+ * own eyes and mouth when they are kept. The CPU reference of
+ * `transferAlpha` in `FACE_TRANSFER_MATH_GLSL` (run per fragment).
+ */
+export declare const transferAlpha: (input: FaceTransferAlphaInput, settings: FaceTransferAlphaSettings) => number;
+/** Mip LOD bias the source map is read with: 0 at `detail` 1, softer below. */
+export declare const faceTransferDetailBias: (detail: number) => number;
+/** How the transfer treats the target's edge-on parts (`FaceTransfer.setUnseen`). */
+export type FaceTransferUnseen = "fade" | "cover";
+/**
+ * How a face texture is laid onto a face. Left and right are the person's
+ * OWN sides on every feed.
+ * - `asIs`: as it is.
+ * - `flip`: left and right swapped.
+ * - `leftLeft` / `rightRight`: one half of the face, mirrored onto the other.
+ * - `upsideDown`: each eye and the mouth flipped top to bottom in place.
+ */
+export declare const FACE_TEXTURE_LAYOUTS: readonly ["asIs", "flip", "leftLeft", "rightRight", "upsideDown"];
+export type FaceTextureLayout = (typeof FACE_TEXTURE_LAYOUTS)[number];
+/**
+ * Whether a vertex reads the source at its mirrored UV (`uvMirror`) or its
+ * own (`uv`): the CPU reference of the vertex shader's choice.
+ *
+ * - `sourceMirror` is `resolveFaceSourceMirror(source.mirrored, feedMirrored)`:
+ *   whether the source's sides must be swapped to land on the target's own
+ *   sides (false for a live face drawn on its own feed).
+ * - `flip` swaps every vertex.
+ * - `leftLeft` / `rightRight` keep the vertices on the person's own left
+ *   (right) half and mirror the rest. The person's own left is canonical
+ *   `personLeftSign(feedMirrored)` × X: −X (landmark 33's side) on the
+ *   mirrored webcam, +X (landmark 263's side) on an unmirrored feed.
+ * - `faceSide` is the vertex's canonical side: the sign of its canonical x
+ *   (+1 = landmark 263's side), 0 on the midline (never mirrored by a half
+ *   layout; its mirror is itself).
+ */
+export declare const faceTransferReadsMirror: (layout: FaceTextureLayout, sourceMirror: boolean, feedMirrored: boolean, faceSide: number) => boolean;
+/**
+ * The half a `leftLeft` / `rightRight` layout keeps, as a canonical X sign
+ * (+1 = landmark 263's side), or 0 for any other layout: the person's own
+ * left is `personLeftSign(feedMirrored)`. A uniform for the vertex shader:
+ * a vertex with `faceSide × keptSide < 0` toggles its mirror.
+ */
+export declare const faceTransferKeptSide: (layout: FaceTextureLayout, feedMirrored: boolean) => -1 | 0 | 1;
+/**
+ * `upsideDown`: the fraction of each ellipse's radius, inside its rim, over
+ * which the flipped feature blends back into the face.
+ */
+export declare const FACE_TRANSFER_UPSIDE_DOWN_SOFTNESS = 0.3;
+/** One `upsideDown` ellipse in source UV: `[cu, cv, radiusU, radiusV]`. */
+export type FaceTransferEllipse = readonly [number, number, number, number];
+/**
+ * How much of the flipped read a point takes in one ellipse: 1 inside
+ * `1 − FACE_TRANSFER_UPSIDE_DOWN_SOFTNESS` of its radius, 0 on and outside
+ * the rim, a smoothstep between. The CPU reference of `ftSoftEllipse`.
+ */
+export declare const faceTransferSoftEllipse: (u: number, v: number, ellipse: FaceTransferEllipse) => number;
+/**
+ * `upsideDown` (the Thatcher effect): each eye and the mouth flipped top to
+ * bottom in place. For a source UV, writes `[u, v′, weight]` to `out`: the
+ * second read is at `(u, v′)` with `v′ = 2·cv − v` about the centre of the
+ * ellipse the point is in (the one with the largest weight; they do not
+ * overlap), and the fragment shader mixes it over the plain read by
+ * `weight`. Outside every ellipse the weight is 0 and `v′ = v` (identity).
+ * `ellipses` are in the source map's UV (from the transfer geometry). The
+ * CPU reference of `faceTransferUpsideDown` in `FACE_TRANSFER_MATH_GLSL`.
+ */
+export declare const faceTransferUpsideDownUv: (u: number, v: number, ellipses: readonly FaceTransferEllipse[], out?: [number, number, number]) => [number, number, number];
+/**
+ * GLSL ES 3.00 of the functions above, built from the same constants, for
+ * the transfer shaders to include:
+ * - `vec3 faceTransferGain(vec4 sourceMean, vec4 targetMean, vec4 sourceLow,
+ *   vec4 targetLow, float edge, float matchSkinTone, float matchLighting,
+ *   float edgeMatch, float edgeInset, float edgeSoftness)`;
+ * - `vec4 faceTransferSourceLow(vec4 read, vec4 twin)`;
+ * - `float transferAlpha(float coverage, float facing, float edge,
+ *   float eyeCm, float mouthCm, float amount, float edgeInset,
+ *   float edgeSoftness, bool ownEyes, bool ownMouth, float featureSoftness)`;
+ * - `float faceTransferDetailBias(float detail)`;
+ * - `bool faceTransferReadsMirror(bool mirror, float keptSide, float faceSide)`,
+ *   with `mirror = sourceMirror != (layout == flip)` and `keptSide` from
+ *   `faceTransferKeptSide`;
+ * - `float ftSoftEllipse(vec2 uv, vec4 ellipse)` and
+ *   `vec3 faceTransferUpsideDown(vec2 uv, vec4 ellipses[3])` (returns the
+ *   second read's UV in `xy` and its weight in `z`).
+ * `edgeSoftness` and `featureSoftness` must be above 0 (the resolved settings are).
+ */
+export declare const FACE_TRANSFER_MATH_GLSL: string;
+/** Texels of a transfer's live map: one per unwrap vertex (the 468 landmarks, then the 3 opening centres). */
+export declare const FACE_TRANSFER_LIVE_MAP_WIDTH: number;
+/**
+ * How squarely the target must face the camera to be drawn over (cosines,
+ * as `FaceUnwrapFrameOptions.facing`): a cheek seen edge-on fades out, so
+ * the real face shows at the silhouette of a turned head.
+ */
+export declare const FACE_TRANSFER_TARGET_FACING: readonly [number, number];
+/** Clip-space z of the transfer mesh: just behind the near plane, so `HandCutout`'s near-plane depth (z −1) stays in front. */
+export declare const FACE_TRANSFER_DEPTH = -0.999;
+/**
+ * Writes a target face's live map: `(x, y, facing, 1)` per unwrap vertex
+ * (`FACE_TRANSFER_LIVE_MAP_WIDTH` texels, RGBA), where `x, y` are the
+ * landmark in feed or picture space (0..1, y down) and `facing` how squarely
+ * it faces the camera (0..1, `FACE_TRANSFER_TARGET_FACING`). The opening
+ * centres sit at the average of their ring, as in the unwrap, so a face
+ * drawn back where it was unwrapped lands exactly on itself. `landmarks` has
+ * at least 468 points; `aspect` is the image's width / height. Returns
+ * `out`; allocates nothing.
+ */
+export declare const writeFaceTransferLiveMap: (landmarks: ArrayLike<FaceImageLandmark>, aspect: number, out: Float32Array, facing?: readonly [number, number]) => Float32Array;
+/** A live map texture (`FACE_TRANSFER_LIVE_MAP_WIDTH` × 1, RGBA32F, nearest): write `image.data`, then set `needsUpdate`. */
+export declare const createFaceTransferLiveMap: () => THREE.DataTexture;
+/**
+ * The transfer's vertex shader (three's `ShaderMaterial` prefix supplies
+ * `uv`). Per vertex: its place on screen from three texels of the target's
+ * live map (`ftCorners` blended by `ftBary`), how squarely it faces the
+ * camera, which UV the source is read at (`uv` or `ftUvMirror`, per layout
+ * and sides), and the colour gain (`faceTransferGain`, from the source's and
+ * target's skin statistics). The source's local skin is read where its map
+ * is read, or at the mirror twin where that skin was not seen
+ * (`faceTransferSourceLow`: a mirror-filled map holds the twin's light).
+ * `uSourceFlat` 1 reads the source's local skin as its mean (painted faces:
+ * the paint keeps its own shading).
+ */
+export declare const FACE_TRANSFER_VERTEX_SHADER: string;
+/**
+ * The transfer's fragment shader: one read of the source map (two in
+ * `upsideDown`, mixed per fragment so the flipped eyes and mouth stay
+ * crisp), un-premultiplied, times the vertex's gain; alpha from
+ * `transferAlpha`. Writes straight alpha for `faceSurfaceBlending`.
+ */
+export declare const FACE_TRANSFER_FRAGMENT_SHADER: string;
+/** The transfer's per-vertex attributes (besides three's `position` and `uv`). */
+export declare const FACE_TRANSFER_ATTRIBUTES: readonly ["ftCorners", "ftBary", "ftUvMirror", "ftFaceSide", "ftEdge", "ftEyeCm", "ftMouthCm"];
+export type FaceTransferUniforms = {
+    uLiveMap: THREE.IUniform<THREE.Texture | null>;
+    uSourceMap: THREE.IUniform<THREE.Texture | null>;
+    uSourceLow: THREE.IUniform<THREE.Texture | null>;
+    uSourceMean: THREE.IUniform<THREE.Texture | null>;
+    uTargetLow: THREE.IUniform<THREE.Texture | null>;
+    uTargetMean: THREE.IUniform<THREE.Texture | null>;
+    uSourceFlat: THREE.IUniform<number>;
+    uMirror: THREE.IUniform<number>;
+    uKeptSide: THREE.IUniform<number>;
+    uMatchSkinTone: THREE.IUniform<number>;
+    uMatchLighting: THREE.IUniform<number>;
+    uEdgeMatch: THREE.IUniform<number>;
+    uEdgeInset: THREE.IUniform<number>;
+    uEdgeSoftness: THREE.IUniform<number>;
+    uFeatureSoftness: THREE.IUniform<number>;
+    uFacingFloor: THREE.IUniform<number>;
+    uDetail: THREE.IUniform<number>;
+    uOwnEyes: THREE.IUniform<number>;
+    uOwnMouth: THREE.IUniform<number>;
+    uAmount: THREE.IUniform<number>;
+    uUpsideDown: THREE.IUniform<number>;
+    uEllipses: THREE.IUniform<THREE.Vector4[]>;
+    uDepth: THREE.IUniform<number>;
+};
+/** Every uniform the transfer shaders declare, at neutral values (nothing bound, nothing drawn). */
+export declare const createFaceTransferUniforms: () => FaceTransferUniforms;
+/** The settings a transfer draws with: `FaceSwapSettings` without the preset, smoothing and amount. */
+export type FaceTransferSettings = Pick<FaceSwapSettings, "matchSkinTone" | "matchLighting" | "edgeMatch" | "edgeSoftness" | "edgeInset" | "ownEyes" | "ownMouth" | "featureSoftness" | "detail">;
+/**
+ * The transfer mesh's geometry at a level, with its own buffer attributes
+ * (their arrays are the memoised geometry's: shared, never written). The
+ * index drops the eye fills (`ownEyes`) and the mouth fill (`ownMouth`).
+ */
+export declare const createFaceTransferGeometry: (level: FaceTransferLevel, ownEyes: boolean, ownMouth: boolean) => THREE.BufferGeometry;
+export type FaceTransferOptions = {
+    /** Subdivision of the mesh: 2 (default) = 14.5k triangles, 1 = 3.6k. */
+    level?: FaceTransferLevel;
+};
+/**
+ * Draws a face texture (`setSource`) onto a target face (`setTarget`, or a
+ * shared live map with `setTargetMap`) in screen space, with colour
+ * transfer, soft edges, the target's own eyes and mouth kept, and a layout
+ * (`asIs`, `flip`, `leftLeft`, `rightRight`, `upsideDown`). Positions come
+ * from the target's landmarks in feed or picture space (0..1, y down), so
+ * the same mesh draws over the live feed (add `mesh` to the scene) or into a
+ * render target the size of a picture. No React needed.
+ *
+ * - The mesh draws at `FACE_SURFACE_RENDER_ORDER` (−2) in the opaque pass
+ *   with `faceSurfaceBlending`, depth-tested (hands drawn by `HandCutout`
+ *   stay in front) and writing no depth (accessories draw over it). Its
+ *   triangles are ordered back to front, so the nose covers the far cheek of
+ *   a turned head.
+ * - It shows only when everything it needs is set: a target, a source whose
+ *   `map` is ready, the target's statistics (`setTargetStats`) and
+ *   `amount > 0`. Live sources change in place: call `update()` once a frame
+ *   (`<FaceTextureLayer>` does) so `mesh.visible` follows them.
+ *
+ * ```ts
+ * const transfer = new FaceTransfer();
+ * transfer.setSource(face); // a FaceTexture (createFaceTexture, useLiveFaceTexture)
+ * transfer.setTarget(pictureLandmarks, picture.width / picture.height);
+ * transfer.setTargetStats(pictureFace); // its low and mean
+ * transfer.setLayout("asIs", false);
+ * renderer.setRenderTarget(pictureTarget);
+ * renderer.render(transfer.mesh, camera); // any camera: the mesh is in clip space
+ * ```
+ */
+export declare class FaceTransfer {
+    /** The screen-space mesh. Add it to a scene, or render it into a target. */
+    readonly mesh: THREE.Mesh<THREE.BufferGeometry, THREE.ShaderMaterial>;
+    /** The shaders' uniforms (the setters keep them; read-only for callers). */
+    readonly uniforms: FaceTransferUniforms;
+    private levelValue;
+    private readonly liveData;
+    private ownLiveMap;
+    private sharedLiveMap;
+    private ownTarget;
+    private source;
+    private targetStats;
+    private amountValue;
+    private layoutValue;
+    private feedMirrored;
+    private unseenValue;
+    private readonly settings;
+    constructor(options?: FaceTransferOptions);
+    /** The mesh's subdivision level. */
+    get level(): FaceTransferLevel;
+    /** The layout set last. */
+    get layout(): FaceTextureLayout;
+    /** The settings in use (resolved and clamped; do not mutate). */
+    get currentSettings(): Readonly<FaceTransferSettings>;
+    /**
+     * Everything the draw needs is set: a target, a source with a ready map,
+     * and the target's statistics.
+     */
+    get ready(): boolean;
+    /** Swaps the mesh to another subdivision level (a quality change). */
+    setLevel(level: FaceTransferLevel): void;
+    /**
+     * A new geometry for the level and the own eyes / mouth (the index drops
+     * or restores their fills). The old one is disposed, which frees all its
+     * GL buffers, the index included (replacing only the index would leave the
+     * old index buffer on the GPU until garbage collection).
+     */
+    private rebuildGeometry;
+    /**
+     * The target face: its landmarks (≥ 468) in feed or picture space (0..1,
+     * y down) and that image's width / height. How squarely each point faces
+     * the camera is computed here. Replaces a `setTargetMap` map.
+     */
+    setTarget(landmarks: ArrayLike<FaceImageLandmark>, aspect: number, facing?: readonly [number, number]): void;
+    /**
+     * Draws on a live map kept elsewhere (`writeFaceTransferLiveMap` into a
+     * `createFaceTransferLiveMap` texture; the live-face registry keeps one per
+     * tracked face). `null` goes back to the last `setTarget`.
+     */
+    setTargetMap(map: THREE.Texture | null): void;
+    /** The face texture to draw (it stays the caller's to dispose). `null` draws nothing. */
+    setSource(face: FaceTexture | null): void;
+    /** The target's skin statistics (its `low` and `mean`). `null` draws nothing. */
+    setTargetStats(stats: FaceTextureStatistics | null): void;
+    /**
+     * How the source is laid on the target. `feedMirrored` is the target
+     * feed's (or picture's) mirroring, `useXRMirrored()` for the live feed:
+     * with the source's own `mirrored` it decides which side is the person's
+     * own left (`resolveFaceSourceMirror`, `faceTransferKeptSide`).
+     */
+    setLayout(layout: FaceTextureLayout, feedMirrored: boolean): void;
+    /**
+     * Colour, edge, feature and detail settings (any subset of
+     * `FaceSwapSettings`; clamped to their ranges). `preset`, `smoothing` and
+     * `amount` are ignored here (`setAmount` sets the amount).
+     */
+    setSettings(settings: Partial<FaceSwapSettings>): void;
+    /**
+     * The parts of the target the camera sees edge-on (nostril undersides,
+     * the lips' seam, the far side of the nose): `"fade"` (default) leaves
+     * them to the camera, `"cover"` draws the source there too, for a fill
+     * that must hide the features (`<Faceless>`).
+     */
+    setUnseen(unseen: FaceTransferUnseen): void;
+    /** Overall strength, 0..1. */
+    setAmount(amount: number): void;
+    /**
+     * Re-reads a live source (its `map`, `mirrored`, `ready`) and sets
+     * `mesh.visible`. The setters do this; call it once a frame when the
+     * source or the target's statistics change in place.
+     */
+    update(): void;
+    /** Frees the geometry, the own live map and the material. The source and statistics stay the caller's. */
+    dispose(): void;
+    /** Binds the current state into the uniforms; `visibility` also sets `mesh.visible`. */
+    private sync;
+}

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

@@ -0,0 +1,109 @@
+import { FaceTransferEllipse } from './faceTransfer';
+/**
+ * The face transfer mesh (FACE-2): the filled canonical face
+ * (`getFaceUnwrapMesh()`, 471 vertices: the 468 landmarks and the centres of
+ * the eye and mouth openings) subdivided 1 or 2 times, drawn in screen space
+ * over a target face. Pure data, memoised per level and shared (do not
+ * mutate it); the transfer layer turns it into GPU buffers.
+ *
+ * - **Placement:** every vertex blends three unwrap vertices (`corners`) by
+ *   `bary`, so the vertex shader places it from a 471-texel position texture
+ *   of the target's live landmarks. Subdivision is linear (the vertices lie
+ *   on the parent triangles); it only gives the per-vertex colour, edge and
+ *   feature terms more samples.
+ * - **Draw order:** parent triangles (each with its `4^level` children,
+ *   contiguous) are sorted back to front by canonical centroid z, so without
+ *   depth writes the nose covers the far cheek on a turned head and soft
+ *   edges blend in order. The eye and mouth fills are sorted with the rest,
+ *   so the nose bridge and lids also cover them.
+ * - **Index variants:** `getFaceTransferIndex(level, ownEyes, ownMouth)` drops
+ *   the eye fills and / or the mouth fill, so the target's own live eyes or
+ *   mouth show through.
+ * - **Static attributes**, all in the face atlas (`FACE_ATLAS_UVS`, v up) and
+ *   the canonical head frame (cm, +X toward landmark 263): `uv`, `uvMirror`,
+ *   `faceSide`, `edge`, `eyeCm`, `mouthCm` (see `FaceTransferGeometry`).
+ */
+export declare const FACE_TRANSFER_LEVELS: readonly [1, 2];
+/** Subdivision level of the transfer mesh: each parent triangle becomes `4^level` triangles. */
+export type FaceTransferLevel = (typeof FACE_TRANSFER_LEVELS)[number];
+/** Samples of the smoothed face outline the `edge` attribute is measured to. */
+export declare const FACE_TRANSFER_OUTLINE_SAMPLES = 720;
+/** Samples per ring segment of the smoothed eye rings and inner-lip ring. */
+export declare const FACE_TRANSFER_FEATURE_SAMPLES_PER_SEGMENT = 16;
+/** What a parent triangle covers: the face skin, an eye opening's fill, or the mouth opening's fill. */
+export declare const FACE_TRANSFER_PARENT_KIND: {
+    readonly face: 0;
+    readonly eye: 1;
+    readonly mouth: 2;
+};
+/**
+ * The subdivided face for the transfer. Per-vertex arrays are flat; vertices
+ * `0 … 470` are the unwrap vertices themselves, in order.
+ */
+export type FaceTransferGeometry = {
+    level: FaceTransferLevel;
+    vertexCount: number;
+    /** Three unwrap vertices (0 … 470) per vertex: the live positions it blends. */
+    corners: Uint16Array;
+    /** Their barycentric weights (three per vertex, summing to 1). */
+    bary: Float32Array;
+    /** Rest position in the canonical head frame, cm (three per vertex). */
+    position: Float32Array;
+    /** Face atlas UV (`FACE_ATLAS_UVS`, v up; two per vertex). */
+    uv: Float32Array;
+    /**
+     * Face atlas UV of the vertex's mirror point `(−x, y, z)` (two per vertex):
+     * where a mirrored read samples the source. Exact through the landmark
+     * mirror map where the mirror triangle exists; for the 12 canonical
+     * triangles whose mirror quad is split the other way, the point is found
+     * on the front-projected (x, y) face. Midline vertices keep their own UV.
+     */
+    uvMirror: Float32Array;
+    /** The vertex's canonical side: +1 on landmark 263's side (+X), −1 on 33's, 0 on the midline. */
+    faceSide: Float32Array;
+    /**
+     * cm to the smoothed face outline (a centripetal Catmull-Rom loop through
+     * the 36 oval landmarks, `FACE_TRANSFER_OUTLINE_SAMPLES` samples), straight
+     * line in 3D: 0 on the outline, positive inside, so fades follow a smooth
+     * curve instead of the 36-segment polygon.
+     */
+    edge: Float32Array;
+    /** cm outside the nearer smoothed eye ring (lash line): 0 on it, negative inside the opening. */
+    eyeCm: Float32Array;
+    /** cm outside the smoothed inner-lip ring: 0 on it, negative inside the mouth opening. */
+    mouthCm: Float32Array;
+    /** Triangles per parent: `4^level`. */
+    trianglesPerParent: number;
+    /**
+     * Draw slots, back to front: the unwrap triangle (`getFaceUnwrapMesh().index / 3`)
+     * of each. Slot `t`'s children are triangles `[t·4^level, (t+1)·4^level)` of `index`.
+     */
+    parents: Uint16Array;
+    /** Per slot: `FACE_TRANSFER_PARENT_KIND` (face, eye fill or mouth fill). */
+    parentKinds: Uint8Array;
+    /** Every triangle in draw order (three vertex indices each): eyes and mouth filled. */
+    index: Uint16Array;
+};
+/**
+ * The transfer mesh at a subdivision level: level 1 has 1 845 vertices and
+ * 3 616 triangles, level 2 has 7 305 vertices and 14 464 triangles. Built
+ * once per level (tens of milliseconds) and shared: do not mutate it.
+ */
+export declare const getFaceTransferGeometry: (level: FaceTransferLevel) => FaceTransferGeometry;
+/**
+ * The transfer mesh's triangles in draw order, without the eye fills
+ * (`ownEyes`: the target keeps its live eyes) and / or the mouth fill
+ * (`ownMouth`: the target keeps its live mouth interior). One of four
+ * memoised arrays per level; `ownEyes` and `ownMouth` both false is the
+ * geometry's own `index`. Shared: do not mutate it.
+ */
+export declare const getFaceTransferIndex: (level: FaceTransferLevel, ownEyes: boolean, ownMouth: boolean) => Uint16Array;
+/**
+ * The `upsideDown` ellipses in face atlas UV, `[cu, cv, radiusU, radiusV]`:
+ * the +X eye (landmark 263's), the −X eye (33's) and the mouth, each centred
+ * on its opening's centre and covering `faceReprojectionRegionEllipses()`
+ * (the lids and a little brow bone; the lips) as seen on the face. Each eye
+ * and the mouth is flipped top to bottom about its own centre, in place; a
+ * flipped read stays inside its ellipse. Built once and shared.
+ */
+export declare const getFaceTransferUpsideDownEllipses: () => readonly [FaceTransferEllipse, FaceTransferEllipse, FaceTransferEllipse];

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

@@ -0,0 +1,94 @@
+import * as THREE from "three";
+/**
+ * A GPU self-test of the face transfer (FACE-2) on this device's WebGL2:
+ *
+ * 1. **compile**: both transfer shaders (`FACE_TRANSFER_VERTEX_SHADER` /
+ *    `FACE_TRANSFER_FRAGMENT_SHADER`, with `FACE_TRANSFER_MATH_GLSL`) link
+ *    and draw, in every layout, with no shader or GL error.
+ * 2. **parity**: `faceTransferGain`, `faceTransferSourceLow`,
+ *    `transferAlpha` and `faceTransferUpsideDown` run on the GPU for many
+ *    input tuples and match their TypeScript references.
+ * 3. **asIs equals the camera**: a synthetic clip (a textured canonical head
+ *    turning, drawn by a perspective camera, its 468 landmarks projected)
+ *    runs through the live-face registry (`LiveFaceEntry`: smoothing, live
+ *    map, unwrap, skin statistics) and a `FaceTransfer` with layout `asIs`
+ *    draws the face back on itself: the frame must equal the camera frame
+ *    within resampling, far below a one-pixel shift.
+ * 4. **layouts**: on the frontal frame, `flip` equals the head painted with
+ *    mirrored UVs, and `leftLeft` / `rightRight` keep the right half as the
+ *    camera has it and draw a symmetric face.
+ * 5. **mirror fill**: a side-lit source turned 30°, its far cheek filled
+ *    from the near side, takes the target's light there (the twin read).
+ * 6. **latency**: results whose landmarks are two frames older than the
+ *    camera frame they arrive with (a moving head) still give the camera
+ *    back with `asIs`.
+ * 7. **between results** (reported): the face between two 15 Hz results
+ *    over a moving 30 fps camera.
+ * 8. **bakes**: asIs with a painted face (`canonicalTexture`, the clip's
+ *    own paint, preset `raw`) and a photo bake of a frame (known landmarks).
+ * 9. **faceless**: the frontal frame's live face through `FacelessTexture`
+ *    (FACE-5): its shader links; the features are erased and opaque, the
+ *    rest is the live map unchanged; `smooth` changes the whole face; grain
+ *    adds texture only where it should.
+ *
+ * The headless smoke run drives it (`example/smoke/face-transfer.spec.ts`);
+ * open `/smoke/face-transfer.html` on the dev server to run it on a device.
+ */
+export type FaceTransferSelfTestCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type FaceTransferSelfTestResult = {
+    ok: boolean;
+    /** A thrown error, if the test could not run. */
+    error: string | null;
+    checks: FaceTransferSelfTestCheck[];
+};
+/** The synthetic clip and the pass thresholds. */
+export declare const FACE_TRANSFER_SELF_TEST_SCENE: Readonly<{
+    width: 480;
+    height: 360;
+    /** Vertical field of view (degrees). */
+    fov: 40;
+    /** Head distance (cm). */
+    distance: 55;
+    /** Per frame: yaw, pitch, roll (degrees), x / y offset (cm). */
+    poses: readonly [readonly [0, 0, 0, 0, 0], readonly [12, -4, 3, 1.5, 0.5], readonly [-18, 6, -4, -1, -0.5], readonly [28, 2, 5, 2, 1], readonly [-30, -6, -2, -2, 0], readonly [6, 10, 8, 0.5, -1], readonly [-8, -10, -6, -0.5, 1], readonly [20, -3, 0, 1, 0]];
+    /** Atlas paint size (px, square). */
+    paintSize: 512;
+    /** asIs: mean |Δ| per channel over the face (8-bit sRGB levels) must stay below this… */
+    maxMeanDiff: 1.5;
+    /** …and below this share of a one-pixel shift's mean |Δ| (registration well under a pixel). */
+    maxShiftShare: 0.5;
+    /** Drawn alone, the layer is opaque over at least this share of the face's box (it really draws). */
+    minCoverage: 0.3;
+    /** GPU vs TypeScript: largest relative error of the gain and alpha. */
+    parityTolerance: 0.002;
+    parityTuples: 64;
+    /**
+     * The mirror-fill case, over the outer strip of each side (from
+     * `stripFrom` × the half-width out): the far strip's least opaque share,
+     * its largest brightness bias from the target (8-bit levels), and the
+     * least bias with the twin read removed (the case really fills the cheek).
+     */
+    mirrorFill: Readonly<{
+        stripFrom: 0.6;
+        minCoverage: 0.1;
+        maxFarBias: 2.5;
+        minPlainBias: 5;
+    }>;
+    /** The latency case: how many 30 fps frames the landmarks lag the camera, over how many frames. */
+    latency: Readonly<{
+        latencyFrames: 2;
+        frames: 6;
+    }>;
+}>;
+/**
+ * Runs every check (see the module comment) on `renderer`, or on a new
+ * offscreen renderer that it disposes. Never rejects: failures and thrown
+ * errors are in the result.
+ */
+export declare const runFaceTransferSelfTest: (options?: {
+    renderer?: THREE.WebGLRenderer;
+}) => Promise<FaceTransferSelfTestResult>;