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

package/docs/guides/lip-effect-textures.mdx

@@ -1,15 +1,16 @@
 ---
 title: "Lip Effect Textures"
-description: "How to author a design texture for LipEffect: the canvas contract, the lip UV template, orientation, mask modes, and the custom material context."
+description: "How to author a design texture for LipEffect: the canvas contract, the lip template, sides, shading and finishes, mask modes, and the custom material context."
 sidebarTitle: "Lip Effect Textures"
 icon: "palette"
 ---
 
 `LipEffect` (from `@vincentt-xr/sdk/face-effects`) paints a design texture onto
-the lips of a tracked face. The texture lives in the **canonical face UV
-atlas**, but only the lip triangles are ever sampled. Everything this page
-describes is derived from the canonical mesh's own `uv` attribute: the mesh is
-the design contract, not a hand-drawn diagram.
+the lips of a tracked face. The texture lives in the **face atlas**
+(`FACE_ATLAS_UVS`, the canonical face model's UV layout, bundled with the
+SDK), but only the lip triangles are ever sampled. Everything this page
+describes is drawn from that bundled atlas data: the data the effect samples
+is the design contract, not a hand-drawn diagram.
 
 ## The canvas contract
 
@@ -25,103 +26,126 @@ the design contract, not a hand-drawn diagram.
   multiplied by `color`; at `intensity={0}` the design colours show as painted.
   Paint white or light grey for a pure tint, or paint real colour and lower
   `intensity`.
+- **Paint in sRGB.** Images load without a colour space and the lip material
+  decodes their sRGB itself; a `THREE.Texture` you tag `SRGBColorSpace` is
+  decoded by the GPU instead. Cached textures are never re-tagged.
 - **Image top is `v = 1`.** Textures load with `flipY`, so the top row of the
-  image is the top of the UV atlas and the upper lip sits above the lower lip
-  in the image, as you would expect.
+  image is the top of the atlas and the upper lip sits above the lower lip in
+  the image, as you would expect.
 
-## The lip UV template
+## The lip template
 
-<img
-  src="/guides/lip-uv-template.svg"
-  alt="Lip UV template generated from the canonical face mesh"
-/>
+<img src="/guides/lip-uv-template.svg" alt="Lip template generated from the bundled face atlas" />
 
-The template is generated from `canonical_face_model.obj`:
+The template is the face atlas guide (`createFaceAtlasGuideSvg`) for the lips
+and the mouth:
 
-- **Solid pink ring** — the outer lip ring (MediaPipe `FACEMESH_LIPS` outer
-  contour). This is the painted edge.
-- **Dashed blue ring and blue fill** — the inner lip ring and the mouth
-  interior. In the default `outer-and-inner-lips` mask mode this area is cut
-  out, so teeth and tongue stay clean when the mouth opens.
+- **Pink outline and fill** — the lips (between MediaPipe's outer and inner
+  lip rings). The outer outline is the painted edge.
+- **Blue outline and fill** — the mouth interior. In the default
+  `outer-and-inner-lips` mask mode this area is cut out, so teeth and tongue
+  stay clean when the mouth opens.
 - **Grey wireframe** — the lip triangles that are actually sampled.
-- **Orientation labels** — image **left** is the subject's **right** lip corner.
+- **Side labels** — image **left** is the person's **right**, on every feed.
 
-Regenerate it after the canonical OBJ changes on the CDN; the script verifies
-the download against the hash pinned in `lib/utils/integrity.ts`:
+Regenerate it after the atlas data changes (`scripts/generate-face-atlas.ts`);
+it needs no download:
 
 ```bash
 pnpm dlx tsx scripts/generate-lip-uv-guide.ts --png
 ```
 
-### Mirrored camera behaviour
+### Sides on every feed
 
-The design is always mapped in the **subject's** frame: the left edge of the
-lip region is the subject's right lip corner, whatever is on screen.
+Paint the design as on an unmirrored photo of the person: **image-left is the
+person's right**. `LipEffect` keeps those sides on every feed (GROUNDING "Left
+and right"):
 
-- With the **webcam**, the session mirrors the feed once (selfie view), so the
-  subject's right appears on **screen right**. The left side of your design
-  therefore lands on the right side of the screen.
-- With **image or video sources**, nothing is mirrored, so the subject's right
-  (and the left side of your design) appears on **screen left**.
+- With **image, video or rear-camera sources** nothing is mirrored: the
+  design's left half lands on the person's right lip half, on the screen's left.
+- With the **webcam** the session mirrors the feed (selfie view). The lip
+  material reads the design at `(1 − u, v)` there, so the design's left half
+  still lands on the person's own **right** lip half (on the screen's right).
 
-Do not add a second mirror in CSS, canvas, or a shader; see "Camera, layout,
-mirror, and capture parity" in `GROUNDING.md`.
+The atlas is symmetric, so the flip is exact. Text therefore reads mirrored in
+the selfie view, as text on a real face would. Do not add a mirror of your own
+in CSS, canvas or a shader; see "Camera, layout, mirror, and capture parity"
+in `GROUNDING.md`.
 
 ### Generating the guide at runtime
 
-The same renderer is exported, so an editor or a debug panel can draw the guide
-from the live mesh:
+The same renderer is exported, so an editor or a debug panel can draw the
+guide; it needs no mesh:
 
 ```tsx
 import {
   createLipUvGuideDataUrl,
   createLipUvGuideSvg,
   getLipUvBounds,
-  useCanonicalFaceMesh,
 } from "@vincentt-xr/sdk/face-effects";
 
-const mesh = useCanonicalFaceMesh();
-const svg = mesh ? createLipUvGuideSvg(mesh, { size: 1024 }) : null;
-const zoomed = mesh ? createLipUvGuideDataUrl(mesh, { region: "lips" }) : null;
-const bounds = mesh ? getLipUvBounds(mesh) : null; // { minU, maxU, minV, maxV }
+const svg = createLipUvGuideSvg({ size: 1024 });
+const zoomed = createLipUvGuideDataUrl({ region: "lips" });
+const bounds = getLipUvBounds(); // { minU, maxU, minV, maxV, mouthV }
 ```
 
 Options: `size` (canvas pixels), `region` (`"canvas"` or `"lips"`),
 `wireframe`, `labels`, `background`. `lipUvToPixel(u, v, size)` converts a UV
-to image pixels with the `flipY` convention.
+to image pixels with the `flipY` convention. The alpha.8 calls with a parsed
+mesh first (`createLipUvGuideSvg(mesh, options)`) still work and draw the same
+guide.
 
-The example playground's `/lip-effect` page has a **Texture preview / UV
+The example playground's `/makeup` page has a **Texture preview / UV
 guide** toggle: it overlays the guide on the current design texture, shows a
 zoomed crop of the lip region, and paints the template itself onto the tracked
-lips so the labelled rings can be checked against a real mouth.
+lips so the labelled sides can be checked against a real mouth.
 
-## Presets and material controls
+## Presets, finishes and shading
 
 `LipEffect` takes flat, serializable settings (`LipEffectSettings`). Start from
 a preset and override what you need; explicit props always win over the preset:
 
 ```tsx
-<LipEffect preset="matte" color="#8b2635" designTexture="/lips/matte.png" />
+<LipEffect preset="matte" shade="brick" designTexture="/lips/matte.png" />
 ```
 
-| Preset     | Look                                                            |
-| ---------- | --------------------------------------------------------------- |
-| `lipstick` | Opaque colour with a soft highlight                             |
-| `gloss`    | Translucent colour with a strong, tight highlight               |
-| `matte`    | Opaque, no highlight, heavy skin shading                        |
-| `tint`     | Sheer wash of colour that keeps the natural lip                 |
-| `metallic` | Full-strength, tight gold-tinted highlight                      |
-| `gradient` | Ombre: strong colour at the mouth line fading at the outer edge |
-
-Controls: `color`, `opacity`, `intensity` (0 shows the design as painted, 1
-multiplies it by `color`), `shading` (how much the camera's own lip light and
-shadow show through), `gloss` and `roughness` (highlight amount and spread),
-`highlightColor`, and `gradientColor` with `gradientAmount`. Without a
-`designTexture` the lips are filled with `color`, so every preset works on its
-own.
+| Preset     | Finish   | Look                                                            |
+| ---------- | -------- | --------------------------------------------------------------- |
+| `lipstick` | satin    | Opaque colour with a soft sheen                                 |
+| `gloss`    | gloss    | Translucent colour with a strong, wet highlight                 |
+| `matte`    | matte    | Opaque, the lips' own shine removed                             |
+| `tint`     | matte    | Sheer wash of colour that keeps the natural lip                 |
+| `metallic` | metallic | A highlight tinted by the shade, gold-tinted extra highlight    |
+| `gradient` | satin    | Ombre: strong colour at the mouth line fading at the outer edge |
+| `shimmer`  | shimmer  | Fine flakes over a satin colour                                 |
+| `glitter`  | glitter  | Sparse, large flakes over a sheer colour                        |
+
+Pick a colour by name with `shade` (`MAKEUP_SHADES.lips`: `nude`, `rosewood`,
+`mauve`, `softPink`, `coral`, `peach`, `classicRed`, `brick`, `berry`, `plum`,
+`wine`, `chocolate`; or `"auto"` for the person's own lip colour, deepened,
+measured on the GPU). A `color` that differs from the shade wins. `finish`
+(`matte`, `satin`, `gloss`, `shimmer`, `metallic`, `glitter`) sets `shine` and
+the sparkle fields (`sparkleColor`, `sparkleDensity`, `sparkleSize`);
+`coverage` runs from sheer (0: filters the lips' own colour and never lightens
+them) to opaque (1: covers them); `enabled={false}` draws nothing.
+
+**Shading.** The paint is shaded by the makeup core against the person's own
+skin, light and lip colour (`useFaceSkin`), so the same shade looks the same on
+every skin tone and follows the room's light: the lips' own shadow and
+highlights, a lamp switched off, a warm or cool cast. `shading` sets how much
+of that light the paint follows: 1 (the default) fully, 0 flattens the opaque
+part (the shade as picked, with only the finish's own highlight). A sheer part
+(`coverage` below 1) still filters the live lips, so their own light and
+texture show through; set `coverage: 1` as well for a fully flat fill.
+
+Other controls: `opacity` (linear: 0.8 paints 80 %), `intensity` (0 shows the
+design as painted, 1 multiplies it by `color`), `gloss`, `roughness` and
+`highlightColor` (an extra lip highlight on top of the finish: amount, spread,
+colour), and `gradientColor` with `gradientAmount`. Without a `designTexture`
+the lips are filled with `color`, so every preset works on its own.
 
 The `LipEffectSettingsPanel` from `@vincentt-xr/sdk/debug-ui` edits all of these
-live, including the mask mode and the texture transform, and the `/lip-effect`
+live, including the mask mode and the texture transform, and the `/makeup`
 example page mounts it next to the design-texture picker.
 
 ## Procedural colour, edges, inner lip and split lips
@@ -130,7 +154,8 @@ example page mounts it next to the design-texture picker.
   `colorMode="solid"` to ignore one, and the lips are filled with `color`.
   Add `gradientColor` with `gradientAmount` and pick `gradientDirection`:
   `outward` runs from the mouth line to the outer edge, `vertical` and
-  `horizontal` span the lip box.
+  `horizontal` span the lip box (`horizontal` from the person's right corner
+  to their left).
 - **Edge softness.** `edgeSoftness` feathers the outer lip boundary as a
   fraction of the lip band (default `0.12`; `0` is a hard polygon edge). It
   uses the mesh's own band position, so it follows the tracked lip shape.
@@ -140,7 +165,7 @@ example page mounts it next to the design-texture picker.
 - **Separate lower lip.** Turn on `splitLips` to give the lower lip its own
   `lowerLipColor` and `lowerLipOpacity`, and pass `lowerDesignTexture` for a
   separate texture (it falls back to `designTexture`). The split happens at the
-  mouth line of the canonical UV atlas with a thin blend at the corners.
+  mouth line of the atlas with a thin blend at the corners.
 
 ## Texture transform
 
@@ -153,17 +178,17 @@ A design that does not line up can be fitted without repainting:
 | `textureRotation`                  | Degrees, counter-clockwise as seen on the face                                                |
 | `textureFlipX`, `textureFlipY`     | Mirror across the lip centre                                                                  |
 
-The transform is applied to the sampled UV, so the gradient and the mask are
-unaffected. `createLipTextureTransform(settings, bounds)` returns the same
-`Matrix3` the shader uses if a custom material wants it.
+The transform is applied to the sampled UV, in the design's own (person-side)
+frame, so the gradient and the mask are unaffected.
+`createLipTextureTransform(settings, bounds)` returns the same `Matrix3` the
+shader uses if a custom material wants it.
 
 ## Downloading the template
 
-The `/lip-effect` page has **Download SVG** and **Download PNG** buttons that
-export the guide at 2048 px straight from the loaded mesh. In code,
-`createLipUvGuideSvg(mesh, { size })` returns the SVG string and
-`createLipUvGuidePngBlob(mesh, { size })` resolves to a PNG `Blob` (browser
-only). The shipped copies are `docs/guides/lip-uv-template.svg` and
+The `/makeup` page has **Download SVG** and **Download PNG** buttons that
+export the guide at 2048 px. In code, `createLipUvGuideSvg({ size })` returns
+the SVG string and `createLipUvGuidePngBlob({ size })` resolves to a PNG `Blob`
+(browser only). The shipped copies are `docs/guides/lip-uv-template.svg` and
 `docs/guides/lip-uv-template.png`.
 
 ## Mask modes
@@ -173,10 +198,20 @@ only). The shipped copies are `docs/guides/lip-uv-template.svg` and
 ```
 
 - `outer-and-inner-lips` (default) — paint the lip surface only. The mouth
-  interior writes the shared stencil buffer and the lip material skips it.
+  interior sets the mouth stencil bit (`FACE_ATLAS_STENCIL.mouth`, 0x01) and
+  the lip material skips those pixels.
 - `outer-lips` — paint everything inside the outer ring, mouth interior
   included.
 
+## Draw order
+
+The lips draw in the opaque face layer at `MAKEUP_RENDER_ORDER.lips` (-1.64):
+after `FaceRetouch`, the face effects and the other makeup regions, before
+`FaceInset`, the head occluder and accessories. Hands (`HandCutout`) and
+glasses draw over the lips, and on a turned head the far half of the lips
+stops at the nose (the face's self-occlusion pass, on the high and medium
+quality tiers).
+
 ## Several faces and performance
 
 `LipEffects` renders one lip effect per face slot. Pass one config for every
@@ -192,18 +227,27 @@ face or a picker per face:
 />
 ```
 
-With a single config the faces share one built-in material. The material is a
-plain three.js object underneath: `useLipEffectMaterial(inputs)` returns one you
-can pass as `sharedMaterial` to any number of `LipEffect`s, or return from a
-`material` factory. `maxUpdateFps` caps how often the lip mesh follows the
-landmarks, and `<XRProvider perf={{ targetFps, camRes }}>` lowers the tracking
-rate and the analysed camera resolution for the whole session.
+With a single config the faces share one built-in material; each draw still
+reads its own face (fade, skin, light). The material is a plain three.js
+object underneath: `useLipEffectMaterial(inputs)` returns one you can pass as
+`sharedMaterial` to any number of `LipEffect`s, or return from a `material`
+factory. `LipEffect` needs no `FaceTracker`: it starts the face model itself
+(`numFaces`; `LipEffects` asks for `maxFaces`). A `FaceTracker` mounted beside
+it in the same commit starts the model first, with its own `numFaces` and
+`targetFps`; one that mounts later (under a later `Suspense`) does not, so
+give the lips the same `numFaces`. `holdMs` is the face's: every layer on it
+shares one hold, and the largest `holdMs` asked for wins (a `FaceRig` above
+keeps its own). The lips ride the face's
+shared surface, which every makeup layer on that face shares (one landmark
+update and one skin probe per face); `maxUpdateFps` and `predictMs` are
+deprecated and ignored. `<XRProvider perf={{ targetFps, camRes }}>` lowers the
+tracking rate and the analysed camera resolution for the whole session.
 
 ## Custom materials
 
 `material` accepts a React material node or a factory. The factory receives a
-stable context and is called once per lip geometry group (plus the mouth
-interior in `outer-lips` mode), only after the canonical mesh has loaded:
+stable context and is called for the lips (plus the mouth interior in
+`outer-lips` mode):
 
 ```ts
 type LipEffectMaterialContext = {
@@ -211,11 +255,15 @@ type LipEffectMaterialContext = {
   designTexture: THREE.Texture | null;
   faceUv: THREE.BufferAttribute;
   lipEdge: THREE.BufferAttribute;
+  restPosition: THREE.BufferAttribute;
   lowerDesignTexture: THREE.Texture | null;
   faceIndex: number;
   maskMode: LipMaskMode;
   lipUvBounds: LipUvBounds;
   settings: LipEffectSettings;
+  personLeftSign: 1 | -1;
+  skin: FaceSkinReference;
+  uniforms: FaceAtlasUniforms & FaceSkinUniforms;
 };
 ```
 
@@ -224,18 +272,32 @@ outer ring, `1` on the mouth line. It is bound as `attribute float lipEdge`
 and is what the built-in material uses for feathering, the outward gradient
 and the inner-lip tint. `lipUvBounds.mouthV` is the mouth line in UV space.
 
-`faceUv` is the live per-vertex camera-texture UV. It is already bound to the
-geometry, so a custom vertex shader reads it as `attribute vec2 faceUv`; the
-attribute object is exposed for uniforms, debugging, or readback.
+`faceUv` is the live per-vertex camera-texture UV, bound as `attribute vec2
+faceUv` and kept current while a custom material is in use. `restPosition` is
+the canonical position in cm. `personLeftSign` is −1 on the mirrored webcam:
+read the design at `(1 − u, v)` there. `uniforms` holds the layer's
+`uPresence` (spread it to fade with the face), `uPersonLeftSign` and the face's
+live skin probe uniforms (`skin.uniforms`: `uSkinStats`, `uSkinStatsPacked`,
+`uSkinMap`, `uSkinLod`, `uSkinSqrt`), so spreading `uniforms` whole is enough;
+`skin` is the face's skin probe.
+
+Draw in the face layer: spread `MAKEUP_BLENDING`, keep `depthWrite={false}`
+and write premultiplied colour (`rgb × coverage, coverage`); a `transparent`
+material draws in the later transparent pass, where the head occluder can
+hide it.
 
 ```tsx
 <LipEffect
   designTexture={texture}
-  material={({ cameraTexture, designTexture, maskMode }) => (
+  material={({ cameraTexture, designTexture, maskMode, uniforms }) => (
     <shaderMaterial
       uniforms={{
         cameraTexture: { value: cameraTexture },
         designTexture: { value: designTexture },
+        // 1: decode the design's sRGB here (the built-in material's rule).
+        decodeDesign: { value: designTexture ? lipEffectDesignDecode(designTexture) : 0 },
+        uPresence: uniforms.uPresence,
+        uPersonLeftSign: uniforms.uPersonLeftSign,
       }}
       vertexShader={`
         attribute vec2 faceUv;
@@ -246,16 +308,22 @@ attribute object is exposed for uniforms, debugging, or readback.
         }`}
       fragmentShader={`
         uniform sampler2D cameraTexture; uniform sampler2D designTexture;
+        uniform float decodeDesign; uniform float uPresence; uniform float uPersonLeftSign;
         varying vec2 vFaceUv; varying vec2 vUv;
         void main() {
-          vec4 design = texture2D(designTexture, vUv);
+          vec2 uv = uPersonLeftSign < 0.0 ? vec2(1.0 - vUv.x, vUv.y) : vUv;
+          vec4 design = texture2D(designTexture, uv);
+          vec3 paint = mix(design.rgb, pow(max(design.rgb, vec3(0.0)), vec3(2.2)), decodeDesign);
           vec3 skin = texture2D(cameraTexture, vFaceUv).rgb;
-          gl_FragColor = vec4(skin * design.rgb, design.a);
+          float c = design.a * uPresence;
+          gl_FragColor = vec4(linearToOutputTexel(vec4(skin * paint, 1.0)).rgb * c, c);
         }`}
-      transparent
+      {...MAKEUP_BLENDING}
       depthWrite={false}
       stencilWrite
-      stencilRef={1}
+      stencilRef={FACE_ATLAS_STENCIL.mouth}
+      stencilFuncMask={FACE_ATLAS_STENCIL.mouth}
+      stencilWriteMask={0}
       stencilFunc={
         maskMode === "outer-and-inner-lips" ? THREE.NotEqualStencilFunc : THREE.AlwaysStencilFunc
       }
@@ -269,24 +337,32 @@ attribute object is exposed for uniforms, debugging, or readback.
 
 Four complete factories (animated gloss, noise texture, iridescence, time-based
 shimmer) are documented in [Lip Shader Examples](/examples/lip-shaders) and run
-on the `/lip-effect` page.
+on the `/makeup` page; they use `LIP_EFFECT_VERTEX_SHADER`, which provides
+`vUv`, `vFaceUv`, `vLipEdge`, `vNormal` and `vViewDir`.
 
 Honour `maskMode` with the stencil test shown above; that is exactly what the
-built-in `LipEffectMaterial` does through its `subtractMouth` prop. Note that
-three.js only evaluates `stencilFunc` while `stencilWrite` is true, so keep it
-on and use the keep-ops: the material then compares against the mouth stencil
-without ever writing to it. The lip triangles already exclude the mouth cavity,
-so the stencil is the guard for anything that reaches past them. It is
-exported so you can reuse the default shader with different settings:
+built-in `LipEffectMaterial` does through its `subtractMouth` prop. three.js
+only evaluates `stencilFunc` while `stencilWrite` is true, so keep it on and
+use the keep-ops and a zero write mask: the material then compares the mouth
+bit without ever writing to the stencil (the face's self-occlusion pass owns
+bit 0x80, so always test with `stencilFuncMask={FACE_ATLAS_STENCIL.mouth}`).
+The built-in material is exported so you can reuse it with different settings.
+It never reads the camera uv per vertex, so pass `faceUv={false}` with a factory
+that returns it (a factory cannot be inspected in advance; a
+`<LipEffectMaterial>` node or a `useLipEffectMaterial` instance passed directly
+needs nothing):
 
 ```tsx
-material={(context) => (
-  <LipEffectMaterial
-    cameraTexture={context.cameraTexture}
-    designTexture={context.designTexture}
-    settings={resolveLipEffectSettings({ ...context.settings, preset: "metallic" })}
-    lipUvBounds={context.lipUvBounds}
-    subtractMouth={context.maskMode === "outer-and-inner-lips"}
-  />
-)}
+<LipEffect
+  faceUv={false}
+  material={(context) => (
+    <LipEffectMaterial
+      cameraTexture={context.cameraTexture}
+      designTexture={context.designTexture}
+      settings={resolveLipEffectSettings({ ...context.settings, preset: "metallic" })}
+      lipUvBounds={context.lipUvBounds}
+      subtractMouth={context.maskMode === "outer-and-inner-lips"}
+    />
+  )}
+/>
 ```

package/docs/guides/lip-uv-template.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect x="1.28" y="1.28" width="1021.44" height="1021.44" fill="none" stroke="#cbd5e1" stroke-width="2.56"/><path d="M540.93,666.01L511.98,668.19L539.77,682.19ZM483.07,666.01L484.23,682.19L511.98,668.19ZM512.02,682.22L539.77,682.19L511.98,668.19ZM512.02,682.22L511.98,668.19L484.23,682.19ZM540.93,666.01L539.77,682.19L573.66,673ZM483.07,666.01L450.34,673L484.23,682.19ZM566.45,684.57L573.66,673L539.77,682.19ZM457.55,684.57L484.23,682.19L450.34,673ZM573.66,673L566.45,684.57L599.43,682.54ZM450.34,673L424.57,682.54L457.55,684.57ZM591.09,690.06L599.43,682.54L566.45,684.57ZM432.91,690.06L457.55,684.57L424.57,682.54ZM591.09,690.06L613.64,697.41L599.43,682.54ZM432.91,690.06L424.57,682.54L410.36,697.41ZM622.18,693.97L599.43,682.54L613.64,697.41ZM401.82,693.97L410.36,697.41L424.57,682.54ZM584.94,699.08L582.49,708.98L607.44,702.13ZM439.06,699.08L416.55,702.13L441.51,708.98ZM600.69,708.98L607.44,702.13L582.49,708.98ZM423.31,708.98L441.51,708.98L416.55,702.13ZM611.29,723.5L618.39,727.26L626.58,710.62ZM412.71,723.5L397.42,710.62L405.61,727.26ZM632.86,711.38L626.58,710.62L618.39,727.26ZM391.14,711.38L405.61,727.26L397.42,710.62ZM590.68,728.93L595.65,737.34L611.29,723.5ZM433.32,728.93L412.71,723.5L428.35,737.34ZM618.39,727.26L611.29,723.5L595.65,737.34ZM405.61,727.26L428.35,737.34L412.71,723.5ZM568.49,748.33L595.65,737.34L566.16,732.99ZM455.51,748.33L457.84,732.99L428.35,737.34ZM590.68,728.93L566.16,732.99L595.65,737.34ZM433.32,728.93L428.35,737.34L457.84,732.99ZM511.98,754.71L540.34,753.9L511.98,736.65ZM511.98,754.71L511.98,736.65L483.66,753.9ZM539.56,735.09L511.98,736.65L540.34,753.9ZM484.44,735.09L483.66,753.9L511.98,736.65ZM604.54,718.67L622.17,710.86L600.88,712.09ZM419.46,718.67L423.12,712.09L401.81,710.86ZM610.68,710.61L600.88,712.09L622.17,710.86ZM413.32,710.61L401.81,710.86L423.12,712.09ZM626.58,710.62L622.17,710.86L611.29,723.5ZM397.42,710.62L412.71,723.5L401.81,710.86ZM604.54,718.67L611.29,723.5L622.17,710.86ZM419.46,718.67L401.81,710.86L412.71,723.5ZM539.77,682.19L538.47,696.52L566.45,684.57ZM484.23,682.19L457.55,684.57L485.53,696.52ZM562.82,697.2L566.45,684.57L538.47,696.52ZM461.18,697.2L485.53,696.52L457.55,684.57ZM566.45,684.57L562.82,697.2L591.09,690.06ZM457.55,684.57L432.91,690.06L461.18,697.2ZM584.94,699.08L591.09,690.06L562.82,697.2ZM439.06,699.08L461.18,697.2L432.91,690.06ZM591.09,690.06L584.94,699.08L613.64,697.41ZM432.91,690.06L410.36,697.41L439.06,699.08ZM607.44,702.13L613.64,697.41L584.94,699.08ZM416.55,702.13L439.06,699.08L410.36,697.41ZM587.29,720.42L590.68,728.93L604.54,718.67ZM436.71,720.42L419.46,718.67L433.32,728.93ZM611.29,723.5L604.54,718.67L590.68,728.93ZM412.71,723.5L433.32,728.93L419.46,718.67ZM566.16,732.99L590.68,728.93L565.23,721.54ZM457.84,732.99L458.77,721.54L433.32,728.93ZM587.29,720.42L565.23,721.54L590.68,728.93ZM436.71,720.42L433.32,728.93L458.77,721.54ZM511.98,736.65L539.56,735.09L511.98,722.88ZM511.98,736.65L511.98,722.88L484.44,735.09ZM539.52,721.54L511.98,722.88L539.56,735.09ZM484.48,721.54L484.44,735.09L511.98,722.88ZM511.98,722.88L539.52,721.54L511.98,711.96ZM511.98,722.88L511.98,711.96L484.48,721.54ZM539.61,711.96L511.98,711.96L539.52,721.54ZM484.39,711.96L484.48,721.54L511.98,711.96ZM564.57,711.96L565.23,721.54L585.79,711.96ZM459.43,711.96L438.21,711.96L458.77,721.54ZM587.29,720.42L585.79,711.96L565.23,721.54ZM436.71,720.42L458.77,721.54L438.21,711.96ZM600.88,712.09L585.79,711.96L604.54,718.67ZM423.12,712.09L419.46,718.67L438.21,711.96ZM587.29,720.42L604.54,718.67L585.79,711.96ZM436.71,720.42L438.21,711.96L419.46,718.67ZM562.82,697.2L560.97,708.98L584.94,699.08ZM461.18,697.2L439.06,699.08L463.03,708.98ZM582.49,708.98L584.94,699.08L560.97,708.98ZM441.51,708.98L463.03,708.98L439.06,699.08ZM538.47,696.52L537.2,708.98L562.82,697.2ZM485.53,696.52L461.18,697.2L486.8,708.98ZM560.97,708.98L562.82,697.2L537.2,708.98ZM463.03,708.98L486.8,708.98L461.18,697.2ZM607.44,702.13L600.69,708.98L622.17,710.86ZM416.55,702.13L401.81,710.86L423.31,708.98ZM610.68,710.61L622.17,710.86L600.69,708.98ZM413.32,710.61L423.31,708.98L401.81,710.86ZM512.02,682.22L512.02,695.53L539.77,682.19ZM512.02,682.22L484.23,682.19L512.02,695.53ZM538.47,696.52L539.77,682.19L512.02,695.53ZM485.53,696.52L512.02,695.53L484.23,682.19ZM512.02,695.53L512.02,708.96L538.47,696.52ZM512.02,695.53L485.53,696.52L512.02,708.96ZM537.2,708.98L538.47,696.52L512.02,708.96ZM486.8,708.98L512.02,708.96L485.53,696.52ZM539.52,721.54L565.23,721.54L539.61,711.96ZM484.48,721.54L484.39,711.96L458.77,721.54ZM564.57,711.96L539.61,711.96L565.23,721.54ZM459.43,711.96L458.77,721.54L484.39,711.96ZM539.56,735.09L566.16,732.99L539.52,721.54ZM484.44,735.09L484.48,721.54L457.84,732.99ZM565.23,721.54L539.52,721.54L566.16,732.99ZM458.77,721.54L457.84,732.99L484.48,721.54ZM540.34,753.9L568.49,748.33L539.56,735.09ZM483.66,753.9L484.44,735.09L455.51,748.33ZM566.16,732.99L539.56,735.09L568.49,748.33ZM457.84,732.99L455.51,748.33L484.44,735.09ZM613.64,697.41L607.44,702.13L626.58,710.62ZM410.36,697.41L397.42,710.62L416.55,702.13ZM622.17,710.86L626.58,710.62L607.44,702.13ZM401.81,710.86L416.55,702.13L397.42,710.62ZM613.64,697.41L626.58,710.62L622.18,693.97ZM410.36,697.41L401.82,693.97L397.42,710.62ZM632.86,711.38L622.18,693.97L626.58,710.62ZM391.14,711.38L397.42,710.62L401.82,693.97Z" fill="#e85d75" fill-opacity="0.08" stroke="#94a3b8" stroke-width="1.28" stroke-linejoin="round"/><path d="M610.68,710.61L600.69,708.98L600.88,712.09ZM413.32,710.61L423.12,712.09L423.31,708.98ZM511.98,711.96L539.61,711.96L512.02,708.96ZM511.98,711.96L512.02,708.96L484.39,711.96ZM537.2,708.98L512.02,708.96L539.61,711.96ZM486.8,708.98L484.39,711.96L512.02,708.96ZM539.61,711.96L564.57,711.96L537.2,708.98ZM484.39,711.96L486.8,708.98L459.43,711.96ZM560.97,708.98L537.2,708.98L564.57,711.96ZM463.03,708.98L459.43,711.96L486.8,708.98ZM564.57,711.96L585.79,711.96L560.97,708.98ZM459.43,711.96L463.03,708.98L438.21,711.96ZM582.49,708.98L560.97,708.98L585.79,711.96ZM441.51,708.98L438.21,711.96L463.03,708.98ZM585.79,711.96L600.88,712.09L582.49,708.98ZM438.21,711.96L441.51,708.98L423.12,712.09ZM600.69,708.98L582.49,708.98L600.88,712.09ZM423.31,708.98L423.12,712.09L441.51,708.98Z" fill="#2563eb" fill-opacity="0.25" stroke="none"/><polygon points="391.14,711.38 405.61,727.26 428.35,737.34 455.51,748.33 483.66,753.9 511.98,754.71 540.34,753.9 568.49,748.33 595.65,737.34 618.39,727.26 632.86,711.38 622.18,693.97 599.43,682.54 573.66,673 540.93,666.01 511.98,668.19 483.07,666.01 450.34,673 424.57,682.54 401.82,693.97" fill="none" stroke="#e85d75" stroke-width="2.56" stroke-linejoin="round"/><polygon points="413.32,710.61 423.12,712.09 438.21,711.96 459.43,711.96 484.39,711.96 511.98,711.96 539.61,711.96 564.57,711.96 585.79,711.96 600.88,712.09 610.68,710.61 600.69,708.98 582.49,708.98 560.97,708.98 537.2,708.98 512.02,708.96 486.8,708.98 463.03,708.98 441.51,708.98 423.31,708.98" fill="none" stroke="#2563eb" stroke-width="2.56" stroke-dasharray="7.68 5.12" stroke-linejoin="round"/><text x="378.85" y="710.36" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">subject's RIGHT ▸</text><text x="645.15" y="710.36" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">◂ subject's LEFT</text><text x="512" y="653.73" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">upper lip  (outer ring = painted edge)</text><text x="512" y="783.38" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lower lip  ·  dashed ring = mouth interior, hidden in outer-and-inner-lips mode</text><text x="512" y="804.68" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lip region: u 0.38–0.62, v 0.26–0.35  (image x 38–62%, y 65–74%)</text><text x="25.6" y="41.98" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a" font-weight="bold">Lip UV template — canonical face UV atlas</text><text x="25.6" y="63.28" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">1024×1024 canvas, same layout as Canonical_Face_Color.png.</text><text x="25.6" y="84.58" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Only the lip triangles are sampled; transparent pixels leave the skin untouched.</text><text x="25.6" y="105.88" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Image LEFT = subject's RIGHT (screen-right on a mirrored webcam view).</text><text x="25.6" y="998.4" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">generated from canonical_face_model.obj uv attributes</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect x="1.28" y="1.28" width="1021.44" height="1021.44" fill="none" stroke="#cbd5e1" stroke-width="2.56"/><path d="M540.93,666.01L511.98,668.19L539.77,682.19ZM483.07,666.01L484.23,682.19L511.98,668.19ZM512.02,682.22L539.77,682.19L511.98,668.19ZM512.02,682.22L511.98,668.19L484.23,682.19ZM540.93,666.01L539.77,682.19L573.66,673ZM483.07,666.01L450.34,673L484.23,682.19ZM566.45,684.57L573.66,673L539.77,682.19ZM457.55,684.57L484.23,682.19L450.34,673ZM573.66,673L566.45,684.57L599.43,682.54ZM450.34,673L424.57,682.54L457.55,684.57ZM591.09,690.06L599.43,682.54L566.45,684.57ZM432.91,690.06L457.55,684.57L424.57,682.54ZM591.09,690.06L613.64,697.41L599.43,682.54ZM432.91,690.06L424.57,682.54L410.36,697.41ZM622.18,693.97L599.43,682.54L613.64,697.41ZM401.82,693.97L410.36,697.41L424.57,682.54ZM584.94,699.08L582.49,708.98L607.44,702.13ZM439.06,699.08L416.55,702.13L441.51,708.98ZM600.69,708.98L607.44,702.13L582.49,708.98ZM423.31,708.98L441.51,708.98L416.55,702.13ZM611.29,723.5L618.39,727.26L626.58,710.62ZM412.71,723.5L397.42,710.62L405.61,727.26ZM632.86,711.38L626.58,710.62L618.39,727.26ZM391.14,711.38L405.61,727.26L397.42,710.62ZM590.68,728.93L595.65,737.34L611.29,723.5ZM433.32,728.93L412.71,723.5L428.35,737.34ZM618.39,727.26L611.29,723.5L595.65,737.34ZM405.61,727.26L428.35,737.34L412.71,723.5ZM568.49,748.33L595.65,737.34L566.16,732.99ZM455.51,748.33L457.84,732.99L428.35,737.34ZM590.68,728.93L566.16,732.99L595.65,737.34ZM433.32,728.93L428.35,737.34L457.84,732.99ZM511.98,754.71L540.34,753.9L511.98,736.65ZM511.98,754.71L511.98,736.65L483.66,753.9ZM539.56,735.09L511.98,736.65L540.34,753.9ZM484.44,735.09L483.66,753.9L511.98,736.65ZM604.54,718.67L622.17,710.86L600.88,712.09ZM419.46,718.67L423.12,712.09L401.81,710.86ZM610.68,710.61L600.88,712.09L622.17,710.86ZM413.32,710.61L401.81,710.86L423.12,712.09ZM626.58,710.62L622.17,710.86L611.29,723.5ZM397.42,710.62L412.71,723.5L401.81,710.86ZM604.54,718.67L611.29,723.5L622.17,710.86ZM419.46,718.67L401.81,710.86L412.71,723.5ZM539.77,682.19L538.47,696.52L566.45,684.57ZM484.23,682.19L457.55,684.57L485.53,696.52ZM562.82,697.2L566.45,684.57L538.47,696.52ZM461.18,697.2L485.53,696.52L457.55,684.57ZM566.45,684.57L562.82,697.2L591.09,690.06ZM457.55,684.57L432.91,690.06L461.18,697.2ZM584.94,699.08L591.09,690.06L562.82,697.2ZM439.06,699.08L461.18,697.2L432.91,690.06ZM591.09,690.06L584.94,699.08L613.64,697.41ZM432.91,690.06L410.36,697.41L439.06,699.08ZM607.44,702.13L613.64,697.41L584.94,699.08ZM416.55,702.13L439.06,699.08L410.36,697.41ZM587.29,720.42L590.68,728.93L604.54,718.67ZM436.71,720.42L419.46,718.67L433.32,728.93ZM611.29,723.5L604.54,718.67L590.68,728.93ZM412.71,723.5L433.32,728.93L419.46,718.67ZM566.16,732.99L590.68,728.93L565.23,721.54ZM457.84,732.99L458.77,721.54L433.32,728.93ZM587.29,720.42L565.23,721.54L590.68,728.93ZM436.71,720.42L433.32,728.93L458.77,721.54ZM511.98,736.65L539.56,735.09L511.98,722.88ZM511.98,736.65L511.98,722.88L484.44,735.09ZM539.52,721.54L511.98,722.88L539.56,735.09ZM484.48,721.54L484.44,735.09L511.98,722.88ZM511.98,722.88L539.52,721.54L511.98,711.96ZM511.98,722.88L511.98,711.96L484.48,721.54ZM539.61,711.96L511.98,711.96L539.52,721.54ZM484.39,711.96L484.48,721.54L511.98,711.96ZM564.57,711.96L565.23,721.54L585.79,711.96ZM459.43,711.96L438.21,711.96L458.77,721.54ZM587.29,720.42L585.79,711.96L565.23,721.54ZM436.71,720.42L458.77,721.54L438.21,711.96ZM600.88,712.09L585.79,711.96L604.54,718.67ZM423.12,712.09L419.46,718.67L438.21,711.96ZM587.29,720.42L604.54,718.67L585.79,711.96ZM436.71,720.42L438.21,711.96L419.46,718.67ZM562.82,697.2L560.97,708.98L584.94,699.08ZM461.18,697.2L439.06,699.08L463.03,708.98ZM582.49,708.98L584.94,699.08L560.97,708.98ZM441.51,708.98L463.03,708.98L439.06,699.08ZM538.47,696.52L537.2,708.98L562.82,697.2ZM485.53,696.52L461.18,697.2L486.8,708.98ZM560.97,708.98L562.82,697.2L537.2,708.98ZM463.03,708.98L486.8,708.98L461.18,697.2ZM607.44,702.13L600.69,708.98L622.17,710.86ZM416.55,702.13L401.81,710.86L423.31,708.98ZM610.68,710.61L622.17,710.86L600.69,708.98ZM413.32,710.61L423.31,708.98L401.81,710.86ZM512.02,682.22L512.02,695.53L539.77,682.19ZM512.02,682.22L484.23,682.19L512.02,695.53ZM538.47,696.52L539.77,682.19L512.02,695.53ZM485.53,696.52L512.02,695.53L484.23,682.19ZM512.02,695.53L512.02,708.96L538.47,696.52ZM512.02,695.53L485.53,696.52L512.02,708.96ZM537.2,708.98L538.47,696.52L512.02,708.96ZM486.8,708.98L512.02,708.96L485.53,696.52ZM539.52,721.54L565.23,721.54L539.61,711.96ZM484.48,721.54L484.39,711.96L458.77,721.54ZM564.57,711.96L539.61,711.96L565.23,721.54ZM459.43,711.96L458.77,721.54L484.39,711.96ZM539.56,735.09L566.16,732.99L539.52,721.54ZM484.44,735.09L484.48,721.54L457.84,732.99ZM565.23,721.54L539.52,721.54L566.16,732.99ZM458.77,721.54L457.84,732.99L484.48,721.54ZM540.34,753.9L568.49,748.33L539.56,735.09ZM483.66,753.9L484.44,735.09L455.51,748.33ZM566.16,732.99L539.56,735.09L568.49,748.33ZM457.84,732.99L455.51,748.33L484.44,735.09ZM613.64,697.41L607.44,702.13L626.58,710.62ZM410.36,697.41L397.42,710.62L416.55,702.13ZM622.17,710.86L626.58,710.62L607.44,702.13ZM401.81,710.86L416.55,702.13L397.42,710.62ZM613.64,697.41L626.58,710.62L622.18,693.97ZM410.36,697.41L401.82,693.97L397.42,710.62ZM632.86,711.38L622.18,693.97L626.58,710.62ZM391.14,711.38L397.42,710.62L401.82,693.97Z" fill="#e85d75" fill-opacity="0.18" stroke="none"/><path d="M540.93,666.01L511.98,668.19M511.98,668.19L483.07,666.01M573.66,673L540.93,666.01M483.07,666.01L450.34,673M599.43,682.54L573.66,673M450.34,673L424.57,682.54M622.18,693.97L599.43,682.54M424.57,682.54L401.82,693.97M582.49,708.98L600.69,708.98M423.31,708.98L441.51,708.98M618.39,727.26L632.86,711.38M391.14,711.38L405.61,727.26M595.65,737.34L618.39,727.26M405.61,727.26L428.35,737.34M568.49,748.33L595.65,737.34M428.35,737.34L455.51,748.33M511.98,754.71L540.34,753.9M483.66,753.9L511.98,754.71M610.68,710.61L600.88,712.09M423.12,712.09L413.32,710.61M539.61,711.96L511.98,711.96M511.98,711.96L484.39,711.96M585.79,711.96L564.57,711.96M459.43,711.96L438.21,711.96M600.88,712.09L585.79,711.96M438.21,711.96L423.12,712.09M560.97,708.98L582.49,708.98M441.51,708.98L463.03,708.98M537.2,708.98L560.97,708.98M463.03,708.98L486.8,708.98M600.69,708.98L610.68,710.61M413.32,710.61L423.31,708.98M512.02,708.96L537.2,708.98M486.8,708.98L512.02,708.96M564.57,711.96L539.61,711.96M484.39,711.96L459.43,711.96M540.34,753.9L568.49,748.33M455.51,748.33L483.66,753.9M632.86,711.38L622.18,693.97M401.82,693.97L391.14,711.38" fill="none" stroke="#e85d75" stroke-width="2.56" stroke-linecap="round"/><path d="M610.68,710.61L600.69,708.98L600.88,712.09ZM413.32,710.61L423.12,712.09L423.31,708.98ZM511.98,711.96L539.61,711.96L512.02,708.96ZM511.98,711.96L512.02,708.96L484.39,711.96ZM537.2,708.98L512.02,708.96L539.61,711.96ZM486.8,708.98L484.39,711.96L512.02,708.96ZM539.61,711.96L564.57,711.96L537.2,708.98ZM484.39,711.96L486.8,708.98L459.43,711.96ZM560.97,708.98L537.2,708.98L564.57,711.96ZM463.03,708.98L459.43,711.96L486.8,708.98ZM564.57,711.96L585.79,711.96L560.97,708.98ZM459.43,711.96L463.03,708.98L438.21,711.96ZM582.49,708.98L560.97,708.98L585.79,711.96ZM441.51,708.98L438.21,711.96L463.03,708.98ZM585.79,711.96L600.88,712.09L582.49,708.98ZM438.21,711.96L441.51,708.98L423.12,712.09ZM600.69,708.98L582.49,708.98L600.88,712.09ZM423.31,708.98L423.12,712.09L441.51,708.98Z" fill="#2563eb" fill-opacity="0.18" stroke="none"/><path d="M610.68,710.61L600.69,708.98M600.88,712.09L610.68,710.61M413.32,710.61L423.12,712.09M423.31,708.98L413.32,710.61M511.98,711.96L539.61,711.96M484.39,711.96L511.98,711.96M537.2,708.98L512.02,708.96M512.02,708.96L486.8,708.98M539.61,711.96L564.57,711.96M459.43,711.96L484.39,711.96M560.97,708.98L537.2,708.98M486.8,708.98L463.03,708.98M564.57,711.96L585.79,711.96M438.21,711.96L459.43,711.96M582.49,708.98L560.97,708.98M463.03,708.98L441.51,708.98M585.79,711.96L600.88,712.09M423.12,712.09L438.21,711.96M600.69,708.98L582.49,708.98M441.51,708.98L423.31,708.98" fill="none" stroke="#2563eb" stroke-width="2.56" stroke-linecap="round"/><path d="M540.93,666.01L511.98,668.19L539.77,682.19ZM483.07,666.01L484.23,682.19L511.98,668.19ZM512.02,682.22L539.77,682.19L511.98,668.19ZM512.02,682.22L511.98,668.19L484.23,682.19ZM540.93,666.01L539.77,682.19L573.66,673ZM483.07,666.01L450.34,673L484.23,682.19ZM566.45,684.57L573.66,673L539.77,682.19ZM457.55,684.57L484.23,682.19L450.34,673ZM573.66,673L566.45,684.57L599.43,682.54ZM450.34,673L424.57,682.54L457.55,684.57ZM591.09,690.06L599.43,682.54L566.45,684.57ZM432.91,690.06L457.55,684.57L424.57,682.54ZM591.09,690.06L613.64,697.41L599.43,682.54ZM432.91,690.06L424.57,682.54L410.36,697.41ZM622.18,693.97L599.43,682.54L613.64,697.41ZM401.82,693.97L410.36,697.41L424.57,682.54ZM584.94,699.08L582.49,708.98L607.44,702.13ZM439.06,699.08L416.55,702.13L441.51,708.98ZM600.69,708.98L607.44,702.13L582.49,708.98ZM423.31,708.98L441.51,708.98L416.55,702.13ZM611.29,723.5L618.39,727.26L626.58,710.62ZM412.71,723.5L397.42,710.62L405.61,727.26ZM632.86,711.38L626.58,710.62L618.39,727.26ZM391.14,711.38L405.61,727.26L397.42,710.62ZM590.68,728.93L595.65,737.34L611.29,723.5ZM433.32,728.93L412.71,723.5L428.35,737.34ZM618.39,727.26L611.29,723.5L595.65,737.34ZM405.61,727.26L428.35,737.34L412.71,723.5ZM568.49,748.33L595.65,737.34L566.16,732.99ZM455.51,748.33L457.84,732.99L428.35,737.34ZM590.68,728.93L566.16,732.99L595.65,737.34ZM433.32,728.93L428.35,737.34L457.84,732.99ZM511.98,754.71L540.34,753.9L511.98,736.65ZM511.98,754.71L511.98,736.65L483.66,753.9ZM539.56,735.09L511.98,736.65L540.34,753.9ZM484.44,735.09L483.66,753.9L511.98,736.65ZM604.54,718.67L622.17,710.86L600.88,712.09ZM419.46,718.67L423.12,712.09L401.81,710.86ZM610.68,710.61L600.88,712.09L622.17,710.86ZM413.32,710.61L401.81,710.86L423.12,712.09ZM626.58,710.62L622.17,710.86L611.29,723.5ZM397.42,710.62L412.71,723.5L401.81,710.86ZM604.54,718.67L611.29,723.5L622.17,710.86ZM419.46,718.67L401.81,710.86L412.71,723.5ZM539.77,682.19L538.47,696.52L566.45,684.57ZM484.23,682.19L457.55,684.57L485.53,696.52ZM562.82,697.2L566.45,684.57L538.47,696.52ZM461.18,697.2L485.53,696.52L457.55,684.57ZM566.45,684.57L562.82,697.2L591.09,690.06ZM457.55,684.57L432.91,690.06L461.18,697.2ZM584.94,699.08L591.09,690.06L562.82,697.2ZM439.06,699.08L461.18,697.2L432.91,690.06ZM591.09,690.06L584.94,699.08L613.64,697.41ZM432.91,690.06L410.36,697.41L439.06,699.08ZM607.44,702.13L613.64,697.41L584.94,699.08ZM416.55,702.13L439.06,699.08L410.36,697.41ZM587.29,720.42L590.68,728.93L604.54,718.67ZM436.71,720.42L419.46,718.67L433.32,728.93ZM611.29,723.5L604.54,718.67L590.68,728.93ZM412.71,723.5L433.32,728.93L419.46,718.67ZM566.16,732.99L590.68,728.93L565.23,721.54ZM457.84,732.99L458.77,721.54L433.32,728.93ZM587.29,720.42L565.23,721.54L590.68,728.93ZM436.71,720.42L433.32,728.93L458.77,721.54ZM511.98,736.65L539.56,735.09L511.98,722.88ZM511.98,736.65L511.98,722.88L484.44,735.09ZM539.52,721.54L511.98,722.88L539.56,735.09ZM484.48,721.54L484.44,735.09L511.98,722.88ZM511.98,722.88L539.52,721.54L511.98,711.96ZM511.98,722.88L511.98,711.96L484.48,721.54ZM539.61,711.96L511.98,711.96L539.52,721.54ZM484.39,711.96L484.48,721.54L511.98,711.96ZM564.57,711.96L565.23,721.54L585.79,711.96ZM459.43,711.96L438.21,711.96L458.77,721.54ZM587.29,720.42L585.79,711.96L565.23,721.54ZM436.71,720.42L458.77,721.54L438.21,711.96ZM600.88,712.09L585.79,711.96L604.54,718.67ZM423.12,712.09L419.46,718.67L438.21,711.96ZM587.29,720.42L604.54,718.67L585.79,711.96ZM436.71,720.42L438.21,711.96L419.46,718.67ZM562.82,697.2L560.97,708.98L584.94,699.08ZM461.18,697.2L439.06,699.08L463.03,708.98ZM582.49,708.98L584.94,699.08L560.97,708.98ZM441.51,708.98L463.03,708.98L439.06,699.08ZM538.47,696.52L537.2,708.98L562.82,697.2ZM485.53,696.52L461.18,697.2L486.8,708.98ZM560.97,708.98L562.82,697.2L537.2,708.98ZM463.03,708.98L486.8,708.98L461.18,697.2ZM607.44,702.13L600.69,708.98L622.17,710.86ZM416.55,702.13L401.81,710.86L423.31,708.98ZM610.68,710.61L622.17,710.86L600.69,708.98ZM413.32,710.61L423.31,708.98L401.81,710.86ZM512.02,682.22L512.02,695.53L539.77,682.19ZM512.02,682.22L484.23,682.19L512.02,695.53ZM538.47,696.52L539.77,682.19L512.02,695.53ZM485.53,696.52L512.02,695.53L484.23,682.19ZM512.02,695.53L512.02,708.96L538.47,696.52ZM512.02,695.53L485.53,696.52L512.02,708.96ZM537.2,708.98L538.47,696.52L512.02,708.96ZM486.8,708.98L512.02,708.96L485.53,696.52ZM539.52,721.54L565.23,721.54L539.61,711.96ZM484.48,721.54L484.39,711.96L458.77,721.54ZM564.57,711.96L539.61,711.96L565.23,721.54ZM459.43,711.96L458.77,721.54L484.39,711.96ZM539.56,735.09L566.16,732.99L539.52,721.54ZM484.44,735.09L484.48,721.54L457.84,732.99ZM565.23,721.54L539.52,721.54L566.16,732.99ZM458.77,721.54L457.84,732.99L484.48,721.54ZM540.34,753.9L568.49,748.33L539.56,735.09ZM483.66,753.9L484.44,735.09L455.51,748.33ZM566.16,732.99L539.56,735.09L568.49,748.33ZM457.84,732.99L455.51,748.33L484.44,735.09ZM613.64,697.41L607.44,702.13L626.58,710.62ZM410.36,697.41L397.42,710.62L416.55,702.13ZM622.17,710.86L626.58,710.62L607.44,702.13ZM401.81,710.86L416.55,702.13L397.42,710.62ZM613.64,697.41L626.58,710.62L622.18,693.97ZM410.36,697.41L401.82,693.97L397.42,710.62ZM632.86,711.38L622.18,693.97L626.58,710.62ZM391.14,711.38L397.42,710.62L401.82,693.97Z" fill="none" stroke="#94a3b8" stroke-width="1.28" stroke-linejoin="round"/><text x="378.85" y="710.36" text-anchor="end" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">person's RIGHT ▸</text><text x="645.15" y="710.36" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">◂ person's LEFT</text><text x="512" y="653.73" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">upper lip  (pink outline = painted edge)</text><text x="512" y="783.38" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lower lip  ·  blue = mouth interior, cut out in outer-and-inner-lips mode</text><text x="512" y="804.68" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">lip region: u 0.38–0.62, v 0.26–0.35  (image x 38–62%, y 65–74%)</text><text x="25.6" y="41.98" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a" font-weight="bold">Lip template: the face atlas</text><text x="25.6" y="63.28" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">1024×1024 canvas: the face atlas (FACE_ATLAS_UVS, as Canonical_Face_Color.png).</text><text x="25.6" y="84.58" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Only the lip triangles are sampled; transparent pixels leave the skin untouched.</text><text x="25.6" y="105.88" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">Paint as on an unmirrored photo: image LEFT = the person's RIGHT on every feed</text><text x="25.6" y="127.18" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">(the SDK flips the design on the mirrored webcam).</text><text x="25.6" y="998.4" text-anchor="start" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="16.38" fill="#0f172a">generated from the bundled face atlas data</text></svg>

package/docs/guides/makeup-design-textures.mdx

@@ -0,0 +1,109 @@
+---
+title: "Makeup Design Textures"
+description: "How to paint art for MakeupDesign: the face atlas canvas, sides on every feed, alpha and colour, regions, finishes, and the example art."
+sidebarTitle: "Makeup Design Textures"
+icon: "palette"
+---
+
+`MakeupDesign` (from `@vincentt-xr/sdk/face-effects`) paints your art on the
+live face: freckles, face gems, graphic liner, face paint. The art is shaded
+like makeup, relative to the person's own skin and light, with a finish.
+
+```tsx
+import { MakeupDesign } from "@vincentt-xr/sdk/face-effects";
+
+<MakeupDesign
+  texture="/makeup/freckles.svg"
+  region={["cheeks", "nose"]}
+  coverage={0.45}
+  opacity={0.8}
+/>;
+```
+
+## The canvas
+
+The layout, templates and loading rules are in
+[Face Atlas Textures](/guides/face-atlas-textures); props and finishes are in
+[Makeup](/api/makeup).
+
+- **One square image in the face atlas** (`FACE_ATLAS_UVS`): the layout of the
+  canonical face OBJ, the same one LipEffect designs and face swap use. 1024×1024
+  is enough; 2048×2048 for fine detail.
+- **Upright, as on an unmirrored photo.** Image-left is the person's **right**,
+  image-right is their **left**; the forehead is at the top.
+- **Transparent where nothing is painted.** Alpha is where the art paints;
+  soft alpha gives soft edges.
+- **Colours are the paint**, in sRGB. `color` multiplies them: paint white art
+  to recolour it from code.
+
+<img
+  src="/guides/face-atlas-template.svg"
+  alt="Face atlas template: every region outlined, with the person's sides labelled"
+/>
+
+The template is generated from the bundled atlas data
+(`pnpm dlx tsx scripts/generate-face-atlas.ts`); in an app,
+`createFaceAtlasGuideSvg()` / `createFaceAtlasGuidePngBlob()` draw the same
+guide. Put it on a layer under your art and hide it before exporting.
+
+## Sides on every feed
+
+Each side of the art stays on the person's own side on every feed. On the rear
+camera, images and video the art is used as painted; on the mirrored webcam it
+is sampled at `(1 − u, v)`. The atlas is symmetric to 0.001, so the flip is
+exact. A mark on the skin therefore reads backwards on the mirrored webcam, as
+it does in a mirror.
+
+To check a setup, use the side-test art: an L on the person's own left cheek.
+It must sit on the person's left cheek on the webcam and on the rear camera.
+
+## Regions
+
+`region` limits where the art may paint, as one `FaceAtlasRegion` or a list:
+`face` (default: everything but the eye and mouth openings and the nostrils),
+`skin`, `lips`, `mouth`, `eyes`, `lids`, `brows`, `cheeks`, `nose`,
+`forehead`, `jaw`. Art outside the region is never drawn, and a smaller region
+draws fewer pixels. `eyes` and `mouth` are the openings: art there covers the
+eyeballs or the inside of the mouth.
+
+Liner drawn on the lash line is cut there by the eye opening; draw it just
+above the line.
+
+## Finish and coverage
+
+| Setting    | Use                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------ |
+| `coverage` | 0 sheer: the art filters the skin and never lightens it (freckles). 1 opaque: it covers the skin |
+| `finish`   | `matte`, `satin`, `gloss` (gems, wet looks), `shimmer`, `metallic`, `glitter`                    |
+| `opacity`  | Linear amount, times the art's alpha                                                             |
+| `side`     | `both`, or the person's own `left` / `right` half of the art                                     |
+
+Finishes add their highlight from the live face's normals and the room light,
+so painted facets (on gems) and the finish's highlight work together.
+
+## Texture inputs
+
+- **URL**: PNG, WebP or SVG with `width` and `height`. Loaded without Suspense,
+  premultiplied and mipmapped, and disposed by the component. A URL that
+  fails to load draws nothing (and warns once).
+- **`THREE.Texture`** you own: read as sRGB unless tagged
+  `LinearSRGBColorSpace`, and as premultiplied when `premultiplyAlpha` is set.
+  Leave a premultiplied texture untagged: tagged `SRGBColorSpace`, the GPU
+  decodes it before the alpha is divided out, which darkens soft edges (it
+  warns). It must sample upright as an image loaded with `flipY` does
+  (`TextureLoader`, `CanvasTexture`). The component never changes it.
+- **Material API**: `setMakeupDesignTexture(createMakeupMaterial("design").uniforms, texture)`.
+
+## Example art
+
+The SDK playground ships four examples in `example/public/makeup/`, drawn in
+atlas coordinates by `scripts/generate-makeup-samples.ts` (CC0, Vincentt):
+
+| File                | Settings                                                    |
+| ------------------- | ----------------------------------------------------------- |
+| `freckles.svg`      | `region={["cheeks", "nose"]} coverage={0.45} opacity={0.8}` |
+| `face-gems.svg`     | `region={["lids", "cheeks", "forehead"]} finish="gloss"`    |
+| `graphic-liner.svg` | `region={["lids", "forehead"]} opacity={0.95}`              |
+| `side-test.svg`     | `region="cheeks"`                                           |
+
+They are not part of the npm package: copy one into your app's public folder.

package/docs/introduction.mdx

@@ -106,13 +106,12 @@ summary only.
 
 - `/unified-architecture`: current debug-ui composition for a unified
   face-tracking scene.
-- `/testing-hook`: multi-face face-mesh sanity example using reusable
+- `/face-mesh?faces=two`: multi-face face-mesh sanity example using reusable
   scene-object/debug-ui APIs.
 - `/body`: visible body-tracking anchors using `BodyTracker` and
   `TrackingAnchor`.
 - `/debugger`: minimal debugger overlay example for metrics and runtime
   inspection.
-- `/viewport-editor`: reusable 3D scene editor fixture.
 - `/face-retouch-legacy`: legacy face-retouch shader controls with debug-ui
   settings.