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

package/docs/api/head-occluder.mdx

@@ -0,0 +1,563 @@
+---
+title: "Head Occluder"
+description: "Depth-only head mesh fitted to the tracked face so 3D accessories pass behind the head; the canonical centimetre frame for authoring accessories; earrings on both ear lobes."
+sidebarTitle: "Head Occluder"
+icon: "user-round"
+---
+
+A 3D accessory attached to the head has parts that pass behind the skull: the
+arms of glasses, the back of a halo, an earring at a turn. Without an occluder
+they draw over the camera image. `HeadOccluder` is a depth-only head mesh
+(`colorWrite: false`, `depthWrite: true`, `renderOrder: -1`) that writes depth
+where the head is, so anything behind it fails the depth test.
+
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { HeadAttachment, HeadBinding } from "@vincentt-xr/sdk/face-effects";
+
+<HeadBinding faceIndex={0}>
+  <HeadAttachment point="noseBridge">
+    {/* centimetres around the nose bridge, facing +Z (out of the face) */}
+    <Glasses />
+  </HeadAttachment>
+</HeadBinding>;
+```
+
+`HeadBinding` mounts a `FaceTracker` (with `scaleWithFace`) and the occluder;
+its `occluder` prop is `true` by default and accepts the options below.
+
+## The canonical frame
+
+The v3 head is authored in the MediaPipe canonical face frame: centimetres,
+`+X` toward the screen's right on a face looking at the camera (MediaPipe's
+left: the person's own right in the mirrored selfie view, their left on
+unmirrored sources; GROUNDING "Left and right"), `+Y` up, `+Z` out of the face
+toward the camera. Its first
+468 vertices are the canonical face landmarks in landmark order, with a skull,
+brow, neck and ears behind them. The source is
+`assets-src/head-occluder/head-occluder-v3.blend`; the published mesh is
+`https://cdn.vincentt.studio/assets/xr/3d-models/head-occluder-v3.glb`,
+integrity-hashed in the SDK.
+
+Every frame `solveCanonicalHeadPose` fits the mesh to the live face:
+
+| quantity                     | source                                                                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| scale, rotation, translation | the 3D similarity (Umeyama, `solveSimilarity`) that maps the canonical positions of 31 rigid landmarks onto the same landmarks in world space |
+| live x / y                   | the feed point unprojected onto the `z = 0` plane, where `FaceTracker` lives                                                                  |
+| live depth                   | MediaPipe's landmark `z` (normalized-x units, smaller = closer) × the feed's world width                                                      |
+| landmark set                 | `CANONICAL_RIGID_LANDMARKS`: nose bridge and tip, eye corners, cheeks, temples, forehead, upper face oval; no mouth, no lower jaw             |
+
+The pose is written as a local transform re-expressed in the parent tracker
+group's frame, so it does not inherit the group's scale heuristic or rotation;
+the group only supplies visibility. Typical residual is 0.3–0.5 cm RMS. The
+pose is EMA-smoothed (`smoothing`, default `0.5`; `1` = none) and snaps on
+reacquire. The mesh hides while the face is lost. `onFit(fit)` receives the
+`HeadPoseFit` (`worldUnitsPerCm`, `rms`, `quaternion`, `translation`) each
+fitted frame, for calibration readouts.
+
+Other reference points for authoring, centimetres (the named attachment
+points are in the next section):
+
+| point                       | position            |
+| --------------------------- | ------------------- |
+| landmark 4 (tracker origin) | `(0, -0.5, 7.6)`    |
+| hairline (10)               | `(0, 8.3, 4.5)`     |
+| cheeks (50 / 280)           | `(±4.8, -0.7, 3.5)` |
+| back of skull               | `z ≈ -12`           |
+
+## Attachment points — `HeadAttachment`
+
+Named places on the head, so an accessory never needs a raw landmark index.
+`leftEar` / `rightEar` / `leftEarLobe` / `rightEarLobe` are the person's OWN
+ears on every feed. The table gives them as on an unmirrored feed (the
+person's left ear at canonical `+X`); on the mirrored webcam they swap, which
+`HeadAttachment` does from the session's mirror state (`mirrored` prop to
+override; `resolveHeadAttachmentPoint(point, mirrored)` for tools):
+
+| point          | cm (x, y, z), unmirrored | source                     | typical accessory      |
+| -------------- | ------------------------ | -------------------------- | ---------------------- |
+| `headCenter`   | `(0, 2.7, -2.2)`         | centre of the v3 skull     | helmets, halos         |
+| `crown`        | `(0, 13.26, -3.76)`      | top of the v3 skull        | hats, crowns           |
+| `forehead`     | `(0, 6.55, 5.03)`        | landmark 151               | headbands, bindis      |
+| `noseBridge`   | `(0, 2.47, 5.79)`        | landmark 6 (nose ridge)    | glasses, masks         |
+| `noseTip`      | `(0, -1.13, 7.48)`       | landmark 1                 | clown noses, piercings |
+| `chin`         | `(0, -9.4, 4.26)`        | landmark 152 (neutral jaw) | beards                 |
+| `leftEar`      | `(8.84, 1.37, -3.26)`    | centre of a v3 ear volume  | headphones, ear cuffs  |
+| `rightEar`     | `(-8.84, 1.37, -3.26)`   | centre of a v3 ear volume  | headphones, ear cuffs  |
+| `leftEarLobe`  | `(9.34, -0.73, -3.0)`    | v3 lobe piercing, 2 mm out | earrings (`Earrings`)  |
+| `rightEarLobe` | `(-9.34, -0.73, -3.0)`   | v3 lobe piercing, 2 mm out | earrings (`Earrings`)  |
+
+```tsx
+<HeadBinding faceIndex={1} numFaces={2}>
+  <HeadAttachment point="crown" offset={{ position: [0, -1.5, 0], rotation: [-0.25, 0, 0] }}>
+    <Hat />
+  </HeadAttachment>
+  {/* the person's right ear; +X is away from the head on either ear */}
+  <HeadAttachment point="rightEar" offset={{ position: [0.6, 0, 0] }}>
+    <HeadphoneCup />
+  </HeadAttachment>
+  {/* a pair of earrings: see Earrings below */}
+  <Earrings model={earring.scene} />
+</HeadBinding>
+```
+
+- Children are authored in centimetres around the point, in the head's axes,
+  facing `+Z`. Model a GLB with its origin at the attachment point (the nose
+  pad of a pair of glasses, the inner brim centre of a hat) and it needs no
+  offset.
+- `offset.position` (cm, relative to the point), `offset.rotation` (radians)
+  and `offset.scale` (multiplier) all apply about the point.
+- Ear points use the ear frame: children and `offset` are authored with `+X`
+  away from the head, and the ear on the screen's left (canonical `−X`) gets
+  them mirrored, so one accessory fits either ear on any feed.
+- `chin` is the neutral chin: the fit is rigid and ignores the jaw. Use
+  `TrackingAnchor target="face.chin"` for something that must open with the
+  mouth.
+- Inside a `CanonicalHeadFrame` several attachments share that frame's fit; on
+  its own each runs the canonical fit itself (cheap: a 31-point 3×3 solve).
+- `HEAD_ATTACHMENT_POINTS`, `HEAD_ATTACHMENT_POINT_NAMES`,
+  `getHeadAttachmentPoint(point, out?, mirrored?)` and
+  `resolveHeadAttachmentPoint(point, mirrored?)` (`{ position, mirror }`) expose
+  the table for tools.
+
+## Earrings — `Earrings`
+
+One earring, authored once in the ear frame, worn on both ear lobes; the one on the screen's left is
+its mirror image (scale `x = −1` about the head's mid-plane, so a piece turned out and forward on one
+ear is turned out and forward on the other too). `left` / `right` are the person's own ears on every
+feed. It clones the model per ear and runs one fit for both.
+
+```tsx
+import { Earrings, HeadBinding } from "@vincentt-xr/sdk/face-effects";
+
+const Pair = ({ left, right }: { left: boolean; right: boolean }) => {
+  const gltf = useLoader(GLTFLoader, earringUrl);
+  return (
+    <HeadBinding faceIndex={0}>
+      <Earrings model={gltf.scene.getObjectByName("silver_hoop")} left={left} right={right} />
+    </HeadBinding>
+  );
+};
+```
+
+| prop                                                             | meaning                                                                                                                                                                        |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model`                                                          | `Object3D` (a GLB's `scene` or one node), cloned per ear: shares geometry and materials, `frustumCulled = false`, `renderOrder` 5 (transparent meshes 6) unless a mesh has one |
+| `children`                                                       | JSX instead of / with `model`, mounted once per ear (build objects per mount, never one shared `<primitive>`); or `(side) => …` for a mismatched pair                          |
+| `left` / `right`                                                 | wear one on the person's own left / right ear; default `true`; both `false` renders nothing                                                                                    |
+| `offset`                                                         | `{ position, rotation, scale }` about the piercing (cm / radians / multiplier), in the ear frame, mirrored with the screen-left earring                                        |
+| `mirrored`                                                       | whether the feed is mirrored; default the session's (the front webcam is)                                                                                                      |
+| `swing`                                                          | swing on a spring about the piercing with head motion, then settle: `true` (gentle), `SpringSwingOptions`, or `false` (default, rigid); each ear swings on its own             |
+| `faceIndex`, `smoothing`, `enabled`, `onFit`, `onTrackingChange` | as on `HeadAttachment`; inside a `CanonicalHeadFrame` the frame's fit is reused                                                                                                |
+
+**The anchor.** The lobe point is the piercing as seen from outside: on the v3 occluder's ear
+volume at canonical `+X` (`HEAD_ATTACHMENT_POINTS.leftEarLobe`), 0.8 cm above its lowest point and
+0.26 cm ahead of its centre, moved 2 mm out of its surface (the `−X` lobe is its mirror). The 2 mm is the clearance the glasses keep from the occluder (coplanar surfaces z-fight
+with a depth-only mesh), so an earring authored outward from the origin is never cut on the near
+side.
+
+**Authoring an earring GLB.**
+
+- Canonical centimetres, object origin on the piercing, in the ear frame (as for the ear at
+  canonical `+X`): `+X` away from the head, `+Y` up (hang it along `−Y`), `+Z` out of the face. In Blender that is `(x, y, z)` =
+  canonical `(x, −z, y)` with a `+Y Up` glTF export.
+- Keep visible parts at `x ≥ 0` beside the lobe; 0.8 cm below the piercing the ear volume ends and
+  the earring hangs free. Anything inside the ear volume is hidden: wanted for a hoop's wire behind
+  the lobe, a cut earring otherwise. Measure against the v3 occluder (the source `.blend` keeps it
+  as a reference with the piercing at the origin).
+- Turn a flat piece 25–40° toward `+Z`: the front camera sees an ear almost edge-on.
+- Metals need an environment to reflect: set `scene.environment` (e.g. `RoomEnvironment` through
+  `PMREMGenerator`, no network). Without it a metallic GLB renders nearly black.
+- Model a dangling part as a child node whose origin is its hinge (the example drop's pendant and
+  heart's charm), so a later swinging dangle can hang from the same lobe anchor.
+
+**Example sets** (`/head-occluder?earrings=1`, built from nothing by
+`assets-src/accessories/build_earrings.py`, with a README):
+
+| GLB                         | nodes (origin on the piercing)                                   | size    |
+| --------------------------- | ---------------------------------------------------------------- | ------- |
+| `earrings-realistic-v1.glb` | `gold_stud`, `silver_hoop`, `rose_drop` (+ `rose_drop_pendant`)  | ~89 KB  |
+| `earrings-playful-v1.glb`   | `star_stud`, `heart_drop` (+ `heart_drop_charm`), `rainbow_hoop` | ~153 KB |
+
+The playful set ships plain `toon_*` PBR materials plus an inverted-hull outline (single-sided
+`toon_outline`); the example swaps the `toon_*` colours for `MeshToonMaterial` with a 3-step ramp.
+
+**Limitations.**
+
+- With `swing`, the whole earring swings about the piercing; a drop's pendant does not swing on
+  its own hook.
+- Hair is not an occluder: hair falling over the ears draws behind the earrings.
+- The occluder's ear is a thick average ear, so a hoop's hidden stretch behind the lobe is longer
+  than on a real one, and the piercing can sit a few millimetres off a real lobe; nudge with
+  `offset.position`.
+
+## Face index and tracking contract
+
+- `faceIndex` on `HeadAttachment`, `CanonicalHeadFrame` and `HeadOccluder`
+  defaults to the enclosing `FaceTracker` / `HeadBinding`. Set it only to read
+  a different face than the group you are in.
+- The fits read the parent tracker's model and never acquire it, so the
+  tracker's `numFaces` always decides how many faces are detected.
+  They therefore need an enclosing `FaceTracker` / `HeadBinding`; on a bare
+  group `useCanonicalHeadFit` finds no model and keeps the object hidden.
+- **Lost:** the fitted object hides the same frame; nothing is left frozen.
+- **Found / reacquired:** it snaps to the new pose; no easing in from the old
+  place.
+- **Face swap:** a jump of more than `LANDMARK_POSE_FIT_SNAP_CM` (20 cm) in one
+  frame — another person took the index — snaps instead of sliding across.
+- `onTrackingChange(tracked)` fires once on found and once on lost, never per
+  frame. The state machine is the pure `stepLandmarkPoseSmoothing`; its optional
+  `snapDistance` is in the fit's source units (default 20 for these centimetre fits).
+- MediaPipe result indices are not identities: with several people, index 1 can
+  move to someone else when a face enters or leaves. See
+  [Multi-subject](/api/multi-subject) for sticky selection.
+
+## `CanonicalHeadFrame`
+
+The same fit applied to a plain group. Children authored in canonical
+centimetres land exactly where the occluder expects them, so a modeller can
+measure an accessory against the `.blend` and ship it without per-scene tuning.
+
+```tsx
+<CanonicalHeadFrame faceIndex={0} offset={{ position: [0, 0.5, 0] }} smoothing={0.35}>
+  <primitive object={glasses.scene} />
+</CanonicalHeadFrame>
+```
+
+Props: `faceIndex` (default: the parent tracker's), `offset`, `smoothing`,
+`enabled`, `onFit`, `onTrackingChange`.
+`useCanonicalHeadFit(ref, options)` is the hook behind it, for driving an
+existing `Object3D`.
+
+## Options
+
+`HeadOccluder` props, also accepted by `HeadBinding`'s `occluder` object:
+
+- `fit`: `"canonical"` (default, v3 head) or `"manual"` (legacy v2 shell).
+- `faceIndex`: which tracked face feeds the fit; defaults to the parent tracker's.
+- `offset`: `{ position?: [x, y, z], rotation?: [rx, ry, rz], scale?: k }` on
+  top of the canonical fit. Position in canonical centimetres (rotates with the
+  head), rotation in radians after the head rotation, scale as a multiplier.
+- `smoothing`: EMA factor for the fitted pose.
+- `onFit`: per-frame `HeadPoseFit` callback (readouts; no React state at frame rate).
+- `url`: a different mesh. The canonical fit expects a v3-frame mesh.
+- `showDebugMaterial` / `opacity`: draw the occluder visibly for calibration.
+  Never ship it on.
+- Manual fit only: `position` (default `[0, 0, -10]`), `rotation`, `scale`
+  (default `[0.5, 0.5, 0.5]`), applied verbatim inside the tracker group.
+
+## Render contract
+
+- Accessory materials keep `depthTest` on (the default). A transparent
+  material still depth-tests against the occluder.
+- The occluder lives inside the same `FaceTracker` and face index as the
+  accessory; `HeadBinding` guarantees this.
+- `frustumCulled` is off on the occluder because its bounds move every frame.
+- The occluder is `DoubleSide`: the face region is an open shell, the skull is
+  closed, and the two overlap on purpose.
+
+## Shoulder occluder
+
+`ShoulderOccluder` (from `@vincentt-xr/sdk/tracking`, under a `BodyTracker`)
+is the same idea for the shoulders and upper torso: a depth-only mesh in a
+canonical **torso** frame — centimetres, origin at the midpoint of the shoulder
+joints, `+X` screen right in the selfie view, `+Y` up, `+Z` toward the camera;
+shoulders at `x = ±18` — fitted every frame from pose landmarks 11 / 12 only
+(`solveShoulderPose`): scale from their distance, roll from the line between
+them, yaw from their depth difference, no pitch. Nothing below the shoulders is
+read: this is a selfie-mode occluder, and hips predicted out of frame inflated
+the torso at close range. `CanonicalTorsoFrame` places accessories authored in
+torso centimetres (a necklace at `[0, -2, 2]`, a strap, wings behind the
+shoulder blades). Mount it beside `HeadBinding` for a full head-and-shoulders
+occluder; the two neck stubs overlap on purpose.
+
+```tsx
+<BodyTracker bodyIndex={0}>
+  <ShoulderOccluder offset={{ scale: 1.05 }} />
+  <CanonicalTorsoFrame>{/* torso cm */}</CanonicalTorsoFrame>
+</BodyTracker>
+```
+
+Props: `bodyIndex`, `offset`, `smoothing`, `url`, `showDebugMaterial`,
+`opacity`, `onFit`. Asset: `/assets/xr/3d-models/shoulder-occluder-v1.glb`
+(integrity-hashed; published with the same release as the v3 head).
+
+## Neck and shoulders — `neck`
+
+The head occluder stops at the neck. `neck` adds a depth-only bust (neck and shoulders) so what
+passes behind the neck and shoulders hides too: a necklace's back, a collar, hair down the back.
+
+```tsx
+<HeadBinding occluder={{ neck: "bust" }}>{/* accessories */}</HeadBinding>
+```
+
+| option         | default  | meaning                                                                                        |
+| -------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `type`         | `"bust"` | the mesh (`NECK_OCCLUDER_TYPES`)                                                               |
+| `follow`       | `"head"` | `"head"`: moved by the head fit, no body tracking; `"torso"`: by the torso fit (body tracking) |
+| `shoulderTurn` | 0.25     | with `"head"`: how much of the head's turn the shoulders take                                  |
+| `url`          | the CDN  | the mesh                                                                                       |
+| `offset`       | none     | a nudge, head cm (`"head"`) or torso cm (`"torso"`)                                            |
+| `bodyIndex`    | 0        | with `"torso"`: the body                                                                       |
+
+**Moved by the head.** The bust hangs from the head: the top of its neck follows the head, and its
+two lower neck bones each bend half of what keeps the shoulders level and facing the camera
+(`neckBoneTwist`). Nothing but the face tracker runs. The shoulders are where an average neck puts
+them, so nudge with `offset` for a long or short neck.
+
+**Moved by the torso.** The bust sits on the canonical torso fit (`NECK_BUST_TORSO_POSITION`), like
+`ShoulderOccluder`: the shoulders follow the real ones, at the cost of body tracking.
+
+**Credit.** The bust is from ["Complete 3D Reference - Spark AR"](https://sketchfab.com/3d-models/complete-3d-reference-spark-ar-9ecb7f5a38d7497b99ed114ffc0c519a)
+by [jepharaujo](https://sketchfab.com/jepharaujo), [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/),
+moved into the canonical head frame (`assets-src/head-occluder/README.md`). Until
+`neck-occluder-bust-v1.glb` is on the CDN, pass `url` (the example bundles it).
+
+## Swinging — `SpringSwing`
+
+Children of `<SpringSwing>` swing about its origin as whatever it sits in moves and turns, then
+settle (spring bones, from `@vincentt-xr/sdk/face-effects`). They hang along the parent's own
+down, so a head tilt tilts them; only motion swings them. `Earrings swing` and `Necklace` use it.
+
+```tsx
+<HeadAttachment point="leftEarLobe">
+  <SpringSwing frequency={1.8} damping={0.25} maxAngle={50} length={1.5}>
+    <MyCharm />
+  </SpringSwing>
+</HeadAttachment>
+```
+
+| prop        | default | meaning                                                  |
+| ----------- | ------- | -------------------------------------------------------- |
+| `frequency` | 1.8     | swings per second when let go                            |
+| `damping`   | 0.25    | 0..1: how fast a swing dies down (1: no overshoot)       |
+| `maxAngle`  | 50      | largest swing from rest, degrees                         |
+| `length`    | 1.5     | how far below the pivot the weight sits (parent's units) |
+| `enabled`   | true    | false: hangs still                                       |
+
+It steps in the scene's before-render hook, so it swings from the pose it is drawn at, at any frame
+rate; it rests while hidden. The solver (`SpringJoint`, `SpringChain`) and `SpringSwingDriver` are
+there for your own rigs.
+
+## Necklaces — `Necklace`
+
+A necklace on a tracked body: the chain sits on the neck base and upper chest (the canonical torso
+fit), its pendants swing about their bail, and a shoulder occluder hides the chain behind the neck.
+Inside a `BodyTracker` it uses that body; anywhere else it tracks the body itself.
+
+```tsx
+import { Necklace } from "@vincentt-xr/sdk/face-effects";
+
+const Worn = () => {
+  const gltf = useLoader(GLTFLoader, necklaceUrl);
+  return <Necklace model={gltf.scene.getObjectByName("gold_heart")} />;
+};
+```
+
+| prop                  | default                | meaning                                                           |
+| --------------------- | ---------------------- | ----------------------------------------------------------------- |
+| `model`               | none                   | the necklace in torso centimetres (cloned)                        |
+| `swing`               | `true`                 | pendants swing: `true` (gentle, at most 35°), options, or `false` |
+| `swingNodes`          | `["pendant", "charm"]` | name parts of the nodes that swing                                |
+| `occluder`            | `true`                 | mount a `ShoulderOccluder`                                        |
+| `occluderUrl`         | the SDK CDN copy       | the occluder's mesh                                               |
+| `bodyIndex`, `offset` | `0`, none              | the body; a nudge in torso centimetres                            |
+
+**Authoring a necklace GLB.** The torso frame: centimetres, origin between the shoulder joints,
+`+X` screen right, `+Y` up, `+Z` toward the camera (Blender `(x, y, z)` = `(x, −z, y)` with a `+Y Up`
+export). Lay the chain about 6 mm outside the v1 shoulder occluder (the live fit is coarse: closer
+chains vanish into it beside the neck). A pendant is a child node named `…_pendant` (or `…_charm`)
+with its origin on its bail.
+
+**Example set** (`/head-occluder?necklace=gold_heart`, built from nothing by
+`assets-src/accessories/build_necklaces.py`): `necklaces-v1.glb` with `gold_heart` (+
+`gold_heart_pendant`), `silver_drop` (+ `silver_drop_pendant`) and `pearl_strand`, ~390 KB.
+
+**Limitations.** The chain is rigid (only pendants swing); hair over the shoulders draws behind it;
+the torso fit reads only the shoulders, so a necklace sits where an average neck and chest would be.
+
+## Recipe: a real 3D accessory (glasses, #171)
+
+`/head-occluder?glasses=1` attaches a real glasses GLB with the public API only:
+
+```tsx
+import { HeadAttachment, HeadBinding } from "@vincentt-xr/sdk/face-effects";
+
+const Glasses = () => {
+  const gltf = useLoader(GLTFLoader, glassesUrl);
+  const glasses = useMemo(() => {
+    const clone = gltf.scene.clone(true); // one Object3D per face
+    clone.traverse((child) => {
+      if (!(child instanceof THREE.Mesh)) return;
+      child.frustumCulled = false;
+      // One material or an array (multi-material mesh): handle each.
+      const materials = Array.isArray(child.material) ? child.material : [child.material];
+      let transparent = false;
+      for (const material of materials) {
+        if (!material.transparent) continue;
+        material.depthWrite = false; // lenses
+        transparent = true;
+      }
+      child.renderOrder = transparent ? 6 : 5; // lenses after the frame
+    });
+    return clone;
+  }, [gltf]);
+  return <primitive object={glasses} />;
+};
+
+<HeadBinding faceIndex={0}>
+  <HeadAttachment point="noseBridge" onTrackingChange={(tracked) => setTracked(tracked)}>
+    <Suspense fallback={null}>
+      <Glasses />
+    </Suspense>
+  </HeadAttachment>
+</HeadBinding>;
+```
+
+**Authoring the GLB** (source: `assets-src/accessories/glasses-v1.blend`, with a README):
+
+- Model in canonical centimetres with the object origin ON the attachment point — for glasses the
+  nose bridge (landmark 6). Then no runtime offset is needed.
+- Face the accessory out of the face: canonical `+Z`, which is Blender's front (`−Y`) with a
+  `+Y Up` glTF export (Blender `(x, y, z)` = canonical `(x, −z, y)`).
+- Fit it against the v3 occluder (the `.blend` keeps it as a hidden reference): temples outside the
+  skull by ~2 mm and over the ears, lenses ~1.5 cm in front of the eyes.
+- Keep it light: the example glasses are 5.9 k triangles, ~210 KB.
+
+**Render order.** The occluder draws first (`renderOrder −1`, depth only). Opaque accessory parts
+come next with depth test and depth write on. Transparent parts (lenses) come last with
+`depthWrite: false`, so they tint what is behind them without hiding the frame or the eyes.
+
+**Common failures.**
+
+| symptom                                               | cause                                                        | fix                                                          |
+| ----------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| temples draw over the face and hair                   | no occluder, or it is under a different tracker / face index | keep the accessory and the occluder in one `HeadBinding`     |
+| temples never show, even on a turned head             | they run inside the skull                                    | widen / splay them to clear the occluder by ~2 mm            |
+| flicker along the temples                             | the accessory is coplanar with the occluder (z-fighting)     | keep a 1–2 mm gap                                            |
+| lenses hide the frame or the eyes                     | transparent material writes depth                            | `depthWrite: false` and a later `renderOrder`                |
+| accessory sits beside the face on images / video      | the pre-#169 mirrored tracker origin                         | fixed; use `HeadAttachment` / `CanonicalHeadFrame`           |
+| one face loses its accessory after `numFaces` changes | the pre-#171 one-shot camera registration                    | fixed in `FaceTracker`                                       |
+| accessory wrong size for a face                       | average head                                                 | `offset.scale` (e.g. `0.95`–`1.05`), `offset.position` in cm |
+| only one earring shows                                | one `Object3D` mounted on both ears                          | `<Earrings model={…}>` clones per ear                        |
+| the near earring is cut beside the lobe               | it reaches into the ear volume                               | author it at `x ≥ 0` from the lobe piercing                  |
+| metal earrings look black                             | no environment map                                           | set `scene.environment`                                      |
+
+The example's panel switches the occluder off (to show the failure), shows it with the debug
+material, toggles two faces, nudges `offset` lift / depth / scale and `smoothing`, and logs
+`onTrackingChange` per face.
+
+## Audit (#169) — behaviour, defaults, limitations
+
+**Fixed in the tracker group (`FaceTracker`).** Two defects made anything
+attached directly to the group (not through the canonical fit) land wrong:
+
+1. _Rotation._ The group applied `face.transform.rotation` — a sign-convention
+   reading (looking up/left positive) — as a three.js Euler. That is close to
+   the inverse of the head pose: a frontal face read about 8–16° of pitch the
+   wrong way, and a 40° head turn put the group about 85° off. The group now
+   applies MediaPipe's facial-transformation pose directly
+   (`face.transform.quaternion`). Measured against the canonical fit on still
+   images (frontal and 40° turns, webcam and image sources): within 1.6–2.5°.
+2. _Origin on unmirrored sources._ The face model flipped landmark x for
+   images, videos and the rear camera — a leftover from when the session drew
+   every source mirrored. The session now draws those straight and the model
+   analyzes the displayed frame, so the flip put the group at the mirrored
+   position (e.g. x = 0.23 instead of 0.77). Landmarks are now used as-is for
+   every source kind.
+
+**Fixed in the fits.** `HeadOccluder`'s canonical fit (on by default in
+`HeadBinding`) acquired the face model from a child effect, which runs before
+the parent tracker's, so the shared model was initialized with `numFaces: 1`
+and a multi-face `HeadBinding` tracked one face. The fits now only read the
+parent's model.
+
+**Production defaults.** `HeadBinding`: `numFaces` 4, `scaleWithFace` on,
+occluder on with `fit: "canonical"`, `smoothing` 0.5. Occluder: depth-only,
+`DoubleSide`, `renderOrder` −1, `frustumCulled` off, integrity-checked GLB that
+fails closed. Accessories: `depthTest` on, authored in canonical centimetres
+through `HeadAttachment` / `CanonicalHeadFrame`.
+
+**Known limitations.**
+
+- The fit is rigid: jaw opening, smiles and cheeks are not followed by the
+  occluder or by `chin`.
+- Weak perspective: live depth comes from MediaPipe's relative landmark z, so
+  absolute distance is approximated by scale; a face near the frame edge of a
+  wide camera can read 1–3° of extra pitch / yaw.
+- The occluder is an average head. Big hair volumes, hats worn in the camera
+  image and very long or short heads leave a few millimetres of mismatch; nudge
+  with `offset.scale` / `offset.position`.
+- Beyond about 70° of yaw MediaPipe's landmarks degrade and the fit wobbles.
+- Face indices are per result, not identities.
+
+## Manual visual test plan
+
+Open `/head-occluder` with a live camera. Accessories: a halo around the
+crown, glasses arms over the temples, a bridge across the eyes, two earrings.
+
+1. Frontal: the bridge is fully visible; the arms vanish past the temples; the
+   halo's back half is hidden.
+2. Yaw left and right to about 60°: the near arm appears along the temple, the
+   far arm stays hidden; the far earring hides behind the jaw; the head does not
+   shrink or grow.
+3. Pitch up and down: the halo's visible arc changes smoothly; no flicker along
+   the silhouette.
+4. Roll: the silhouette follows the tilt.
+5. Walk toward and away from the camera: the accessories keep their size
+   relative to the face.
+6. Cover the camera: everything hides; uncover: everything snaps back without
+   sliding.
+7. Toggle `show occluder`: the grey head sits on the face with the nose bridge
+   at the nose; toggle `fit: manual` to compare with the v2 shell.
+8. Mirror check: switch to a video source (unmirrored) and repeat 2; with the
+   face mesh on, the fit markers stay on their landmarks (no mirrored offset).
+9. Attachment points: turn on "attachment points + crown hat". Every dot sits
+   on its feature (forehead, nose bridge between the eyes, nose tip, chin,
+   both ears; the white head-centre dot drifts behind the face as you turn).
+   The hat's brim hides behind the skull at the back. Cover and uncover the
+   camera: the panel's `hat tracking` line logs one `lost` and one `found`.
+10. Multiple faces: two people in frame with `HeadBinding faceIndex={0}` and
+    `faceIndex={1}` each holding a `HeadAttachment` (no `faceIndex` on the
+    attachment): each person gets their own accessory; one leaving does not
+    make the other's slide.
+11. Glasses (`/head-occluder?glasses=1`, live camera): frontal — both lenses over the eyes, the bridge on
+    the nose, both temples hidden past the temples of the head. Turn left / right to ~60° — the
+    near temple runs back over the ear, the far one stays hidden, no flicker along either. Nod —
+    the lenses stay in front of the eyes. Tilt — the frame rolls with the head. Untick the
+    occluder — the far temple draws over the face (the failure case). Cover the camera — the
+    glasses vanish and the panel logs `lost`; uncover — they snap back (`found`), no slide-in.
+    Tick "two faces" with two people — each gets a pair; one leaving does not move the other's.
+    Repeat on the webcam (mirrored) and on a video preset (unmirrored).
+12. Shoulders: turn on the shoulder occluder and torso accessories. The
+    necklace's back half, the strap behind the shoulder and the wings' inner
+    halves hide; lean and turn the torso: they follow the shoulders, not the head.
+
+13. Earrings (`/head-occluder?earrings=1`, live camera): frontal — both earrings hang from the
+    lobes, the near sides whole. Turn left / right to ~60° — the far earring hides behind the head
+    and neck, the near one stays whole beside the ear (no flicker at the lobe). Nod and tilt — they
+    stay on the lobes. Switch style (realistic / playful) and each earring; the hoops' wire
+    disappears behind the lobe. Untick "left ear" — only the earring on your real left ear goes
+    (on the screen's left in the mirrored webcam view). Untick the head occluder — the far earring
+    draws over the face. Repeat on a video preset (unmirrored): "left ear" is now the person's
+    left ear, on the screen's right.
+
+14. Swinging earrings (`/head-occluder?earrings=1&realistic=rose_drop`): shake and nod — the
+    drops swing and settle within about a second; tilt — they tilt with the head. Untick "swing" —
+    rigid again.
+
+15. Necklaces (`/head-occluder?necklace=gold_heart`): the chain lies around the neck base onto the
+    chest, its back hidden behind the neck; the heart hangs from the front and swings as you turn.
+    Try silver drop and pearls; untick "pendant swings".
+
+16. Neck (`/head-occluder?neck=head&debug=1&shoulders=0`): the grey bust's shoulders sit on your
+    collarbones; turn and tilt your head — the neck bends, the shoulders stay level. `neck=torso`:
+    the shoulders follow your real ones.
+
+Examples: `/head-occluder`, `/head-occluder?glasses=1`, `/head-occluder?earrings=1`,
+`/head-occluder?necklace=gold_heart`. Related: [Face Binding Anchors](/api/face-binding-anchors)
+for 2D/3D landmark anchoring without occlusion.