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

package/dist/components/FaceCharacter/FaceMorph.d.ts

@@ -0,0 +1,71 @@
+import { ReactNode } from 'react';
+import { FaceMorphShapeName } from '../../face-character/faceMorph';
+import { FaceReprojectionRegion, FaceReprojectionShading } from '../../face-character/faceReprojection';
+import { FaceFeatureAlignment } from '../../face-character/featureWarp';
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceRigProps } from './FaceRig';
+import * as THREE from "three";
+export type FaceMorphProps = Omit<FaceRigProps, "children"> & {
+    /**
+     * What the face morphs into: a built-in `"sphere"` / `"cube"`, or a model
+     * (e.g. a GLTF scene) in the canonical head frame (cm, like
+     * `ExternalFaceMesh`). A model's mesh with a morph target named `morphKey`
+     * morphs into that shape key, its base positions binding it to the face
+     * (the Blender workflow: sculpt the key from a face-fitting basis);
+     * without one, the mesh is its own base.
+     */
+    shape: FaceMorphShapeName | THREE.Object3D;
+    /** 0 = the person's live face, 1 = the shape (or a ref, read every frame). Default 1. */
+    weight?: LiveValue<number>;
+    /** How strongly the shape takes the face's expression (Snap's Expression Multiplier; or a ref). Default 1. */
+    expression?: LiveValue<number>;
+    /** Scale of the shape around the head (Snap's External Scale). Default 1. */
+    scale?: number;
+    /** The shape key a model morphs into. Default `"morph"`. */
+    morphKey?: string;
+    /**
+     * A stylised model's own eye / mouth / nose / chin positions (its
+     * canonical-frame cm): it binds as if those sat on the real face's, so
+     * your eyes flow into its eyes as it morphs. See `FaceFeatureAlignment`.
+     */
+    align?: FaceFeatureAlignment;
+    /**
+     * How much of the camera face the shape wears, 0..1 — 0 shows the shape's
+     * own material (a character's skin), 1 the face. Default 1.
+     */
+    faceTexture?: number;
+    /** Which part of the camera face it wears (see `FaceReprojectionRegion`). Default `"face"`. */
+    region?: FaceReprojectionRegion;
+    /** `"unlit"` (default): the camera's colours; `"lit"`: shaded by the scene lights. */
+    shading?: FaceReprojectionShading;
+    /** Base colour of a built-in shape where it shows no face. Default `"#f1c6a8"`. */
+    color?: THREE.ColorRepresentation;
+    /** Subdivisions of a built-in shape (smoother edges and corners). Default 2. */
+    subdivisions?: number;
+    /** How far from the face (cm, base pose) a model's vertex still morphs and wears it. Default `[1, 3]`. */
+    falloff?: readonly [number, number];
+    /** Facing cut-off of the camera face (see `FaceUnwrapFrameOptions`). Default `[0.05, 0.3]`. */
+    facing?: readonly [number, number];
+    /** Camera face texture size, px. Default 512. */
+    unwrapResolution?: number;
+    /** Most texture updates per second (`0` = every new camera frame). Default 30. */
+    fps?: number;
+    /** More content in the canonical head frame. A `PinToFaceMesh` here rides the morphing face. */
+    children?: ReactNode;
+};
+/**
+ * The person's face morphing into another shape — a sphere, a cube, a
+ * character — wearing their live camera face all the way (Snap's Face
+ * Morph). `weight` 0 is the live face itself, 1 the shape, which still moves
+ * with the expression (`expression`). A model morphs from its base positions
+ * (where it sits on a face) into its `morphKey` shape key; `faceTexture`
+ * fades between the camera face and the model's own material. Mount inside a
+ * `FaceTracker` (it runs its own `FaceRig`) or a `FaceRig`.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <FaceMorph shape="sphere" weight={0.8} />
+ * </FaceTracker>
+ * ```
+ */
+export declare const FaceMorph: ({ faceIndex, smoothing, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, ...props }: FaceMorphProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceCharacter/FacePiercing.d.ts

@@ -0,0 +1,65 @@
+import { ReactNode, RefObject } from 'react';
+import { FacePinSurface } from '../../face-character/facePin';
+import { FacePiercingKind, FacePiercingName, FacePiercingNudge } from '../../face-character/facePiercings';
+import { FaceRigProps } from './FaceRig';
+import * as THREE from "three";
+/** Rig props a piercing forwards when it runs its own rig. */
+type PiercingRigProps = Omit<FaceRigProps, "children" | "smoothing">;
+export type FacePiercingProps = PiercingRigProps & {
+    /**
+     * The spot: `"nose.left"`, `"nose.right"`, `"septum"`, `"lip.centre"`,
+     * `"lip.left"`, `"lip.right"`, `"brow.left"`, `"brow.right"`
+     * (`FACE_PIERCING_NAMES`). Left and right are the person's real sides.
+     */
+    preset: FacePiercingName;
+    /** `"stud"` or `"ring"`. Defaults to the spot's classic kind (`FACE_PIERCINGS[preset].kind`). */
+    kind?: FacePiercingKind;
+    /**
+     * Whether the feed is mirrored. Defaults to the session's (`useXRMirrored`:
+     * the front webcam is), which is what keeps `"left"` on the person's left.
+     */
+    mirrored?: boolean;
+    /**
+     * Hide what passes behind the skin (a ring's inner half) with a depth-only
+     * patch of the live face around the hole. Default `true`; off with `onto`
+     * (a worn character's own depth hides it).
+     */
+    occlude?: boolean;
+    /** `"face"` (default): the person's real face; `"model"`: the canonical face (a worn character). */
+    surface?: FacePinSurface;
+    /** Per-frame EMA on the pin, `1` = none (default). */
+    smoothing?: number;
+    /** A worn face model to sit on (see `PinToFaceMesh`'s `onto`). */
+    onto?: RefObject<THREE.Object3D | null> | THREE.Object3D | null;
+    /**
+     * A nudge in the piercing frame: `position` (cm), `rotation` (degrees),
+     * `scale`. Mirrored with the spot, so one offset fits a left / right pair.
+     */
+    offset?: FacePiercingNudge;
+    /**
+     * The jewellery, authored in the piercing frame (cm; origin the hole, +Z out
+     * of the skin, +Y up; a ring in the YZ plane hanging toward −Y from the
+     * origin). Default: a plain silver stud or ring sized for the spot.
+     */
+    children?: ReactNode;
+};
+/**
+ * Jewellery on a named piercing spot of the live face: nostril, septum, lip
+ * (centre / labret, sides) and brow. A preset over `PinToFaceMesh`: it knows
+ * where the hole is on the face mesh and how a stud or ring sits there (a stud
+ * faces out of the skin, a septum ring hangs below the septum, a lip ring
+ * wraps the lip, a brow ring goes through the brow), so no landmark lookup is
+ * needed. It rides the face through expressions; left and right are the
+ * person's real sides on every feed. Wrap several in one `FaceRig`.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <FaceRig>
+ *     <FacePiercing preset="nose.left" />
+ *     <FacePiercing preset="septum" kind="ring"><MyRing /></FacePiercing>
+ *   </FaceRig>
+ * </FaceTracker>
+ * ```
+ */
+export declare const FacePiercing: ({ preset, kind, mirrored, occlude, surface, smoothing, onto, offset, children, faceIndex, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, }: FacePiercingProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/FaceCharacter/FaceReprojection.d.ts

@@ -0,0 +1,85 @@
+import { FaceFeatureAlignment } from '../../face-character/featureWarp';
+import { FaceReprojectionRegion, FaceReprojectionShading } from '../../face-character/faceReprojection';
+import type * as THREE from "three";
+export type FaceReprojectionProps = {
+    /**
+     * Which of the model's meshes wear the camera face, by object name. Default:
+     * every `"surface"` part (the skin; not eyeballs or teeth). UVs are not
+     * needed to wear it; the atlas texture (`onTexture`) covers the meshes that
+     * have them, which must share one atlas.
+     */
+    meshes?: readonly string[];
+    /**
+     * A stylised character's own eye / mouth / nose / chin positions (its
+     * canonical-frame cm): the camera face is laid on it as if those sat on the
+     * real face's — your eyes on its (big, low) eyes. See `FaceFeatureAlignment`.
+     */
+    align?: FaceFeatureAlignment;
+    /** Which part of the camera face to take (see `FaceReprojectionRegion`). Default `"face"`. */
+    region?: FaceReprojectionRegion;
+    /** How much of the camera face shows, 0..1. Default 1. */
+    amount?: number;
+    /** `"unlit"` (default): as the camera saw it; `"lit"`: shaded by the scene lights. */
+    shading?: FaceReprojectionShading;
+    /**
+     * A mask in the model's own UV layout (red channel; load it like the
+     * model's own map — glTF textures have `flipY = false`).
+     */
+    mask?: THREE.Texture | null;
+    /** A mask in the canonical face UV layout (red channel), e.g. painted over the canonical face texture. */
+    canonicalMask?: THREE.Texture | null;
+    /** Output texture size, px. Default 1024. */
+    resolution?: number;
+    /** Unwrapped (canonical layout) texture size, px. Default 512. */
+    unwrapResolution?: number;
+    /** Edge padding around the model's UV islands, px (0–4). Default 2. */
+    padding?: number;
+    /** Most updates per second (`0` = every new camera frame). Default 30. */
+    fps?: number;
+    /** Facing cut-off as cosines `[hidden, full]` (see `FaceUnwrapFrameOptions`). Default `[0.05, 0.3]`. */
+    facing?: readonly [number, number];
+    /** Distance from the canonical face (cm) over which the model stops taking it. Default `[1, 3]`. */
+    falloff?: readonly [number, number];
+    /**
+     * Skin beyond the face (`region="face"` only; skin parts, not eyes): the
+     * neck, ears, scalp and back of the head take the person's skin. Next to
+     * the face it continues the real edge skin (push-pull from the face's
+     * edge); farther out it settles to the face's average skin colour. It
+     * shades like the face (`shading`). Default `false`.
+     */
+    fill?: boolean;
+    /** cm from the face where the fill has faded back to the model's own material. Default 30. */
+    fillReach?: number;
+    /**
+     * Put the camera face on the meshes' materials (a patched clone of each,
+     * reading it per vertex — no UVs needed; restored on unmount). `false`:
+     * only render the atlas texture — use `onTexture` and your own material.
+     * Default `true`.
+     */
+    apply?: boolean;
+    /**
+     * The textures once created: `texture` (the face in the meshes' own UV
+     * atlas — rendered only when this is given or `apply` is `false`) and
+     * `unwrap` (the canonical layout).
+     */
+    onTexture?: (textures: {
+        texture: THREE.Texture;
+        unwrap: THREE.Texture;
+    }) => void;
+};
+/**
+ * The live camera face, worn by a face model (`ExternalFaceMesh`) — any
+ * topology, any UV atlas (or none). The camera face is unwrapped into the
+ * canonical face UV layout (the eyes and the inside of the mouth included),
+ * and each vertex wears it at its closest point on the canonical face (after
+ * `align` for a stylised character). The whole face, or only the eyes and /
+ * or mouth (`region`). `onTexture` also gets it remapped into the model's own
+ * atlas, for a custom material. Mount it as a child of an `ExternalFaceMesh`.
+ *
+ * ```tsx
+ * <ExternalFaceMesh model={gltf.scene}>
+ *   <FaceReprojection region="eyesAndMouth" />
+ * </ExternalFaceMesh>
+ * ```
+ */
+export declare const FaceReprojection: ({ meshes: names, align, region, amount, shading, mask, canonicalMask, resolution, unwrapResolution, padding, fps, facing, falloff, fill, fillReach, apply, onTexture, }: FaceReprojectionProps) => null;

package/dist/components/FaceCharacter/FaceRig.d.ts

@@ -0,0 +1,38 @@
+import { MutableRefObject, PropsWithChildren } from 'react';
+import { FaceRigOptions, FaceRigState } from '../../face-character/faceRig';
+export type FaceRigProps = PropsWithChildren<FaceRigOptions & {
+    /**
+     * Which tracked face drives it. Defaults to the parent `FaceTracker`'s (or
+     * `HeadBinding`'s) `faceIndex`.
+     */
+    faceIndex?: number;
+    /** Fires once on face found (`true`) and once on face lost (`false`). */
+    onTrackingChange?: (tracked: boolean) => void;
+    /**
+     * A new value captures the neutral (rest) face again from the next frames
+     * — e.g. bump it from a "Recalibrate" button while the person relaxes.
+     */
+    neutralKey?: unknown;
+}>;
+/** The rig a `FaceRig` publishes to its subtree (read it in `useFrame`). */
+export declare const FaceRigContext: import('react').Context<MutableRefObject<FaceRigState> | null>;
+/**
+ * The live face rig of the nearest `FaceRig` above: head pose, the landmarks
+ * in the head frame and the per-landmark expression offsets. Read
+ * `rig.current` inside `useFrame` (it changes every frame without
+ * re-rendering). `null` outside a `FaceRig`.
+ */
+export declare const useFaceRig: () => MutableRefObject<FaceRigState> | null;
+/**
+ * A group, inside a `FaceTracker`, whose children are authored in canonical
+ * centimetres (the same frame as `CanonicalHeadFrame`) and that also tracks the
+ * face's EXPRESSION: every frame it re-expresses the 468 landmarks in the head
+ * frame and publishes their offsets from the canonical rest (`useFaceRig`).
+ * Face-character components inside it (`ExternalFaceMesh`, …) share that one
+ * rig. Holds its last pose through dropouts shorter than `holdMs`, hides when
+ * lost, snaps on reacquire. `leadMs` (default 0) runs the landmarks through
+ * a `LandmarkLead` so its geometry keeps up with the camera image between
+ * inferences; makeup nested inside rides this rig with the same lead. The
+ * frame step itself is `stepFaceRigFromModel`.
+ */
+export declare const FaceRig: ({ children, faceIndex: faceIndexOption, onTrackingChange, neutralKey, ...options }: FaceRigProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceCharacter/FaceSurface.d.ts

@@ -0,0 +1,49 @@
+import { MutableRefObject } from 'react';
+import { Object3D } from 'three';
+/**
+ * How a face effect moves the face's surface this frame: per landmark, its
+ * displacement from the tracked face (canonical cm, flat, 468 × 3). Published
+ * by `FaceWarp3D` and `FaceMorph` to their children, before they update, so a
+ * `PinToFaceMesh` inside them rides the warped or morphed face.
+ */
+export type FaceSurfaceState = {
+    offsets: Float32Array;
+    /** `false` while nothing is moved (offsets all zero). */
+    active: boolean;
+};
+export declare const createFaceSurfaceState: () => FaceSurfaceState;
+export declare const FaceSurfaceContext: import('react').Context<MutableRefObject<FaceSurfaceState> | null>;
+/** The nearest `FaceWarp3D` / `FaceMorph` surface above (read in `useFrame`), or `null`. */
+export declare const useFaceSurface: () => MutableRefObject<FaceSurfaceState> | null;
+/**
+ * The frame priority of effects that publish a face surface: after the
+ * `FaceRig` (-1), before ordinary children (0) such as pins.
+ */
+export declare const FACE_SURFACE_FRAME_PRIORITY = -0.5;
+/**
+ * Render order of everything that IS the face (`FaceWarp3D`, `FaceMorph`, an
+ * `ExternalFaceMesh` character): before the head occluder
+ * (`HEAD_OCCLUDER_RENDER_ORDER`, -1), so the occluder hides accessories behind
+ * the head but never the face itself, wherever an effect moves it. The hand
+ * cut-out (-900) still comes first, so hands stay in front.
+ */
+export declare const FACE_SURFACE_RENDER_ORDER = -2;
+/**
+ * Puts a subtree's drawables (meshes, points, lines) in the face layer. Not
+ * its groups: three sorts by the nearest group's render order first, so a
+ * group set apart would leave the shared tier (and draw before the camera
+ * background).
+ */
+export declare const markFaceSurface: (root: Object3D) => void;
+/**
+ * Blending for a face effect drawn in the opaque pass (where the render order
+ * puts it before the occluder) that still fades at its edges: normal alpha
+ * blending, set as custom so three applies it to a non-transparent material.
+ */
+export declare const faceSurfaceBlending: {
+    readonly blending: 5;
+    readonly blendSrc: 204;
+    readonly blendDst: 205;
+    readonly blendSrcAlpha: 201;
+    readonly blendDstAlpha: 205;
+};

package/dist/components/FaceCharacter/FaceSurfaceOccluder.d.ts

@@ -0,0 +1,39 @@
+import { FacePinAnchor, FacePinSurface, FaceSurfacePatch } from '../../face-character/facePin';
+import { FaceRigProps } from './FaceRig';
+export type FaceSurfaceOccluderProps = Omit<FaceRigProps, "children" | "smoothing"> & {
+    /** The surface to occlude with: the person's real face (`"face"`, default) or the canonical one (`"model"`). */
+    surface?: FacePinSurface;
+    /**
+     * Only the skin around this point (a `PinToFaceMesh` anchor; a named left /
+     * right one is the person's own side, as on the pin); the whole face when
+     * omitted.
+     */
+    around?: FacePinAnchor;
+    /**
+     * Whether the feed is mirrored. Defaults to the session's (`useXRMirrored`:
+     * the front webcam is), so a named `around` lands where the same-named
+     * `PinToFaceMesh` does.
+     */
+    mirrored?: boolean;
+    /** How far around `around` (cm, default 2.5). */
+    radius?: number;
+    /** Render order of the occluder mesh. Default `-1` (the head occluder's tier: after the face, before accessories). */
+    renderOrder?: number;
+    /** Draw it visibly (a translucent wireframe) to check what it covers. Never ship it on. */
+    debug?: boolean;
+};
+/**
+ * The patch of skin a `FaceSurfaceOccluder` covers on this feed: around the
+ * same surface point a `PinToFaceMesh` with the same anchor binds
+ * (`facePinAnchorForFeed`), or the whole face without `around`.
+ */
+export declare const faceSurfaceOccluderPatch: (around: FacePinAnchor | undefined, radius: number, mirrored: boolean) => FaceSurfacePatch;
+/**
+ * A depth-only mesh of the live face surface: the same skin a `PinToFaceMesh`
+ * rides (face shape + expression, and a `FaceWarp3D` / `FaceMorph` surface
+ * when inside one). Content behind the skin is hidden: the half of a ring that
+ * passes through a nostril or a brow, a stud's post. `around` + `radius` keep
+ * it to a patch of skin (a piercing mounts its own). Runs on the nearest
+ * `FaceRig` (or its own, inside a `FaceTracker`).
+ */
+export declare const FaceSurfaceOccluder: ({ surface, around, mirrored, radius, renderOrder, debug, faceIndex, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, }: FaceSurfaceOccluderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceCharacter/PinToFaceMesh.d.ts

@@ -0,0 +1,68 @@
+import { ReactNode, RefObject } from 'react';
+import { FacePinAnchor, FacePinOrient, FacePinSurface } from '../../face-character/facePin';
+import { FaceRigProps } from './FaceRig';
+import * as THREE from "three";
+/** Rig props a pin forwards when it runs its own rig (the pose smoothing stays the rig default). */
+type PinRigProps = Omit<FaceRigProps, "children" | "smoothing">;
+export type PinToFaceMeshProps = PinRigProps & {
+    /**
+     * Where on the face: a face target name (`"face.noseTip"`, `"face.leftCheek"`
+     * …; left / right = the person's own side on every feed), `{ landmark }`,
+     * `{ point }` (canonical cm) or `{ triangle, weights }`. See `FacePinAnchor`.
+     */
+    anchor: FacePinAnchor;
+    /**
+     * Whether the feed is mirrored. Defaults to the session's (`useXRMirrored`:
+     * the front webcam is), which is what keeps a named `"face.left…"` anchor
+     * on the person's own left.
+     */
+    mirrored?: boolean;
+    /** Follow the person's real face (`"face"`, default) or the canonical / character face (`"model"`). */
+    surface?: FacePinSurface;
+    /** `"surface"` (default): turn with the skin under it; `"head"`: keep the head's orientation. */
+    orient?: FacePinOrient;
+    /**
+     * An offset in the pin's frame (X along the face toward the screen's right
+     * on a face looking at the camera, Y up, Z out of the skin): `position` in
+     * centimetres, `rotation` in degrees, `scale` a factor.
+     */
+    offset?: {
+        position?: readonly [number, number, number];
+        rotation?: readonly [number, number, number];
+        scale?: number;
+    };
+    /**
+     * Per-frame EMA on the pin's position and turn, `1` = none (default: the
+     * rig's expression smoothing already steadies the surface).
+     */
+    smoothing?: number;
+    /**
+     * A face model to sit on (an `ExternalFaceMesh`'s group, in the same rig):
+     * once it has loaded, the pin moves along the surface normal onto that
+     * model's own skin — a character whose cheek or lip is not exactly the
+     * canonical surface — then rides the expression from there.
+     */
+    onto?: RefObject<THREE.Object3D | null> | THREE.Object3D | null;
+    /** The pinned content, authored in centimetres around its origin. */
+    children?: ReactNode;
+};
+/**
+ * Pins content to a point on the live face surface: it follows the head AND
+ * the skin under it through expressions (a cheek sticker rides a smile, a
+ * lip stud follows the mouth), turning with the surface. Anchor by face target
+ * name, landmark index, canonical point or exact triangle; offset in the pin's
+ * own frame. Unlike the generic `PinToMesh`, the surface it follows moves every
+ * frame. Inside a `FaceRig` (or an `ExternalFaceMesh`'s children) it shares
+ * that rig; otherwise it runs its own (mount it in a `FaceTracker`). Hidden
+ * while the face is lost; snaps on reacquire.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <PinToFaceMesh anchor="face.leftCheek" offset={{ position: [0, 0, 0.1] }}>
+ *     <mesh><circleGeometry args={[1.2, 32]} /></mesh>
+ *   </PinToFaceMesh>
+ * </FaceTracker>
+ * ```
+ */
+export declare const PinToFaceMesh: ({ faceIndex, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, ...props }: PinToFaceMeshProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/FaceCharacter/index.d.ts

@@ -0,0 +1,18 @@
+export { FaceRig, FaceRigContext, useFaceRig } from './FaceRig';
+export type { FaceRigProps } from './FaceRig';
+export { ExternalFaceMesh, ExternalFaceMeshContext, FACE_HEAD_WIDTH_RATIO, faceHeadWidth, useExternalFaceMesh, } from './ExternalFaceMesh';
+export type { ExternalFaceMeshBinding, ExternalFaceMeshPart, ExternalFaceMeshProps, } from './ExternalFaceMesh';
+export { FaceExpressionController, useExpressionValues } from './FaceExpressionController';
+export type { FaceExpressionControllerProps, FaceExpressionControllerRule, ExpressionOutputs, UseExpressionValuesResult, } from './FaceExpressionController';
+export { PinToFaceMesh } from './PinToFaceMesh';
+export type { PinToFaceMeshProps } from './PinToFaceMesh';
+export { FacePiercing } from './FacePiercing';
+export type { FacePiercingProps } from './FacePiercing';
+export { FaceSurfaceOccluder } from './FaceSurfaceOccluder';
+export type { FaceSurfaceOccluderProps } from './FaceSurfaceOccluder';
+export { FaceReprojection } from './FaceReprojection';
+export type { FaceReprojectionProps } from './FaceReprojection';
+export { FaceMorph } from './FaceMorph';
+export type { FaceMorphProps } from './FaceMorph';
+export { FACE_SURFACE_FRAME_PRIORITY, FACE_SURFACE_RENDER_ORDER, FaceSurfaceContext, faceSurfaceBlending, createFaceSurfaceState, markFaceSurface, useFaceSurface, } from './FaceSurface';
+export type { FaceSurfaceState } from './FaceSurface';

package/dist/components/FaceCharacter/useFaceReprojector.d.ts

@@ -0,0 +1,10 @@
+import { FaceReprojector, FaceReprojectorOptions } from '../../face-character/faceReprojector';
+/**
+ * A `FaceReprojector` for this component's lifetime (created after mount,
+ * disposed on unmount), kept in step with `options` (sizes, padding, facing;
+ * `null` until created). Rendered every new camera frame of the nearest
+ * `FaceRig`'s face (at most `fps` a second, `0` = every frame) while that
+ * face is tracked; through a dropout the textures keep the last face.
+ * Inside a `<MadeUpCamera>` it unwraps the made-up camera (the makeup shows).
+ */
+export declare const useFaceReprojector: (options: Pick<FaceReprojectorOptions, "resolution" | "unwrapResolution" | "padding" | "facing" | "unwrapMipmaps">, fps: number) => FaceReprojector | null;

package/dist/components/FaceInset/FaceInset.d.ts

@@ -0,0 +1,68 @@
+import { FaceTarget } from '../../types/tracking';
+import { FaceInsetPart } from './frame';
+/**
+ * An inset's draw order on the face: after the face itself (`FaceWarp3D`,
+ * `FaceMorph`, a character, at `FACE_SURFACE_RENDER_ORDER`), so it shows on
+ * top of them, and before the head occluder (-1).
+ */
+export declare const FACE_INSET_RENDER_ORDER: number;
+/** Where an inset is shown: over the face, or as a plane in its parent's frame. */
+export declare const FACE_INSET_PLACEMENTS: readonly ["face", "plane"];
+export type FaceInsetPlacement = (typeof FACE_INSET_PLACEMENTS)[number];
+export type FaceInsetProps = {
+    /** Which part to cut (see `FACE_INSET_PARTS`). */
+    part: FaceInsetPart;
+    /**
+     * `"face"` (default): over the live face, at the part's own place (or `at`),
+     * `magnify` times bigger. `"plane"`: a plane in its parent's frame (on an
+     * object, beside the head, anywhere in the scene), `height` units tall.
+     */
+    placement?: FaceInsetPlacement;
+    /**
+     * `"face"` only: how much bigger than life, about the part's own middle.
+     * 1 = life size, below 1 shrinks it. Default 1.5.
+     */
+    magnify?: number;
+    /**
+     * `"plane"` only: the plane's height in local units; its width follows the
+     * part's shape (`faceInsetAspect`). Default 1.
+     */
+    height?: number;
+    /**
+     * `"face"` only: show it centred on another face point instead of its own
+     * place (`"face.forehead"`, `"face.chin"`, …). With `at`, `"eyes"` is one
+     * strip, both eyes together.
+     */
+    at?: Exclude<FaceTarget, "face.custom">;
+    /** Soft edge, 0 (hard) .. 1 (fades from the middle). Default 0.4. */
+    feather?: number;
+    /** How much around the part is cut, a multiple of its box (`FACE_INSET_BOXES`). Default 1. */
+    size?: number;
+    /** 0..1. Default 1. */
+    opacity?: number;
+    /** Which tracked face. Default: the enclosing `FaceTracker`'s, else 0. */
+    faceIndex?: number;
+    /** `"plane"` only: the texture's longer side, px. Default 256. */
+    resolution?: number;
+    /** Draw order. Default `FACE_INSET_RENDER_ORDER` (-1.5) on the face, 0 as a plane. */
+    renderOrder?: number;
+};
+/**
+ * Face inset (Lens Studio's Face Inset): a face part cut out of the live
+ * camera image with a soft edge, following the face every frame. Over the
+ * face it magnifies the part in place (big cartoon eyes, a giant mouth, a big
+ * or tiny face) or shows it on another face point (`at`); as a `"plane"` it
+ * is a card in the scene (on a product, beside the head). For your own
+ * material or a `ScreenImage`, use `useFaceInsetTexture`. Follows the
+ * enclosing `FaceTracker`'s face; needs a `FaceTracker` mounted (it starts no
+ * tracker). Inside a `<MadeUpCamera>` it cuts the part from the made-up
+ * camera, so the makeup shows in it.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <FaceInset part="eyes" magnify={1.8} />
+ *   <FaceInset part="mouth" at="face.forehead" magnify={0.8} />
+ * </FaceTracker>
+ * ```
+ */
+export declare const FaceInset: ({ part, placement, magnify, height, at, feather, size, opacity, faceIndex, resolution, renderOrder, }: FaceInsetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceInset/frame.d.ts

@@ -0,0 +1,94 @@
+import { FaceImageLandmark } from '../../face-character/faceReprojection';
+/**
+ * Face inset geometry (pure): where a face part is cut from the camera image.
+ * Each part has a box on the camera image, upright in the face's own frame
+ * (it turns with the head's roll), sized from the face (the 3D distance
+ * between the eyes, so it holds still while the mouth opens or the head
+ * turns), and a soft elliptical mask inside it.
+ */
+/** The face parts an inset can cut. */
+export declare const FACE_INSET_PARTS: readonly ["leftEye", "rightEye", "eyes", "mouth", "nose", "face"];
+export type FaceInsetPart = (typeof FACE_INSET_PARTS)[number];
+/**
+ * Each part's box, in eye distances (the 3D distance between the eye
+ * centres), before `size`. Measured on the canonical face: an eye is 0.4 wide,
+ * the mouth 0.76, the face 2.4 wide and 2.7 tall.
+ */
+export declare const FACE_INSET_BOXES: Readonly<Record<FaceInsetPart, {
+    width: number;
+    height: number;
+}>>;
+/** A part's box width over its height (pixels): the inset texture's shape. */
+export declare const faceInsetAspect: (part: FaceInsetPart) => number;
+/**
+ * An eye fades out as the head turns away from it (its far side smears over
+ * the nose): hidden when it is this narrow next to the other eye, fully shown
+ * from this wide.
+ */
+export declare const FACE_INSET_FAR_EYE: readonly [number, number];
+/** One mask ellipse in box space (−1..1 across the box, y down the face). */
+export type FaceInsetEllipse = {
+    x: number;
+    y: number;
+    rx: number;
+    ry: number;
+    alpha: number;
+};
+export type FaceInsetFrame = {
+    /** The box's centre on the camera image (0..1, top-left origin, y down). */
+    center: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Half the box along the face's x (to the image right on an upright face)
+     * and y (down the face), as offsets on the camera image (0..1 per axis).
+     */
+    axisX: {
+        x: number;
+        y: number;
+    };
+    axisY: {
+        x: number;
+        y: number;
+    };
+    /** The face's scale: the 3D distance between the eye centres, in image heights. */
+    unit: number;
+    /** The mask: one ellipse, or two for `"eyes"` (`count`). `alpha` fades an eye turning away. */
+    ellipses: [FaceInsetEllipse, FaceInsetEllipse];
+    count: 1 | 2;
+};
+export declare const createFaceInsetFrame: () => FaceInsetFrame;
+/** How much of an eye shows, 0..1, from its width next to the wider eye. */
+export declare const faceInsetEyeVisibility: (width: number, widest: number) => number;
+export type FaceInsetFrameOptions = {
+    /** How much around the part is cut: a multiple of its box (`FACE_INSET_BOXES`). Default 1. */
+    size?: number;
+    /**
+     * The feed is mirrored (the front webcam; `useXRMirrored()`, or the face's
+     * `mirrored`). `"leftEye"` / `"rightEye"` are the person's own eyes, so they
+     * read the other mesh eye on a mirrored feed. Default `false`.
+     */
+    mirrored?: boolean;
+};
+/**
+ * One frame of a part's inset: writes its box on the camera image and its
+ * mask into `out`. `landmarks` are the tracker's for one face (≥ 468, the
+ * camera image's own space, as `FaceInfo.landmarks`); `aspect` is the camera
+ * image's width / height. The box stays upright on the face whichever way the
+ * mesh labels its sides (a mirrored webcam included); `"leftEye"` is the
+ * person's own left eye when `mirrored` says how the feed is drawn. Returns
+ * `false` (and leaves `out`) without a usable face.
+ */
+export declare const writeFaceInsetFrame: (landmarks: ArrayLike<FaceImageLandmark> | null | undefined, personPart: FaceInsetPart, aspect: number, { size, mirrored }: FaceInsetFrameOptions, out: FaceInsetFrame) => boolean;
+/**
+ * Where a box point lands on the image: `(qx, qy)` in box space (−1..1, y
+ * down the face) → camera image (0..1, y down). Mirrors the shader.
+ */
+export declare const faceInsetPoint: (frame: FaceInsetFrame, qx: number, qy: number, out?: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};

package/dist/components/FaceInset/index.d.ts

@@ -0,0 +1,6 @@
+export { FACE_INSET_PLACEMENTS, FACE_INSET_RENDER_ORDER, FaceInset } from './FaceInset';
+export type { FaceInsetPlacement, FaceInsetProps } from './FaceInset';
+export { FACE_INSET_HOLD_MS, useFaceInsetTexture } from './useFaceInsetTexture';
+export type { FaceInsetTextureOptions } from './useFaceInsetTexture';
+export { FACE_INSET_BOXES, FACE_INSET_PARTS, createFaceInsetFrame, faceInsetAspect, writeFaceInsetFrame, } from './frame';
+export type { FaceInsetEllipse, FaceInsetFrame, FaceInsetFrameOptions, FaceInsetPart, } from './frame';