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

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

@@ -0,0 +1,93 @@
+import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
+import { FaceImageDetection, FacePhotoPick, FacePhotoWarning } from './facePhoto';
+/** Most faces one still image reports (MediaPipe finds at most this many in a group photo). */
+export declare const FACE_IMAGE_MAX_FACES = 4;
+/** The still-image detector closes this long after its last use, freeing its WASM heap. */
+export declare const FACE_IMAGE_LANDMARKER_IDLE_MS = 30000;
+/** An image `detectFaceImage` reads, already decoded and upright. */
+export type FaceImageSource = HTMLCanvasElement | OffscreenCanvas | HTMLImageElement | ImageBitmap;
+/** MediaPipe's result → plain detections, in MediaPipe's order. */
+export declare const toFaceImageDetections: (result: FaceLandmarkerResult) => FaceImageDetection[];
+/**
+ * Closes the still-image detector now (it starts again on the next photo).
+ * A detection still waiting for it rejects with `aborted`.
+ */
+export declare const disposeFaceImageLandmarker: () => void;
+/**
+ * The `numFaces` largest (widest) faces (a whole number from 1 to
+ * `FACE_IMAGE_MAX_FACES`; anything else, NaN included, means the maximum),
+ * ordered left to right (`faceImageOrderLeftToRight`).
+ */
+export declare const limitFaceImageDetections: (detections: ReadonlyArray<FaceImageDetection>, numFaces?: number) => FaceImageDetection[];
+/**
+ * Every face in a still image: the `numFaces` largest (default and maximum
+ * `FACE_IMAGE_MAX_FACES`), ordered left to right as the image is stored
+ * (box centre x; 0 = leftmost); `[]` when there is none.
+ * The image must be decoded and upright (`loadFacePhoto` does both).
+ * Rejects with a `FaceTextureLoadError`: `model` (the detector could not
+ * start), `cors` (a cross-origin image taints the read) or `aborted`.
+ */
+export declare const detectFaceImage: (image: FaceImageSource, options?: {
+    numFaces?: number;
+    signal?: AbortSignal;
+}) => Promise<FaceImageDetection[]>;
+/** A photo: a URL, a File or Blob, or an image that is already decoded. */
+export type FacePhotoSource = string | Blob | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap;
+/** The one canvas a photo is analysed and baked from. */
+export type FacePhotoCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Decodes a photo (fetching a URL; EXIF orientation applied) and draws it
+ * upright into one new canvas whose longest side is at most `maxSize`
+ * (default `FACE_PHOTO_MAX_SIZE`, never upscaled). The same canvas feeds the
+ * detector and the bake, so landmarks and pixels agree by construction. A
+ * URL or Blob is decoded straight at the canvas size where the browser can,
+ * so a large phone photo is never held at full resolution. The caller owns
+ * the canvas; nothing is stored. A bitmap decoded here is closed here; an
+ * image you pass in is left as it is.
+ */
+export declare const loadFacePhoto: (src: FacePhotoSource, options?: {
+    maxSize?: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    canvas: FacePhotoCanvas;
+    width: number;
+    height: number;
+}>;
+/** A photo, analysed: its canvas, the face in use, every face found and the warnings. */
+export type FacePhotoDetection = {
+    /** The upright photo, at most `maxSize` on its longest side. Landmarks are in its space. */
+    canvas: FacePhotoCanvas;
+    width: number;
+    height: number;
+    /** The face in use: the largest, or the one `pick` named. */
+    detection: FaceImageDetection;
+    /** Its index in `detections`, so its place from the left (0 = leftmost). Not a live face index. */
+    pickedIndex: number;
+    /** Every face found, left to right (box centre x; 0 = leftmost). */
+    detections: FaceImageDetection[];
+    /** In `FACE_PHOTO_WARNINGS` order; empty for a good photo. */
+    warnings: FacePhotoWarning[];
+    /**
+     * The photo itself is mirrored (some phones save selfies mirrored), as the
+     * caller said: canonical +X (landmark 263) is then the person's own RIGHT.
+     * Pixels cannot tell (a face is near-symmetric and no metadata records it),
+     * so it is never detected and never a warning; the canvas is not flipped.
+     */
+    mirrored: boolean;
+};
+/**
+ * `loadFacePhoto` + `detectFaceImage` + the face to use + its warnings, the
+ * whole still-photo step of a photo face swap. `pick` (a `FaceTextureSource`'s
+ * `pick`) chooses the photo's face: `"largest"` (default) or the n-th from the
+ * left (0 = leftmost). It is not the live target face (`FaceSwap`'s
+ * `faceIndex`): never pass that here. Rejects with a `FaceTextureLoadError`:
+ * `noFace`, `decode`, `cors`, `model` or `aborted`.
+ */
+export declare const detectFacePhoto: (src: FacePhotoSource, options?: {
+    maxSize?: number;
+    /** Which face of the photo: `"largest"` (default) or n-th from the left (0 = leftmost). */
+    pick?: FacePhotoPick;
+    /** The photo is a mirrored selfie. Default false. */
+    mirrored?: boolean;
+    signal?: AbortSignal;
+}) => Promise<FacePhotoDetection>;

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

@@ -0,0 +1,62 @@
+/**
+ * How an external mesh's vertices find their place on the tracked face:
+ * - `"uv"` — by UV, for a mesh whose face UVs follow the canonical layout
+ *   (exact, even where the shape differs);
+ * - `"surface"` — the closest point on the canonical face surface in 3D (any
+ *   topology and UV layout);
+ * - `"auto"` (default) — UV where a vertex's UV lands on the canonical face
+ *   AND agrees with its 3D position, the surface everywhere else.
+ */
+export type FaceMeshBindingMode = "auto" | "uv" | "surface";
+export type FaceMeshBindingOptions = {
+    mode?: FaceMeshBindingMode;
+    /**
+     * How far from the canonical face surface a vertex still follows the face's
+     * expression, in centimetres: fully up to `inner`, fading to rigid at
+     * `outer` (the back of the head, the ears and the neck stay rigid). Default
+     * `[0.8, 2.5]`.
+     */
+    falloff?: readonly [number, number];
+    /** UV binding is trusted only when it lands within this distance of the vertex (cm). Default 1.5. */
+    uvTolerance?: number;
+};
+/** Where each vertex of one mesh is bound. Arrays are per vertex. */
+export type FaceMeshBinding = {
+    /** The canonical triangle (index into `CANONICAL_FACE_TRIANGLES / 3`), or -1 when unbound. */
+    triangle: Int32Array;
+    /** Barycentric weights of the three triangle corners (flat, 3 per vertex). */
+    weights: Float32Array;
+    /** How much the vertex follows the face's expression, 0 (rigid) … 1. */
+    influence: Float32Array;
+    /** Signed distance from the bound surface point, cm (+ = in front of the face). */
+    distance: Float32Array;
+    /** How it was bound: 0 none, 1 UV, 2 surface. */
+    source: Uint8Array;
+    /** For `"auto"` / `"uv"`: whether the model's UV v runs down (glTF) instead of up. */
+    uvFlipped: boolean;
+};
+/**
+ * Binds the vertices of one mesh to the canonical face surface. `positions`
+ * are the vertices in the canonical head frame (centimetres — the frame the
+ * model is authored in); `uvs` are its UVs (optional, for `"uv"` / `"auto"`).
+ * Pure; run once per mesh at load (≈ tens of milliseconds for a few thousand
+ * vertices).
+ */
+export declare const bindFaceMesh: (positions: ArrayLike<number>, uvs?: ArrayLike<number> | null, { mode, falloff, uvTolerance }?: FaceMeshBindingOptions) => FaceMeshBinding;
+/**
+ * The expression offset at a bound point: the barycentric blend of the three
+ * corner landmarks' offsets (`residual`: flat per landmark, canonical cm — the
+ * live face minus the canonical rest, see `FaceRigState.residual`).
+ */
+export declare const sampleResidual: (binding: FaceMeshBinding, vertex: number, residual: ArrayLike<number>, out: [number, number, number]) => [number, number, number];
+/**
+ * Deforms one mesh by the face's expression: `out = rest + influence ×
+ * residual at the bound point`, with the offset turned into the mesh's own
+ * frame by `toLocal` (a row-major 3×3, canonical cm → mesh units; identity
+ * when the mesh is authored directly in canonical cm). `amount` scales the
+ * whole expression (0 = rigid, 1 = the tracked face). Allocation-free; call it
+ * per frame.
+ */
+export declare const deformFaceMesh: (binding: FaceMeshBinding, rest: ArrayLike<number>, residual: ArrayLike<number>, out: Float32Array | number[], amount?: number, toLocal?: ArrayLike<number>) => number[] | Float32Array<ArrayBufferLike>;
+/** Number of canonical face landmarks a residual array covers. */
+export declare const FACE_RESIDUAL_LENGTH: number;

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

@@ -0,0 +1,77 @@
+import { FaceReprojectionBinding } from './faceReprojection';
+import * as THREE from "three";
+/**
+ * Face morph (Snap-style "External Face Mesh" morph): the person's live face
+ * mesh morphs into another shape — a sphere, a cube, a character — wearing
+ * the person's camera face all the way. `weight` 0 is the live face itself;
+ * 1 is the shape, still moving with the expression.
+ *
+ * Every vertex of the shape is bound to a point of the (filled) canonical
+ * face through its BASE pose — where the vertex sits on a face. Per frame it
+ * blends between that point on the live face and its place on the shape.
+ */
+/** A built-in morph shape. */
+export type FaceMorphShapeName = "sphere" | "cube";
+/** A built-in shape's geometry plus its base pose (the same vertices on the canonical face). */
+export type FaceMorphShape = {
+    /**
+     * Shape positions (canonical cm), `uv` in the canonical face layout, an
+     * RGBA `color` whose alpha fades the shape out at the edge of the face
+     * (render it with `vertexColors` + `transparent`), indexed.
+     */
+    geometry: THREE.BufferGeometry;
+    /** The vertices on the canonical face (cm, flat): the base pose that binds them. */
+    base: Float32Array;
+};
+/** The filled canonical face, subdivided: canonical positions, UVs, edge feather (0 on the outer edge), triangles. */
+export type SubdividedFace = {
+    positions: Float32Array;
+    uvs: Float32Array;
+    feather: Float32Array;
+    index: number[];
+};
+/**
+ * The filled canonical face subdivided `levels` times (cached: the arrays are
+ * shared, do not mutate them).
+ */
+export declare const subdivideFaceUnwrap: (levels: number) => SubdividedFace;
+/**
+ * A built-in morph shape: the filled canonical face (eyes and mouth closed
+ * over), subdivided `subdivisions` times, pushed out onto a sphere or a cube
+ * around the head's centre. Its `uv` is the canonical face layout.
+ */
+export declare const createFaceMorphShape: (name: FaceMorphShapeName, { subdivisions, size }?: {
+    subdivisions?: number;
+    size?: number;
+}) => FaceMorphShape;
+/**
+ * The live face on the filled canonical face's vertices (the landmarks, then
+ * each opening's centre as its ring's average), in the head frame (cm):
+ * `point` — where each is now (the person's face with its expression,
+ * `FaceRigState.local`); `expression` — its expression offset
+ * (`FaceRigState.residual`).
+ */
+export declare const writeFaceMorphLive: (local: ArrayLike<number>, residual: ArrayLike<number>, point: Float32Array, expression: Float32Array) => void;
+/** Allocates the live arrays `writeFaceMorphLive` fills. */
+export declare const createFaceMorphLive: () => {
+    point: Float32Array<ArrayBuffer>;
+    expression: Float32Array<ArrayBuffer>;
+};
+export type FaceMorphStepOptions = {
+    /** 0 = the live face, 1 = the shape. */
+    weight: number;
+    /** Expression strength on the shape (0 = none, 1 = the face's, > 1 exaggerates). */
+    expression: number;
+    /** Scale of the shape around the head frame's origin. */
+    scale: number;
+};
+/**
+ * One frame of a morphing mesh, in the canonical head frame: for each vertex,
+ * its shape position (`shape`, cm, flat) blended toward its bound point on
+ * the live face by `(1 − weight) · coverage`. The shape itself takes the
+ * expression (`expression × coverage`). `out` gets canonical cm, flat.
+ */
+export declare const stepFaceMorph: (binding: Pick<FaceReprojectionBinding, "triangle" | "weights" | "coverage">, shape: ArrayLike<number>, live: {
+    point: Float32Array;
+    expression: Float32Array;
+}, { weight, expression, scale }: FaceMorphStepOptions, out: Float32Array) => void;

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

@@ -0,0 +1,46 @@
+import { FaceBlendshapeName } from '../face-info/blendshapes';
+/**
+ * The expression channels a face rig publishes: MediaPipe's 51 face
+ * blendshapes (ARKit's names — `browDownLeft` … `noseSneerRight`; MediaPipe
+ * has no `tongueOut`), without `_neutral`. "Left" is
+ * the side of landmark 263, the person's own left in the image MediaPipe sees,
+ * the same side ARKit names `Left` (and a Face Cap model `_L`).
+ */
+export declare const FACE_MORPH_NAMES: Exclude<FaceBlendshapeName, "_neutral">[];
+export type FaceMorphName = (typeof FACE_MORPH_NAMES)[number];
+/**
+ * The expression channel a morph target drives, by its name, or -1. Accepts
+ * the ARKit names (`eyeBlinkLeft`), Face Cap / Blender style sides
+ * (`eyeBlink_L`, `eyeBlink.R`, `eyeBlink_left`), any case, and exporter
+ * prefixes (`blendShape1.eyeBlink_L`, `Head_mesh.jawOpen`).
+ */
+export declare const faceMorphChannel: (morphName: string) => number;
+/**
+ * Which part of the face an expression channel moves. In `"hybrid"` driving,
+ * `eyes` and `brows` come from the model's own morph targets (the authored
+ * lids and brows), the rest from the tracked landmarks. (`tongue` is reserved
+ * for trackers that report it; MediaPipe does not.)
+ */
+export type FaceMorphRegion = "eyes" | "brows" | "mouth" | "tongue";
+export declare const faceMorphRegion: (channel: number) => FaceMorphRegion;
+/** The channels of the gaze (eyeball turn), per side. */
+export declare const FACE_GAZE_CHANNELS: {
+    readonly left: {
+        readonly in: number;
+        readonly out: number;
+        readonly up: number;
+        readonly down: number;
+    };
+    readonly right: {
+        readonly in: number;
+        readonly out: number;
+        readonly up: number;
+        readonly down: number;
+    };
+};
+/**
+ * Per landmark, how much it belongs to a region (1 inside, fading to 0
+ * around it, canonical distances): `eyes` = the eyelids and the eye
+ * surroundings up to the brow, `brows` = the eyebrows.
+ */
+export declare const FACE_REGION_MASKS: Record<"eyes" | "brows", Float32Array>;

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

@@ -0,0 +1,138 @@
+import { FaceImageLandmark } from './faceReprojection';
+/** Longest side a photo is analysed and baked at, in pixels. */
+export declare const FACE_PHOTO_MAX_SIZE = 1280;
+/**
+ * The canvas size a `width` × `height` photo is drawn at: its longest side at
+ * most `maxSize`, the aspect kept, never upscaled. `scale` is canvas pixels per
+ * photo pixel (1 when the photo already fits).
+ */
+export declare const fitPhotoCanvasSize: (width: number, height: number, maxSize?: number) => {
+    width: number;
+    height: number;
+    scale: number;
+};
+/** A face's landmark bounds in a still image, normalized (0..1, y down). */
+export type FaceImageBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** One face found in a still image by `detectFaceImage`. */
+export type FaceImageDetection = {
+    /**
+     * The 478 points (468 mesh + 10 iris), as the live tracker reports them:
+     * normalized image x / y (0..1, y down), z in x units. MediaPipe's sides:
+     * landmark 263 is on the image's right for a face looking at the camera.
+     */
+    landmarks: FaceImageLandmark[];
+    /** Blendshape scores (0..1) by MediaPipe name (`jawOpen`, `eyeBlinkLeft`, …). */
+    blendshapes: Record<string, number>;
+    /** The facial transformation matrix (canonical face → camera, column-major 4×4), or null. */
+    matrix: number[] | null;
+    /** The landmarks' bounds. */
+    box: FaceImageBox;
+};
+/** Bounds of a landmark set (normalized). Empty input gives a zero box at the centre. */
+export declare const faceImageBox: (landmarks: ReadonlyArray<FaceImageLandmark>) => FaceImageBox;
+/**
+ * Which face of a photo to use: `"largest"` (the widest), or a number that
+ * counts faces left to right in the image (0 = leftmost). Not the live target
+ * face: that is `FaceSwap`'s `faceIndex`.
+ */
+export type FacePhotoPick = "largest" | number;
+/**
+ * Indices into `detections`, ordered left to right by box centre x as the
+ * image is stored (canvas x, upright; a mirrored selfie is not flipped). Ties
+ * keep their order.
+ */
+export declare const faceImageOrderLeftToRight: (detections: ReadonlyArray<FaceImageDetection>) => number[];
+/**
+ * The face to use. `"largest"` (default) is the widest face, the same rule as
+ * the live multi-subject policy (`selectSubject`). A number counts faces left
+ * to right (`faceImageOrderLeftToRight`, 0 = leftmost), whatever order the
+ * detector reported them in, so a UI can label them. `index` is the picked
+ * face's index in `detections`. Null when there is no such face.
+ */
+export declare const pickFaceImageDetection: (detections: ReadonlyArray<FaceImageDetection>, pick?: FacePhotoPick) => {
+    detection: FaceImageDetection;
+    index: number;
+} | null;
+/**
+ * What can be wrong with a usable photo. Each one still bakes, but looks worse:
+ * - `turned`: the head is turned away (the far cheek is filled from the near one);
+ * - `eyesClosed`: an eye is closed (shows when the photo's eyes are used, `ownEyes` off);
+ * - `mouthOpen`: the mouth is open (the lips stretch over the user's mouth);
+ * - `small`: the face is small in the photo (the swapped face looks soft);
+ * - `severalFaces`: more than one face was found (the largest is used unless another is picked).
+ */
+export declare const FACE_PHOTO_WARNINGS: readonly ["turned", "eyesClosed", "mouthOpen", "small", "severalFaces"];
+export type FacePhotoWarning = (typeof FACE_PHOTO_WARNINGS)[number];
+/** Where each warning starts. */
+export declare const FACE_PHOTO_WARNING_LIMITS: Readonly<{
+    /** `turned`: head yaw beyond this, in degrees. */
+    turnedDegrees: 25;
+    /** `eyesClosed`: `eyeBlinkLeft` or `eyeBlinkRight` above this. */
+    eyeBlink: 0.5;
+    /** `mouthOpen`: `jawOpen` above this. */
+    jawOpen: 0.3;
+    /** `small`: distance between the eye centres below this, in pixels of the analysed photo canvas. */
+    interocularPixels: 60;
+}>;
+/**
+ * How far the head is turned left or right, in degrees (0 = facing the
+ * camera, unsigned), from the facial transformation matrix (column-major,
+ * camera at the origin looking down −Z): the angle around the vertical between
+ * the face's forward axis (canonical +Z, the third column) and the ray from
+ * the face back to the camera (minus the translation). MediaPipe fits the pose
+ * through a perspective camera, so a face near the edge of a photo that looks
+ * into the lens is rotated by about its ray angle; against the ray it reads 0,
+ * and a face turned toward the centre reads its real turn. A matrix without
+ * depth (translation z = 0) is measured against the optical axis. Null
+ * without a matrix.
+ */
+export declare const faceImageYawDegrees: (matrix: ArrayLike<number> | null) => number | null;
+/**
+ * Distance between the two eye centres in pixels of a `width` × `height`
+ * image: the iris centres (468, 473) when the 478-point model reported them,
+ * else the midpoints of each eye's corners; 0 when there are too few points.
+ */
+export declare const faceImageInterocularPixels: (landmarks: ReadonlyArray<FaceImageLandmark>, width: number, height: number) => number;
+/**
+ * The warnings for `detection` (the face in use) among `detections` (every
+ * face found) in a `size.width` × `size.height` photo canvas, in
+ * `FACE_PHOTO_WARNINGS` order.
+ */
+export declare const resolveFacePhotoWarnings: (detection: FaceImageDetection, detections: ReadonlyArray<FaceImageDetection>, size: {
+    width: number;
+    height: number;
+}) => FacePhotoWarning[];
+/**
+ * Why a photo or painted face could not be made:
+ * - `noFace`: no face was found in the photo;
+ * - `decode`: the image could not be decoded;
+ * - `cors`: the URL could not be fetched (CORS, network or HTTP error);
+ * - `model`: the face model could not be loaded;
+ * - `aborted`: the load was cancelled (a newer source replaced it, or unmount).
+ */
+export declare const FACE_TEXTURE_ERROR_CODES: readonly ["noFace", "decode", "cors", "model", "aborted"];
+export type FaceTextureErrorCode = (typeof FACE_TEXTURE_ERROR_CODES)[number];
+export type FaceTextureError = {
+    code: FaceTextureErrorCode;
+    message: string;
+};
+/**
+ * A thrown `FaceTextureError`: an `Error` with a `code`. Internal (SDK code
+ * only, not exported from a door): apps receive the plain `FaceTextureError`.
+ */
+export declare class FaceTextureLoadError extends Error implements FaceTextureError {
+    readonly code: FaceTextureErrorCode;
+    /** The underlying error, when there was one. */
+    readonly cause: unknown;
+    constructor(code: FaceTextureErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Any thrown value as a `FaceTextureError` (an `AbortError` → `aborted`;
+ * anything else unknown → `decode`). Internal, like `FaceTextureLoadError`.
+ */
+export declare const toFaceTextureError: (error: unknown) => FaceTextureError;

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

@@ -0,0 +1,116 @@
+import { FacePinOrient } from './facePin';
+/**
+ * Named piercing spots on the live face (FACE-10). Left and right are the
+ * person's REAL left and right on every source: on a mirrored feed (the front
+ * webcam) the face mesh's own sides are swapped, so `resolveFacePiercing`
+ * takes the other side's placement there.
+ */
+export declare const FACE_PIERCING_NAMES: readonly ["nose.left", "nose.right", "septum", "lip.centre", "lip.left", "lip.right", "brow.left", "brow.right"];
+export type FacePiercingName = (typeof FACE_PIERCING_NAMES)[number];
+/**
+ * The jewellery a spot is placed for:
+ * - `"stud"` — a stud sits on the skin at the hole, its face out of the skin;
+ * - `"ring"` — a hoop passes through the skin at the hole and hangs (a
+ *   septum ring below the septum, a lip ring over the lip, a brow ring through
+ *   the brow).
+ */
+export type FacePiercingKind = "stud" | "ring";
+export declare const FACE_PIERCING_KINDS: readonly FacePiercingKind[];
+/** Position (cm) and rotation (degrees, XYZ order) of the jewellery frame in the pin frame. */
+export type FacePiercingOffset = {
+    position: readonly [number, number, number];
+    rotation: readonly [number, number, number];
+};
+/** Where one kind of jewellery sits on a spot. */
+export type FacePiercingPlacement = {
+    /**
+     * The hole, in the canonical head frame (cm) as on an unmirrored source
+     * (+X = the person's left). It is bound to the face surface under it.
+     */
+    at: readonly [number, number, number];
+    /** `"surface"`: the jewellery turns with the skin; `"head"`: with the head. */
+    orient: FacePinOrient;
+    /** The jewellery frame in the pin frame (see `FacePiercingPreset`). */
+    offset: FacePiercingOffset;
+};
+/**
+ * A named piercing spot. Jewellery for it is authored in the **piercing
+ * frame**, centimetres:
+ * - the origin is the hole, on the skin;
+ * - +Z is the piercing axis, out of the skin: a stud's face looks along +Z;
+ * - +Y is up;
+ * - a ring lies in the YZ plane, its wire passing through the origin, and
+ *   hangs toward −Y (its centre at `(0, −r, 0)` for a centre-line radius `r`).
+ *
+ * The placement turns that frame so the stud faces out of the skin and the
+ * ring hangs the way the real piercing does.
+ */
+export type FacePiercingPreset = {
+    name: FacePiercingName;
+    /** Human label, e.g. `"nostril (left)"`. */
+    label: string;
+    region: "nose" | "lip" | "brow";
+    /** The person's real side, or `"centre"`. */
+    side: "left" | "right" | "centre";
+    /** The classic jewellery for the spot (`FacePiercing`'s default `kind`). */
+    kind: FacePiercingKind;
+    /** Typical sizes (cm): a stud's face diameter, a ring's inner diameter. */
+    size: {
+        stud: number;
+        ring: number;
+    };
+    stud: FacePiercingPlacement;
+    ring: FacePiercingPlacement;
+};
+/** The same placement on the other side of the face (canonical X mirrored). */
+export declare const mirrorFacePiercingPlacement: (p: FacePiercingPlacement) => FacePiercingPlacement;
+/**
+ * The piercing presets: where each spot sits on the canonical face and how
+ * its jewellery is turned. Sided entries are given as on an unmirrored source
+ * (`*.left` at +X); `resolveFacePiercing` swaps them on a mirrored feed.
+ */
+export declare const FACE_PIERCINGS: Readonly<Record<FacePiercingName, FacePiercingPreset>>;
+/** A preset resolved for one feed: what a `PinToFaceMesh` needs. */
+export type ResolvedFacePiercing = {
+    /** The requested spot. */
+    name: FacePiercingName;
+    kind: FacePiercingKind;
+    /** The exact point on the canonical face surface (the hole). */
+    anchor: {
+        triangle: number;
+        weights: readonly [number, number, number];
+    };
+    orient: FacePinOrient;
+    /** The jewellery frame in the pin frame: position (cm), rotation (degrees). */
+    offset: FacePiercingOffset;
+    /** The typical size for the kind (cm): a stud's face diameter or a ring's inner diameter. */
+    size: number;
+    /**
+     * `true` when the placement is the mirror image of the left-side authoring
+     * (it sits at canonical −X): mirror your own jewellery offsets with it
+     * (`mirrorFacePiercingOffset`) so one offset fits both sides.
+     */
+    flip: boolean;
+};
+/**
+ * Resolves a piercing preset for a feed. `mirrored` is whether the feed is
+ * mirrored (the front webcam; `useXRMirrored()`): the face mesh's left is
+ * then the person's right, so a sided spot takes the other side's placement
+ * and stays on the person's real side. The anchor is the exact surface point
+ * under the preset's hole (cached). Throws on an unknown name.
+ */
+export declare const resolveFacePiercing: (name: FacePiercingName, { kind, mirrored }?: {
+    kind?: FacePiercingKind;
+    mirrored?: boolean;
+}) => ResolvedFacePiercing;
+/** A nudge in the piercing frame: `position` (cm), `rotation` (degrees, XYZ), `scale`. */
+export type FacePiercingNudge = {
+    position?: readonly [number, number, number];
+    rotation?: readonly [number, number, number];
+    scale?: number;
+};
+/**
+ * Mirrors a piercing-frame offset across the face (X negated, the Y and Z
+ * rotations negated, scale kept): the same nudge on the other side.
+ */
+export declare const mirrorFacePiercingOffset: (offset: FacePiercingNudge) => FacePiercingNudge;

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

@@ -0,0 +1,131 @@
+import { FaceRigState } from './faceRig';
+import * as THREE from "three";
+/**
+ * The named anchors a pin accepts (the SDK's face targets). Left / right are
+ * the person's own side on every feed when resolved for the feed
+ * (`facePinAnchorForFeed`, which `PinToFaceMesh` applies).
+ */
+export declare const FACE_PIN_TARGETS: readonly string[];
+/**
+ * The anchor to bind on this feed. A named target is the person's own side
+ * (`"face.leftCheek"` = their real left cheek); the canonical face's sides
+ * are MediaPipe's (its left at +X), which is the person's other side on a
+ * mirrored feed (the front webcam), so a sided name is swapped there.
+ * `{ landmark }`, `{ point }` and `{ triangle }` anchors are canonical-face
+ * positions and pass through.
+ */
+export declare const facePinAnchorForFeed: (anchor: FacePinAnchor, mirrored: boolean) => FacePinAnchor;
+/**
+ * Where on the face a pin sits:
+ * - a face target name (`"face.noseTip"`, `"face.leftCheek"`, `"face.forehead"`
+ *   … `FACE_PIN_TARGETS`; composites like `"face.leftEye"` project onto the skin;
+ *   left / right = the person's own side once `facePinAnchorForFeed` resolves it,
+ *   as `PinToFaceMesh` does);
+ * - `{ landmark }` — a MediaPipe face landmark index (0–467);
+ * - `{ point }` — a point in the canonical head frame (cm), bound to the face
+ *   surface under it (any spot, e.g. picked in the `.blend`);
+ * - `{ triangle, weights }` — an exact surface point: a canonical face triangle
+ *   (index into `CANONICAL_FACE_TRIANGLES / 3`) and barycentric weights.
+ */
+export type FacePinAnchor = string | {
+    landmark: number;
+} | {
+    point: readonly [number, number, number];
+} | {
+    triangle: number;
+    weights: readonly [number, number, number];
+};
+/** A pin bound to the canonical face surface (see `bindFacePin`). */
+export type FacePinBinding = {
+    triangle: number;
+    weights: [number, number, number];
+    /**
+     * Where the anchor point sits relative to its surface point at rest, in the
+     * pin's own frame (cm; [0, 0, 0] for an anchor on the skin) — so a `point`
+     * anchor above the skin stays there as the skin turns.
+     */
+    offset: [number, number, number];
+    /** Triangles around the anchor whose live normals are averaged for the orientation. */
+    patch: Int32Array;
+};
+/** How far around the anchor (cm) the orientation's surface normal is averaged. Default for `bindFacePin`. */
+export declare const FACE_PIN_PATCH_RADIUS = 1.2;
+/**
+ * Binds an anchor to the canonical face surface, once. Throws on an unknown
+ * target name or an out-of-range landmark / triangle.
+ */
+export declare const bindFacePin: (anchor: FacePinAnchor, { patchRadius }?: {
+    patchRadius?: number;
+}) => FacePinBinding;
+/** A piece of the canonical face surface: its landmarks and its triangles over them. */
+export type FaceSurfacePatch = {
+    /** The landmark indices the patch uses, ascending. */
+    landmarks: Uint16Array;
+    /** Its triangles as indices into `landmarks` (flat, 3 per triangle). */
+    index: Uint16Array;
+};
+/**
+ * The face triangles whose centres lie within `radius` cm (at rest) of a bound
+ * pin's point, or the whole face for `null`: the skin a `FaceSurfaceOccluder`
+ * draws. Pure.
+ */
+export declare const faceSurfacePatch: (around: {
+    triangle: number;
+    weights: readonly [number, number, number];
+} | null, radius?: number) => FaceSurfacePatch;
+/**
+ * Which face shape a pin follows:
+ * - `"face"` — the person's real face (their face shape + expression): for
+ *   accessories on the camera face;
+ * - `"model"` — the canonical face + expression (the person's own shape
+ *   removed), the surface an `ExternalFaceMesh` character wears.
+ */
+export type FacePinSurface = "face" | "model";
+/**
+ * How a pin turns: `"surface"` follows the live skin under it (a sticker on a
+ * smiling cheek tilts with it), `"head"` keeps the head's orientation (only the
+ * position follows the surface).
+ */
+export type FacePinOrient = "surface" | "head";
+/** A rig as a pin reads it; `view` / `local` (when given) correct a trailing pose. */
+export type FacePinRig = Pick<FaceRigState, "residual" | "neutral"> & Partial<Pick<FaceRigState, "view" | "local">>;
+type PinRig = FacePinRig;
+/**
+ * The live position of landmark `i` in the head frame (canonical cm), on the
+ * chosen surface — the surface a pin rides (`extra`: a `FaceWarp3D` /
+ * `FaceMorph` surface's landmark offsets, or `null`). Allocation-free.
+ */
+export declare const liveFaceLandmark: (rig: PinRig, surface: FacePinSurface, extra: ArrayLike<number> | null, i: number, out: THREE.Vector3) => THREE.Vector3;
+/**
+ * Where a pin is this frame, in the head frame (canonical cm — the `FaceRig`
+ * group's space): `position` on the live surface (plus the anchor's rest lift
+ * along the normal) and `quaternion` = the surface frame (X along the face
+ * toward +X, Y up, Z out of the skin), or the head's (identity) with
+ * `orient: "head"`. Allocation-free.
+ */
+export declare const stepFacePin: (binding: FacePinBinding, rig: PinRig, { surface, orient, offsets, }: {
+    surface?: FacePinSurface;
+    orient?: FacePinOrient;
+    /**
+     * Per-landmark displacements of the surface (canonical cm, flat, 468 × 3)
+     * — a `FaceWarp3D` / `FaceMorph` surface (`FaceSurfaceState.offsets`).
+     */
+    offsets?: ArrayLike<number> | null;
+} | undefined, out: {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+}) => {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+};
+/**
+ * How far along its rest surface normal (cm, + = out of the face) a pin must
+ * move to sit on `model` — a face model in the head frame (an
+ * `ExternalFaceMesh`'s scene) whose skin is not exactly the canonical surface.
+ * Casts from `reach` cm outside the face inward (then from inside outward;
+ * 8 cm by default, so a stylised head's bulging cheeks and brow are found);
+ * `headFrame` is the `FaceRig` group (the head frame in world space). `null`
+ * when the ray misses. Add the result to the binding's `offset[2]`.
+ */
+export declare const projectFacePinOnto: (binding: FacePinBinding, model: THREE.Object3D, headFrame: THREE.Object3D, reach?: number) => number | null;
+export {};