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

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

@@ -0,0 +1,182 @@
+import { FaceInfo } from '../face-info';
+import { FaceBlendshapeName } from '../face-info/blendshapes';
+/** A face's blendshape scores (MediaPipe names, 0..1), as `FaceInfo.blendshapes`. */
+export type FaceBlendshapes = Readonly<Partial<Record<FaceBlendshapeName, number>>>;
+/**
+ * What an expression requires of the blendshapes; omitted fields are "any".
+ * `atLeast` / `atMost` are per-blendshape bounds (all must hold); `anyOf`
+ * passes when one of its rules does (e.g. a wink with either eye).
+ */
+export type FaceExpressionRule = {
+    atLeast?: Partial<Record<FaceBlendshapeName, number>>;
+    atMost?: Partial<Record<FaceBlendshapeName, number>>;
+    anyOf?: readonly FaceExpressionRule[];
+};
+/**
+ * Your own test of the face (any logic over the blendshapes; `face` is the
+ * full `FaceInfo` when a hook calls it).
+ */
+export type FaceExpressionMatch = (blendshapes: FaceBlendshapes, face?: FaceInfo) => boolean;
+/**
+ * How the hint face shows an expression: one morph target played 0 → 1, or a
+ * mix of several (`{ smile: 1, wink: 0.6 }`, each weight reached at the peak).
+ */
+export type FaceExpressionHintPose = {
+    target: string;
+} | {
+    targets: Record<string, number>;
+};
+/**
+ * An expression: its default copy, how it is detected (`rule`, or `match`
+ * for logic a rule cannot express; with both, both must pass) and how the
+ * hint face shows it. Make your own with `defineFaceExpression`.
+ */
+export type FaceExpressionDefinition = {
+    /** Default instruction copy. */
+    label: string;
+    rule?: FaceExpressionRule;
+    match?: FaceExpressionMatch;
+    /** The hint face's morph target(s) that show it (`face-v1.glb` ships one per expression). */
+    hint: FaceExpressionHintPose;
+};
+/**
+ * Anything that names an expression to detect: a built-in name, a rule, a
+ * match function or a full definition.
+ */
+export type FaceExpressionSpec = FaceExpressionName | FaceExpressionRule | FaceExpressionMatch | FaceExpressionDefinition;
+/**
+ * Checks and returns your own expression definition (it needs a `rule` or a
+ * `match`). Pass it anywhere an expression name goes.
+ *
+ * ```ts
+ * const yawn = defineFaceExpression({
+ *   label: "Big yawn",
+ *   rule: { atLeast: { jawOpen: 0.7 } },
+ *   hint: { target: "surprised" },
+ * });
+ * ```
+ */
+export declare const defineFaceExpression: <T extends FaceExpressionDefinition>(definition: T) => T;
+/**
+ * The face instruction vocabulary. Rules read MediaPipe's face blendshapes;
+ * thresholds follow the SDK's face gestures (mouth open 0.5, smile 0.4, blink
+ * 0.55, brow raise 0.45). A wink accepts either eye, with the other one open.
+ */
+export declare const FACE_EXPRESSIONS: {
+    readonly smile: {
+        readonly label: "Give a big smile";
+        readonly rule: {
+            readonly atLeast: {
+                readonly mouthSmileLeft: 0.45;
+                readonly mouthSmileRight: 0.45;
+            };
+        };
+        readonly hint: {
+            readonly target: "smile";
+        };
+    };
+    readonly wink: {
+        readonly label: "Wink at the camera";
+        readonly rule: {
+            readonly anyOf: readonly [{
+                readonly atLeast: {
+                    readonly eyeBlinkLeft: 0.55;
+                };
+                readonly atMost: {
+                    readonly eyeBlinkRight: 0.3;
+                };
+            }, {
+                readonly atLeast: {
+                    readonly eyeBlinkRight: 0.55;
+                };
+                readonly atMost: {
+                    readonly eyeBlinkLeft: 0.3;
+                };
+            }];
+        };
+        readonly hint: {
+            readonly target: "wink";
+        };
+    };
+    readonly surprised: {
+        readonly label: "Look surprised";
+        readonly rule: {
+            readonly atLeast: {
+                readonly jawOpen: 0.35;
+                readonly browInnerUp: 0.4;
+            };
+        };
+        readonly hint: {
+            readonly target: "surprised";
+        };
+    };
+    readonly kiss: {
+        readonly label: "Blow a kiss";
+        readonly rule: {
+            readonly atLeast: {
+                readonly mouthPucker: 0.5;
+            };
+            readonly atMost: {
+                readonly jawOpen: 0.3;
+            };
+        };
+        readonly hint: {
+            readonly target: "kiss";
+        };
+    };
+    readonly puffCheeks: {
+        readonly label: "Puff your cheeks";
+        readonly rule: {
+            readonly atLeast: {
+                readonly cheekPuff: 0.3;
+            };
+        };
+        readonly hint: {
+            readonly target: "puffCheeks";
+        };
+    };
+    readonly frown: {
+        readonly label: "Frown";
+        readonly rule: {
+            readonly atLeast: {
+                readonly browDownLeft: 0.4;
+                readonly browDownRight: 0.4;
+            };
+        };
+        readonly hint: {
+            readonly target: "frown";
+        };
+    };
+    readonly scrunch: {
+        readonly label: "Scrunch your face";
+        readonly rule: {
+            readonly anyOf: readonly [{
+                readonly atLeast: {
+                    readonly noseSneerLeft: 0.3;
+                    readonly noseSneerRight: 0.3;
+                };
+            }, {
+                readonly atLeast: {
+                    readonly eyeSquintLeft: 0.45;
+                    readonly eyeSquintRight: 0.45;
+                    readonly browDownLeft: 0.3;
+                    readonly browDownRight: 0.3;
+                };
+            }];
+        };
+        readonly hint: {
+            readonly target: "scrunch";
+        };
+    };
+};
+export type FaceExpressionName = keyof typeof FACE_EXPRESSIONS;
+export declare const FACE_EXPRESSION_NAMES: FaceExpressionName[];
+/** The full definition a spec names (`undefined` for a bare rule or match function). */
+export declare const resolveFaceExpression: (expression: FaceExpressionSpec) => FaceExpressionDefinition | undefined;
+/**
+ * Whether blendshapes satisfy an expression: a name from `FACE_EXPRESSIONS`, a
+ * rule, a match function or a definition. `face` is passed on to match functions.
+ */
+export declare const matchFaceExpression: (blendshapes: FaceBlendshapes, expression: FaceExpressionSpec, face?: FaceInfo) => boolean;
+/** Every named expression the blendshapes satisfy (several can: a scrunch is often also a frown). */
+export declare const matchingFaceExpressions: (blendshapes: FaceBlendshapes) => FaceExpressionName[];

package/dist/face-info/landmarks.d.ts

@@ -1,6 +1,13 @@
 import { NormalizedLandmark } from '@mediapipe/tasks-vision';
 import { FaceCustomAnchorPoint, FaceTarget } from '../types/tracking';
-/** MediaPipe canonical face-mesh indices. Left/right follow the person's perspective. */
+/**
+ * MediaPipe canonical face-mesh index of each single-landmark face target, as
+ * MediaPipe names the side (263 = its left eye): the person's own side on an
+ * unmirrored feed. On the mirrored webcam the person's side is the other
+ * entry — read `FACE_LANDMARK_INDICES[feedSidedName(target, mirrored)]`, or
+ * let `resolveFaceAnchorPoint` / `TrackingAnchor` pick it (GROUNDING "Left and
+ * right").
+ */
 export declare const FACE_LANDMARK_INDICES: {
     readonly "face.forehead": 10;
     readonly "face.noseTip": 1;
@@ -13,8 +20,15 @@ export declare const FACE_LANDMARK_INDICES: {
     readonly "face.leftEarlobe": 454;
     readonly "face.rightEarlobe": 234;
 };
-/** Resolves a semantic face target in normalized tracker-input coordinates. */
-export declare const resolveFaceAnchorPoint: (faceTarget: FaceTarget, landmarks: readonly NormalizedLandmark[], customAnchorPoint?: FaceCustomAnchorPoint, target?: NormalizedLandmark) => NormalizedLandmark | null;
+/**
+ * Resolves a semantic face target in normalized tracker-input coordinates.
+ * Left / right (`face.leftCheek`, `face.custom`'s −x) are the person's own
+ * side: pass `feedMirrored` (`useXRMirrored()`; the front webcam is mirrored)
+ * so the target is read from the mesh side the person's side has on this
+ * feed. Defaults to an unmirrored feed.
+ */
+export declare const resolveFaceAnchorPoint: (faceTarget: FaceTarget, landmarks: readonly NormalizedLandmark[], customAnchorPoint?: FaceCustomAnchorPoint, target?: NormalizedLandmark, feedMirrored?: boolean) => NormalizedLandmark | null;
+/** The outer eye corners (MediaPipe's sides; only their distance is read). */
 export declare const FACE_EYE_DISTANCE_LANDMARKS: {
     readonly left: 263;
     readonly right: 33;

package/dist/face-info/types.d.ts

@@ -9,22 +9,38 @@ export type FaceVector3 = Readonly<{
 export type FaceInfo = {
     /** Current result-array index. This is not a persistent identity. */
     readonly index: number;
-    /** MediaPipe landmarks in normalized tracker-input coordinates; top-left origin. */
+    /**
+     * MediaPipe landmarks in normalized tracker-input coordinates; top-left
+     * origin. Indices keep MediaPipe's sides (263 = MediaPipe's left eye): the
+     * person's own side on an unmirrored feed, the opposite on the mirrored
+     * webcam (see `mirrored`).
+     */
     readonly landmarks: readonly NormalizedLandmark[];
     /** Axis-aligned bounds in the same normalized tracker-input coordinates. */
     readonly bounds: Readonly<FaceBounds>;
     readonly pose: {
         /** Three.js world position from the existing face tracker. */
         readonly position: FaceVector3;
-        /** Radians: X pitch (+up), Y yaw (+left), Z roll. */
+        /**
+         * Radians: X pitch (+ = looking up), Y yaw (+ = turning to the person's
+         * own left), Z roll (+ = tilting toward the person's own left shoulder),
+         * on every feed.
+         */
         readonly rotation: FaceVector3;
         /** Smoothed uniform sizing heuristic used by the face occluder/tracker anchor. */
         readonly scale: FaceVector3;
     };
     /** Outer-eye distance in normalized tracker-input coordinates. */
     readonly eyeDistance: number;
-    /** MediaPipe blendshape category names mapped to scores in [0, 1]. */
+    /**
+     * MediaPipe blendshape category names mapped to scores in [0, 1], raw:
+     * `…Left` is MediaPipe's left (the person's own left on an unmirrored feed,
+     * their right on the mirrored webcam). Face actions (`eyeBlinkLeft` …) read
+     * the person's side for you.
+     */
     readonly blendshapes: Readonly<Partial<Record<FaceBlendshapeName, number>>>;
+    /** The face was read from a mirrored feed (the front webcam): MediaPipe's sides are the person's opposite sides. */
+    readonly mirrored: boolean;
 };
 export type FaceInfoTarget = {
     index: number;
@@ -49,4 +65,5 @@ export type FaceInfoTarget = {
     };
     eyeDistance: number;
     blendshapes: Record<string, number>;
+    mirrored: boolean;
 };

package/dist/gestures/definitions.d.ts

@@ -5,6 +5,15 @@ import { OscillationTracker } from './measures';
 export type GestureKind = "face" | "hand" | "body";
 /** What each tracker hands a definition per frame. */
 export type GestureInputOf<K extends GestureKind> = K extends "face" ? FaceInfo | null : ReadonlyArray<TrackerPoint> | undefined;
+/**
+ * The feed a frame came from. `mirrored`: the front webcam, where MediaPipe's
+ * left / right labels (pose 11 / 12 …, face mesh sides, `…Left` blendshapes)
+ * name the person's opposite side. A sided gesture reads the person's own
+ * side with it (`personSide(side, mirrored)`).
+ */
+export type GestureContext = {
+    mirrored: boolean;
+};
 /**
  * A gesture: which tracker it reads, how to turn one frame of that tracker
  * into a `{ value, confidence }` sample, and its default detector options.
@@ -17,8 +26,12 @@ export type GestureDefinition<K extends GestureKind = GestureKind, M = unknown>
     /** Overrides of `DEFAULT_GESTURE_DETECTOR_OPTIONS` for this gesture. */
     defaults?: Partial<GestureDetectorOptions>;
     createMemory?: () => M;
-    /** `null` when the tracker has no subject this frame. Confidence 1 unless the source knows better. */
-    measure: (input: GestureInputOf<K>, memory: M, nowMs: number) => GestureSample;
+    /**
+     * `null` when the tracker has no subject this frame. Confidence 1 unless
+     * the source knows better. `context` is the feed (`useGesture` passes it;
+     * missing = an unmirrored feed).
+     */
+    measure: (input: GestureInputOf<K>, memory: M, nowMs: number, context?: GestureContext) => GestureSample;
 };
 type OscillationMemory = {
     tracker: OscillationTracker;

package/dist/gestures/index.d.ts

@@ -1,7 +1,7 @@
 export { DEFAULT_GESTURE_DETECTOR_OPTIONS, createGestureDetectorState, gestureStatesEqual, resolveGestureDetectorOptions, snapshotGestureState, stepGestureDetector, } from './detector';
 export type { GestureDetectorOptions, GestureDetectorState, GestureEndReason, GesturePhase, GestureSample, GestureState, } from './detector';
 export { GESTURES, GESTURE_NAMES, defineGesture, resolveGestureDefinition } from './definitions';
-export type { AnyGestureDefinition, BuiltInGestureName, GestureDefinition, GestureInputOf, GestureKind, GestureRef, } from './definitions';
+export type { AnyGestureDefinition, BuiltInGestureName, GestureContext, GestureDefinition, GestureInputOf, GestureKind, GestureRef, } from './definitions';
 export { HAND_JOINTS, OscillationTracker, POSE_JOINTS, measureArmRaise, fingerExtensions, measureFingerPattern, measureGrab, measureHandHeight, measureOpenPalm, measurePinch, measureTPose, measureThumb, thumbDirection, thumbExtension, } from './measures';
 export type { FingerPattern } from './measures';
 export { DEFAULT_GESTURE_SETTINGS, GESTURE_SETTINGS_FIELDS, patchGestureSettings, resolveGestureSettings, } from './settings';

package/dist/gestures/measures.d.ts

@@ -54,7 +54,12 @@ export declare const measureGrab: (hand: ReadonlyArray<TrackerPoint> | undefined
 export declare const measureOpenPalm: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
 /** Hand height on screen: 0 at the bottom edge, 0.5 at the centre, 1 at the top (tracker Y up). */
 export declare const measureHandHeight: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
-/** MediaPipe pose landmarks used by the body measures (person's perspective). */
+/**
+ * MediaPipe pose landmarks used by the body measures, as MediaPipe labels
+ * them (11 = its left shoulder): the person's own side on an unmirrored feed,
+ * the opposite on the mirrored webcam. Sided measures take the feed's
+ * `mirrored` to read the person's own side.
+ */
 export declare const POSE_JOINTS: {
     readonly leftShoulder: 11;
     readonly rightShoulder: 12;
@@ -68,10 +73,13 @@ export declare const POSE_JOINTS: {
 /** Shoulder width in tracker units; the body's scale reference. */
 export declare const shoulderWidth: (pose: ReadonlyArray<TrackerPoint>) => number;
 /**
- * How far a wrist is raised above its shoulder, in shoulder widths: 0 at
- * shoulder level or below, 1 at one shoulder width above.
+ * How far the person's own `side` wrist is raised above its shoulder, in
+ * shoulder widths: 0 at shoulder level or below, 1 at one shoulder width
+ * above. `mirrored` is the feed's mirror state (the front webcam; default
+ * `false`): MediaPipe's labels name the person's opposite side there, so the
+ * other label is read (#298).
  */
-export declare const measureArmRaise: (pose: ReadonlyArray<TrackerPoint> | undefined, side: "left" | "right") => number;
+export declare const measureArmRaise: (pose: ReadonlyArray<TrackerPoint> | undefined, side: "left" | "right", mirrored?: boolean) => number;
 /**
  * T-pose: both wrists level with the shoulders and stretched outward by at
  * least a shoulder width. 1 when fully extended and level.
@@ -79,15 +87,20 @@ export declare const measureArmRaise: (pose: ReadonlyArray<TrackerPoint> | undef
 export declare const measureTPose: (pose: ReadonlyArray<TrackerPoint> | undefined) => number;
 /**
  * Counts direction reversals of a scalar over a sliding window: the engine
- * behind nod, head shake and wave. A reversal counts when the signal has
- * moved at least `minAmplitude` from the last turning point. `measure`
+ * behind nod, head shake and wave. It follows the running extreme in the
+ * current direction; a turning point counts once the signal has come back
+ * at least `minAmplitude` from it (so jitter below the amplitude never
+ * counts, and a small first half-swing does not stall the count). `push`
  * returns `min(1, reversals / requiredReversals)` within `windowMs`.
  */
 export declare class OscillationTracker {
     private readonly options;
     private reversals;
-    private lastExtremum;
-    private lastValue;
+    /** Running extreme in the current direction (max rising, min falling). */
+    private extreme;
+    /** Range seen before the first swing (direction still unknown). */
+    private low;
+    private high;
     private direction;
     constructor(options: {
         minAmplitude: number;

package/dist/getFaceInfo-B1otSDMX.cjs

@@ -0,0 +1 @@
+"use strict";const f=require("./landmarks-BlUqf5MZ.cjs"),d=(s,e={minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0})=>{if(s.length===0)return e.minX=0,e.minY=0,e.maxX=0,e.maxY=0,e.width=0,e.height=0,e.centerX=0,e.centerY=0,e;let n=1,t=1,i=0,c=0;for(let r=0;r<s.length;r++){const{x:a,y:h}=s[r];a<n&&(n=a),h<t&&(t=h),a>i&&(i=a),h>c&&(c=h)}const o=Math.max(0,i-n),m=Math.max(0,c-t);return e.minX=n,e.minY=t,e.maxX=i,e.maxY=c,e.width=o,e.height=m,e.centerX=n+o*.5,e.centerY=t+m*.5,e},u=.5,X=(s,e)=>{for(const n in e)delete e[n];if(s)for(const n of s)e[n.categoryName]=n.score;return e},E=(s,e)=>s.blendshapes[e]??0,Y=(s,e,n=u)=>E(s,e)>=n,F=s=>{const e=s[f.FACE_EYE_DISTANCE_LANDMARKS.left],n=s[f.FACE_EYE_DISTANCE_LANDMARKS.right];return!e||!n?0:Math.hypot(e.x-n.x,e.y-n.y)},x=()=>({index:0,landmarks:[],bounds:{minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0},pose:{position:{x:0,y:0,z:0},rotation:{x:0,y:0,z:0},scale:{x:0,y:0,z:0}},eyeDistance:0,blendshapes:{},mirrored:!0}),l=(s,e)=>{e.x=s.x,e.y=s.y,e.z=s.z},p=(s,e,n=0,t)=>{var m,r,a;const i=(m=e.faceLandmarks)==null?void 0:m[n],c=s.getFace(n);if(!i||!c)return null;const o=t??x();return o.index=n,o.landmarks=i,d(i,o.bounds),l(c.transform.position,o.pose.position),l(c.transform.rotation,o.pose.rotation),l(c.transform.scale,o.pose.scale),o.eyeDistance=F(i),X((a=(r=e.faceBlendshapes)==null?void 0:r[n])==null?void 0:a.categories,o.blendshapes),o.mirrored=c.mirrored!==!1,o},y=(s,e=0,n)=>{const t=s.getDetectionResults();return t?p(s,t,e,n):null};exports.DEFAULT_FACE_EXPRESSION_THRESHOLD=u;exports.computeLandmarkBounds=d;exports.createFaceInfoTarget=x;exports.getFaceBlendshape=E;exports.getFaceEyeDistance=F;exports.getFaceInfo=y;exports.getFaceInfoFromResults=p;exports.hasFaceExpression=Y;

package/dist/getFaceInfo-Cu4xDWiL.js

@@ -0,0 +1,62 @@
+import { F as f } from "./landmarks-bftdwq6Z.js";
+const x = (s, e = {
+  minX: 0,
+  minY: 0,
+  maxX: 0,
+  maxY: 0,
+  width: 0,
+  height: 0,
+  centerX: 0,
+  centerY: 0
+}) => {
+  if (s.length === 0)
+    return e.minX = 0, e.minY = 0, e.maxX = 0, e.maxY = 0, e.width = 0, e.height = 0, e.centerX = 0, e.centerY = 0, e;
+  let n = 1, t = 1, c = 0, i = 0;
+  for (let r = 0; r < s.length; r++) {
+    const { x: a, y: h } = s[r];
+    a < n && (n = a), h < t && (t = h), a > c && (c = a), h > i && (i = h);
+  }
+  const o = Math.max(0, c - n), m = Math.max(0, i - t);
+  return e.minX = n, e.minY = t, e.maxX = c, e.maxY = i, e.width = o, e.height = m, e.centerX = n + o * 0.5, e.centerY = t + m * 0.5, e;
+}, d = 0.5, p = (s, e) => {
+  for (const n in e) delete e[n];
+  if (s)
+    for (const n of s) e[n.categoryName] = n.score;
+  return e;
+}, u = (s, e) => s.blendshapes[e] ?? 0, E = (s, e, n = d) => u(s, e) >= n, X = (s) => {
+  const e = s[f.left], n = s[f.right];
+  return !e || !n ? 0 : Math.hypot(e.x - n.x, e.y - n.y);
+}, Y = () => ({
+  index: 0,
+  landmarks: [],
+  bounds: { minX: 0, minY: 0, maxX: 0, maxY: 0, width: 0, height: 0, centerX: 0, centerY: 0 },
+  pose: {
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0 },
+    scale: { x: 0, y: 0, z: 0 }
+  },
+  eyeDistance: 0,
+  blendshapes: {},
+  mirrored: !0
+}), l = (s, e) => {
+  e.x = s.x, e.y = s.y, e.z = s.z;
+}, y = (s, e, n = 0, t) => {
+  var m, r, a;
+  const c = (m = e.faceLandmarks) == null ? void 0 : m[n], i = s.getFace(n);
+  if (!c || !i) return null;
+  const o = t ?? Y();
+  return o.index = n, o.landmarks = c, x(c, o.bounds), l(i.transform.position, o.pose.position), l(i.transform.rotation, o.pose.rotation), l(i.transform.scale, o.pose.scale), o.eyeDistance = X(c), p((a = (r = e.faceBlendshapes) == null ? void 0 : r[n]) == null ? void 0 : a.categories, o.blendshapes), o.mirrored = i.mirrored !== !1, o;
+}, D = (s, e = 0, n) => {
+  const t = s.getDetectionResults();
+  return t ? y(s, t, e, n) : null;
+};
+export {
+  d as D,
+  Y as a,
+  D as b,
+  x as c,
+  u as d,
+  X as e,
+  y as g,
+  E as h
+};

package/dist/hand/armFit.d.ts

@@ -0,0 +1,46 @@
+import { FeedVec } from './armMask';
+import * as THREE from "three";
+/**
+ * Experimental (vincentt-xr/sdk#319): may change in a later alpha.
+ *
+ * Puts a wrist frame on the arm found in a mask, on screen: turns it about the
+ * camera ray through the wrist so its −Y (up the arm) runs along the arm,
+ * moves it across to the arm's middle, and scales its cross-section (X, Z) so
+ * the wrist's ellipse is as wide on screen as the arm. Depth and roll stay the
+ * hand's: one camera only sees the arm's outline.
+ */
+export type WristFitTarget = {
+    /** Unit, up the arm (toward the elbow), feed units (x right, y down). */
+    up: FeedVec;
+    /** Move across the arm this far, feed units (+ = clockwise side of `up`). */
+    shift: number;
+    /** The arm's width on screen, feed units; null: keep the size. */
+    width: number | null;
+    /** The wrist's half-width (X) and half-depth (Z) in the frame's own units. */
+    halfWidth: number;
+    halfDepth: number;
+    /** Clamp for the width scale: a gentle nudge. Default `[0.85, 1.2]`. */
+    scaleRange?: readonly [number, number];
+};
+/** World point → feed units (x right 0..aspect, y down 0..1). */
+export declare const worldToFeedUnits: (point: THREE.Vector3, camera: THREE.Camera, aspect: number, out?: FeedVec) => FeedVec;
+/** Signed angle from `a` to `b`, radians, positive clockwise on screen (y down). */
+export declare const screenAngle: (a: FeedVec, b: FeedVec) => number;
+/** The frame's −Y (up the arm) on screen, unit, feed units. */
+export declare const frameUpOnScreen: (frame: THREE.Matrix4, camera: THREE.Camera, aspect: number, out?: FeedVec) => FeedVec;
+/**
+ * How much of the frame's arm axis (Y) shows on screen, 0..1: 1 while it runs
+ * across the view, 0 when it points at (or away from) the camera. From its
+ * on-screen length against the longer of X and Z (across the arm).
+ */
+export declare const axisOnScreen: (frame: THREE.Matrix4, camera: THREE.Camera, aspect: number) => number;
+/** The frame's local ellipse (`halfWidth` × `halfDepth` in X / Z) across `up` on screen, feed units. */
+export declare const ellipseWidthOnScreen: (frame: THREE.Matrix4, halfWidth: number, halfDepth: number, up: FeedVec, camera: THREE.Camera, aspect: number) => number;
+/**
+ * The wrist frame (`frame`, world; origin on the wrist, +Y toward the
+ * fingers) fitted to `target`, blended in by `weight` (0..1). Writes the
+ * fitted frame into `out` (turned and moved: a rigid change) and returns the
+ * scale across the arm (X, Z) that fits its width, `1` without one: applied
+ * by what sits on the frame, so a bone never takes a shearing scale.
+ */
+export declare const fitWristFrame: (frame: THREE.Matrix4, camera: THREE.Camera, aspect: number, target: WristFitTarget, weight: number, out: THREE.Matrix4) => number;

package/dist/hand/armMask.d.ts

@@ -0,0 +1,178 @@
+import { HandPose } from './handPose';
+/**
+ * Experimental (vincentt-xr/sdk#319): may change in a later alpha.
+ *
+ * The forearm in a segmentation mask (the portrait mask's person, or the
+ * multiclass mask's bare skin), measured from the tracked wrist: which way the
+ * arm runs on screen and how wide it is. Wristwear uses it so a strap lines up
+ * with the real arm, not just the hand's axis, and fits its width.
+ *
+ * Units: "feed units", isotropic, x right and y down, 1 = the feed's height
+ * (x runs 0..aspect). Lengths along and across the arm are given in cm and
+ * converted with the hand's own scale (`unitsPerCm`), so they don't depend on
+ * how far the hand is.
+ */
+export type FeedVec = {
+    x: number;
+    y: number;
+};
+/** A mask to look for the arm in: `inside(i)` for the row-major pixel `i` (row 0 at the top). */
+export type ArmMaskSource = {
+    width: number;
+    height: number;
+    inside: (index: number) => boolean;
+};
+/** Where to look: from the hand. */
+export type ArmQuery = {
+    /** The wrist joint, feed units. */
+    wrist: FeedVec;
+    /** Unit, from the middle knuckle to the wrist: the hand's axis, pointing up the arm. */
+    toElbow: FeedVec;
+    /** Feed units per cm at the hand. */
+    unitsPerCm: number;
+    /** Feed width / height. */
+    aspect: number;
+};
+export type ArmMeasureOptions = {
+    /** Cross-sections up the arm from the wrist, cm. Default `[2, 4, 6, 8]`. */
+    along?: readonly number[];
+    /** Where the width is measured, cm up the arm. Default 1.5. */
+    widthAt?: number;
+    /**
+     * A cross-section wider than this isn't the arm (it runs into the body or a
+     * sleeve's surroundings), cm. Default 11.
+     */
+    maxWidth?: number;
+    /** Narrower than this isn't the arm (noise, a finger), cm. Default 2.5. */
+    minWidth?: number;
+    /**
+     * The arm may turn at most this far from the hand's axis, degrees: a wrist
+     * bends up to about 80–90° (a fist hanging from a level arm). Default 95.
+     */
+    maxTurn?: number;
+};
+export declare const ARM_MASK_DEFAULTS: Readonly<{
+    along: readonly number[];
+    widthAt: 1.5;
+    maxWidth: 11;
+    minWidth: 2.5;
+    maxTurn: 95;
+}>;
+/** One cross-section across the arm, for debugging: its edges, feed units. */
+export type ArmSection = {
+    a: FeedVec;
+    b: FeedVec;
+    ok: boolean;
+};
+export type ArmMeasure = {
+    /** Unit, up the arm (toward the elbow), feed units. */
+    direction: FeedVec;
+    /**
+     * Signed angle from the hand's axis (`toElbow`) to `direction`, radians;
+     * positive turns clockwise on screen. The arm's bend at the wrist, which
+     * changes slowly: apply it to the hand's current axis.
+     */
+    bend: number;
+    /**
+     * The arm's width across, cm: the narrowest closed cross-section from
+     * `widthAt` up the arm (the wrist is the narrowest part, and a cross-section
+     * by a bent wrist can clip the hand).
+     */
+    width: number;
+    /** The arm's middle at `widthAt`, feed units. */
+    center: FeedVec;
+    /** Cross-sections that found the arm, of those tried (0..1). */
+    confidence: number;
+    /** The last pass's cross-sections and the width one, for drawing. */
+    sections: ArmSection[];
+};
+/**
+ * The hand's wrist, axis and scale in feed units, from its pose (`image` in
+ * tracker space, `world` in cm). `null` when the hand points at the camera
+ * (its axis is too short on screen to trust).
+ */
+export declare const armQueryOf: (pose: Pick<HandPose, "image" | "world">, aspect: number) => ArmQuery | null;
+/**
+ * Measures the arm in `source` from the hand (`query`): cross-sections up the
+ * arm find its edges, a line through their middles (and the wrist) gives its
+ * direction, and a second pass across that direction refines it and the
+ * width. `null` when fewer than two cross-sections find a closed arm (it runs
+ * into the body or off the screen), or it turns implausibly far from the hand.
+ */
+export declare const measureArm: (source: ArmMaskSource, query: ArmQuery, options?: ArmMeasureOptions) => ArmMeasure | null;
+export type ArmFitSettings = {
+    /** Each new measure eases the fit this far, 0..1. Default 0.4. */
+    smoothing: number;
+    /** After the arm is lost, keep the last fit this long, ms. Default 400. */
+    holdMs: number;
+    /** Then ease back to the hand's own axis over about this long, ms. Default 300. */
+    fadeMs: number;
+    /**
+     * Measure a mask against the hand pose nearest its time, at most this far
+     * apart, ms; further apart (the hand moved on) it waits for the next mask.
+     * Default 70.
+     */
+    maxSkewMs: number;
+    /** The fit may move the strap at most this far across the arm, cm. Default 2. */
+    maxShift: number;
+};
+export declare const ARM_FIT_DEFAULTS: Readonly<ArmFitSettings>;
+/**
+ * Follows the arm across masks for one hand: each new mask is measured against
+ * the hand pose from the same moment (masks arrive later than hand poses), and
+ * the result is kept relative to the hand (a bend, a width, a sideways shift),
+ * so it stays right while the hand moves between masks. `weight` (0..1) says
+ * how much of it to apply: 1 once the arm is found, until a mask comes
+ * without it; then held for `holdMs` and faded to 0 over `fadeMs`.
+ */
+export declare class ArmTracker {
+    /** Radians, clockwise on screen, from the hand's axis to the arm's. */
+    bend: number;
+    /** The arm's width, cm (null until measured). */
+    width: number | null;
+    /** How far the arm's middle is from the hand's axis, across it, cm (+ = clockwise side). */
+    shift: number;
+    /** 0..1, how much of the fit applies (found, held or fading). */
+    weight: number;
+    /** 0..1, how sure the measures are (closed cross-sections, eased): blends the fit with the hand. */
+    confidence: number;
+    /** The last measure, for drawing. */
+    last: ArmMeasure | null;
+    settings: ArmFitSettings;
+    private history;
+    /** There is a fit (measured, not yet faded out). */
+    private found;
+    /** When a mask first came without the arm since the last fit. */
+    private lostAtMs;
+    constructor(settings?: Partial<ArmFitSettings>);
+    /**
+     * The hand's query at a detection (`HandPose.timestampMs`); `null` when the
+     * hand's axis can't be used (it points at the camera): `query` reads null
+     * then, and nothing steers by an old axis.
+     */
+    pushHand(timeMs: number, query: ArmQuery | null): void;
+    /** The newest hand query (the hand now), null while its axis is unusable. */
+    get query(): ArmQuery | null;
+    /**
+     * The hand hasn't moved over the kept history (within 0.5 cm and 3°): any
+     * of its poses matches a mask from within that time.
+     */
+    private still;
+    /**
+     * Measures a new mask (taken at `maskTimeMs`, or now when unknown) against
+     * the hand from the same moment (or the newest, while the hand is still).
+     * Returns the measure, or null when the arm wasn't found (that starts the
+     * hold, then the fade) or no hand pose matches the mask's time (nothing
+     * changes: wait for the next mask).
+     */
+    measure(mask: ArmMaskSource, maskTimeMs: number | undefined, options?: ArmMeasureOptions): ArmMeasure | null;
+    /**
+     * Advances the hold and fade (call every frame with `performance.now()`).
+     * A fit holds until a mask comes without the arm, then for `holdMs`, then
+     * fades over `fadeMs`; no new mask changes nothing.
+     */
+    step(nowMs: number): void;
+    private clear;
+    /** Forget everything (the hand was lost). */
+    reset(): void;
+}