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

package/dist/face-atlas/shading.d.ts

@@ -0,0 +1,406 @@
+/**
+ * The makeup shading core, as plain TypeScript: the constants the GLSL chunks
+ * (`./glsl`) are generated from, and a line-for-line mirror of the shader
+ * math for tests and docs. Colours are linear RGB unless a name says
+ * `encoded` (the output colour space, sRGB on the canvas).
+ *
+ * The model (FACE-1 #274, settled open questions 1 and 2):
+ * - Paint is shaded relative to the person's own skin. `S = lum(C) / lum(Rs)`
+ *   is the light on this pixel relative to the GLOBAL settled skin reference
+ *   `Rs`, so the shadow side of a side-lit face stays darker and skin tone
+ *   never enters the result.
+ * - The LOCAL low-pass `L` only separates the skin's own highlight (`Hcam`)
+ *   and clips it out of the diffuse term (hard for matte, soft otherwise).
+ * - One premultiplied operator for every finish: diffuse over the camera plus
+ *   a specular add. Finishes differ only in their diffuse and highlight terms.
+ */
+export type Vec3 = readonly [number, number, number];
+type MVec3 = [number, number, number];
+/** Finish ids, as the shader's `uFinish` uniform takes them. */
+export declare const MAKEUP_FINISH_ID: Readonly<{
+    readonly matte: 0;
+    readonly satin: 1;
+    readonly gloss: 2;
+    readonly shimmer: 3;
+    readonly metallic: 4;
+    readonly glitter: 5;
+}>;
+/** A finish name the shading core knows. */
+export type MakeupShadingFinish = keyof typeof MAKEUP_FINISH_ID;
+/** Auto-shade ids, as the shader's `uAutoShade` uniform takes them (`none` uses `uColor`). */
+export declare const MAKEUP_AUTO_SHADE_ID: Readonly<{
+    readonly none: 0;
+    readonly lips: 1;
+    readonly blush: 2;
+    readonly contour: 3;
+    readonly highlighter: 4;
+    readonly brows: 5;
+}>;
+/** A region whose `shade: "auto"` the shader derives from the person. */
+export type MakeupAutoShade = keyof typeof MAKEUP_AUTO_SHADE_ID;
+/** Linear-sRGB luminance weights (three.js `luminance()`). */
+export declare const MAKEUP_LUMA: Vec3;
+/** Skin-relative shading constants. */
+export declare const MAKEUP_SHADING: Readonly<{
+    /** Guards every division. */
+    readonly epsilon: 0.0001;
+    /** Clamp on the light ratio `S` (and the local ratio). */
+    readonly maxRatio: 4;
+    /** Clamp on the light-colour tint `(Rf / lum Rf) / (Rs / lum Rs)`. */
+    readonly tintMin: 0.85;
+    readonly tintMax: 1.15;
+    /** Soft-clip headroom over the local light, for every finish except matte (0). */
+    readonly clip: 0.15;
+    /** `Hcam = max(0, lum(C) − knee · lum(L))`: the real highlight on the skin. */
+    readonly highlightKnee: 1.1;
+    /**
+     * Low-pass weight (`skinMap.a`) below which a mip has no skin here: the
+     * local skin falls back to the coarser mip, then to the fast skin.
+     */
+    readonly lowpassMinWeight: 0.02;
+    /** Low-pass weight from which a mip's skin is used fully. */
+    readonly lowpassFullWeight: 0.1;
+    /**
+     * Size (texels per side) of the `skinMap` mip the local low-pass reads, so
+     * the low-pass radius on the face is the same at every probe size
+     * (`makeupSkinLod`: mip 2 of a 128² probe, mip 1 of 64²).
+     */
+    readonly lowpassTexels: 32;
+    /**
+     * Mips above the low-pass that the local skin falls back to where the
+     * low-pass has no skin (lips, eyes, brows): it keeps the large-scale light.
+     */
+    readonly lowpassCoarseLods: 2;
+    /** Width (canonical cm along the surface) of the fade in from the face oval. */
+    readonly edgeFadeCm: 1;
+    /** Clamp on the relative light level that scales synthetic lobes and glints. */
+    readonly maxLightLevel: 2;
+    /** View-space key light, used while the light fit is not confident. */
+    readonly keyLight: Vec3;
+    /** Light-fit confidence (`|b| / a`) under which the key light is used. */
+    readonly lightConfidenceMin: 0.15;
+    /** Half-width of the blend between the key light and the fitted light. */
+    readonly lightConfidenceBlend: 0.03;
+    /** Half-width (canonical cm) of the left/right blend across the face's midline. */
+    readonly sideBlendCm: 0.15;
+    /** `dot(normal, viewDir)` where the facing fade starts and where it is full. */
+    readonly facingMin: 0;
+    readonly facingFull: 0.25;
+    /** Output below this (amount and highlight) is discarded. */
+    readonly discardBelow: number;
+}>;
+/**
+ * The `skinMap` mip the local low-pass reads (`uSkinLod`) for a probe of
+ * `probeSize`² texels: the mip that is `lowpassTexels` wide.
+ */
+export declare const makeupSkinLod: (probeSize: number) => number;
+/** Time constants (seconds) of the probe's skin references. */
+export declare const MAKEUP_SKIN_TIME_CONSTANTS: Readonly<{
+    /** `Rf`, the current light, and the per-texel skin map. */
+    readonly fast: 0.25;
+    /** `Rs`, the person's skin under the settled light. */
+    readonly slow: 4;
+}>;
+/** The per-finish highlight model. Roughness maps to a Blinn-Phong exponent `2 / r² − 2`. */
+export declare const MAKEUP_FINISH_MODEL: Readonly<{
+    readonly satin: {
+        readonly cameraHighlight: 0.35;
+        readonly roughness: 0.6;
+        readonly lobe: 0.15;
+    };
+    readonly gloss: {
+        readonly cameraHighlight: 1;
+        readonly cameraHighlightShine: 1.5;
+        readonly roughness: 0.12;
+        readonly lobe: 0.8;
+        readonly fresnel: 0.25;
+        readonly f0: 0.04;
+    };
+    /**
+     * The body scales with coverage: the diffuse colour is multiplied by
+     * `mix(1, metallic.diffuse, coverage)` and the reflected environment by
+     * coverage, so a sheer metallic is the sheer filter plus the lobe, Fresnel
+     * and camera highlights.
+     */
+    readonly metallic: {
+        readonly diffuse: 0.45;
+        readonly environment: 0.55;
+        readonly roughness: 0.35;
+        readonly lobe: 0.9;
+    };
+    /**
+     * Opacity from which the mask-scaled terms (gloss highlights, glitter
+     * flakes) are at full strength. Below it they fade out with opacity, so
+     * opacity 0 shows nothing.
+     */
+    readonly maskTermsFullOpacity: 0.1;
+    /** Sparkle tint when `sparkleColor` is "" : `mix(white, shade, tintMix)`. */
+    readonly sparkleTintMix: 0.5;
+}>;
+/** Flake (shimmer and glitter) model. Sizes are diameters; cells are diameter × `cellScale`. */
+export declare const MAKEUP_FLAKES: Readonly<{
+    readonly shimmer: {
+        readonly cellScale: 1.5;
+        readonly kappa: 20;
+        readonly sharpness: 24;
+        readonly gain: 8;
+        readonly hueJitter: 0;
+    };
+    readonly glitter: {
+        readonly cellScale: 2;
+        readonly kappa: 8;
+        readonly sharpness: 60;
+        readonly gain: 3;
+        readonly hueJitter: 0.35;
+        readonly body: 0.6;
+    };
+    /** Flake diameter (px) from which a flake starts to resolve, and from which it is fully resolved. */
+    readonly resolveStartPx: 0.75;
+    readonly resolveFullPx: 1.5;
+    /** Glitter density on the low quality tier (shimmer drops to its smooth expected value). */
+    readonly lowQualityGlitterDensity: 0.5;
+    /** Offset that keeps hashed cell ids positive. */
+    readonly cellOffset: 32768;
+}>;
+/** Auto-shade recipes (`shade: "auto"`): what the shader derives from the person. */
+export declare const MAKEUP_AUTO_SHADE: Readonly<{
+    readonly lips: {
+        readonly saturation: 1.2;
+        readonly value: 0.7;
+    };
+    readonly blush: {
+        readonly rose: Vec3;
+        readonly mix: 0.55;
+        readonly value: 0.92;
+    };
+    readonly contour: {
+        readonly saturation: 0.85;
+        readonly value: 0.62;
+    };
+    readonly highlighter: {
+        readonly warm: Vec3;
+        readonly mix: 0.3;
+        readonly value: 1.6;
+    };
+}>;
+/** Linear luminance (`makeupLuma`). */
+export declare const makeupLuma: (c: Vec3) => number;
+/** `mix(vec3(lum), c, amount)`: saturation scale. */
+export declare const makeupSaturation: (c: Vec3, amount: number) => MVec3;
+/** Linear → sRGB (three.js `sRGBTransferOETF`, the canvas output). Negative input clamps to 0. */
+export declare const encodeSrgb: (c: Vec3) => MVec3;
+/** sRGB → linear (three.js `sRGBTransferEOTF`, what an sRGB texture decodes to). */
+export declare const decodeSrgb: (c: Vec3) => MVec3;
+/** `1 − exp(−dt / τ)`: the probe's ConstantAlpha blend factor for an EMA with time constant τ. */
+export declare const makeupEmaFactor: (dt: number, tau: number) => number;
+/** One `skinMap` texel (or a mip's average of texels). */
+export type MakeupSkinTexel = readonly [number, number, number, number];
+/**
+ * Encodes skin colour `c` (linear) with weight `w` as the probe writes it:
+ * premultiplied `(c·w, w)`, or on the RGBA8 fallback (`sqrt`) `(w·√c, w)`.
+ * The square root is taken before premultiplying, so a mip's average still
+ * decodes to the weighted skin: `(Σw·√c / Σw)²`.
+ */
+export declare const encodeMakeupSkinTexel: (c: Vec3, w: number, sqrt?: boolean) => MakeupSkinTexel;
+/** The skin colour of a `skinMap` texel or mip: `rgb / a`, squared on the RGBA8 fallback. */
+export declare const decodeMakeupSkinTexel: (texel: MakeupSkinTexel, sqrt?: boolean) => MVec3;
+/** Raw probe inputs for one fragment. */
+export type MakeupSkinInput = {
+    /** C: the linear camera colour at the un-warped surface point. */
+    camera: Vec3;
+    /** Rs from the probe stats. */
+    skinSlow: Vec3;
+    /** Rf from the probe stats. */
+    skinFast: Vec3;
+    /** The skin map at the low-pass mip (`uSkinLod`), as `encodeMakeupSkinTexel` writes it. */
+    lowpass: MakeupSkinTexel;
+    /**
+     * The skin map `lowpassCoarseLods` mips above, read where the low-pass has
+     * no skin (lips, eyes, brows). Omitted: no data there either.
+     */
+    lowpassCoarse?: MakeupSkinTexel;
+    /** 0 until the probe has data, then 1. */
+    ready: number;
+    /** The RGBA8 fallback: rgb holds `w·√c` (`uSkinSqrt`). */
+    sqrt?: boolean;
+};
+/** The resolved skin references. */
+export type MakeupSkin = {
+    camera: Vec3;
+    /** Rs, or the camera itself while the probe is not ready (paint shows at once, flat). */
+    skinSlow: Vec3;
+    /** Rf, or the camera while not ready. */
+    skinFast: Vec3;
+    /**
+     * L, the local low-pass; where it has no skin, a coarser mip of it, then
+     * Rf; the camera while not ready.
+     */
+    skinLocal: Vec3;
+    /** The ready weight actually used (0 also when Rs is black). */
+    ready: number;
+};
+export declare const resolveMakeupSkin: (input: MakeupSkinInput) => MakeupSkin;
+/** The parts of the GLSL `MakeupSample` the shading and finish math read. */
+export type MakeupSample = MakeupSkin & {
+    /** The person's own lip colour (probe), or the region colour while not ready. */
+    lip: Vec3;
+    /** The person's own brow-hair colour (probe), or the region colour while not ready. */
+    brow: Vec3;
+    /** Rest position, canonical cm. */
+    rest: Vec3;
+    /** Unit normal of the rest-space facet under the pixel (sign free). */
+    facet: Vec3;
+    /** Pixel footprint on the surface, canonical cm. */
+    pixelCm: number;
+    /** Live metric normal, view space, unit, outward. */
+    normal: Vec3;
+    /** Rest normal × pose, view space, unit: flakes hang off it. */
+    flakeNormal: Vec3;
+    /** The head frame's +Y in view space, unit. */
+    headUp: Vec3;
+    /** Surface → eye, view space, unit. */
+    viewDir: Vec3;
+    /** Light direction, view space, unit (fitted, or the key light). */
+    light: Vec3;
+    /** side × edge × facing × presence. */
+    fade: number;
+};
+/**
+ * The light to shade with: the fitted direction, blended to the key light as
+ * the fit's confidence drops under `lightConfidenceMin` (GLSL `makeupLightDirection`).
+ */
+export declare const makeupLightDirection: (fitted: Vec3, confidence: number) => MVec3;
+/**
+ * The person's-left weight of a rest point: 1 on the person's own left, 0 on
+ * their right, blended across the midline. `personLeftSign` is #298's
+ * `personLeftSign(mirrored)`: canonical +X is the person's left on an
+ * unmirrored feed and their right on the mirrored webcam.
+ */
+export declare const makeupPersonLeft: (restX: number, personLeftSign: number) => number;
+/** The `side` weight: `uSide = (leftOn, rightOn)` mixed by the person's-left weight. */
+export declare const makeupSideWeight: (restX: number, personLeftSign: number, side: readonly [leftOn: number, rightOn: number]) => number;
+/** The fade in from the face oval: S1's `edge` attribute (cm from the oval) over `edgeFadeCm`. */
+export declare const makeupEdgeFade: (edgeCm: number) => number;
+/** The facing fade from the live normal and the view direction. */
+export declare const makeupFacing: (normal: Vec3, viewDir: Vec3) => number;
+/** The light terms of one fragment (GLSL `MakeupLight`). */
+export type MakeupLightTerms = {
+    /** S = lum(C) / lum(Rs): all the light here, relative to the settled skin. */
+    ratio: number;
+    /** lum(L) / lum(Rs): the light on this region without the skin's own shine. */
+    local: number;
+    /** Sd: S with the shine clipped above `local · (1 + clip)`. */
+    diffuse: number;
+    /** Hcam: the real highlight on the skin. */
+    highlight: number;
+    /** Light-colour tint (the cast of a change in light colour), per channel. */
+    lightTint: MVec3;
+};
+/** `x` unchanged up to `knee`, then compressed toward `knee · (1 + clip)` (hard at clip 0). */
+export declare const makeupSoftClip: (x: number, knee: number, clip: number) => number;
+/** The soft-clip headroom of a finish: none for matte. */
+export declare const makeupClipFor: (finish: MakeupShadingFinish) => 0 | 0.15;
+export declare const makeupLighting: (skin: MakeupSkin, clip: number) => MakeupLightTerms;
+/**
+ * The diffuse colour of the product (GLSL `makeupDiffuse`):
+ * - opaque `P · Sd · lightTint`: the shade under this light, relative to the person's skin;
+ * - sheer `C · P / max(max(P), lum(Rs))`: the person's own colour filtered by the
+ *   shade (a Multiply relative to the skin, capped so it never lightens);
+ * - mixed by `coverage`. Matte filters the clipped camera; metallic scales by
+ *   `mix(1, 0.45, coverage)`, so a sheer metallic is still only a filter.
+ */
+export declare const makeupDiffuse: (skin: MakeupSkin, light: MakeupLightTerms, color: Vec3, coverage: number, finish: MakeupShadingFinish) => MVec3;
+/** The shade a region with `shade: "auto"` derives from the person (GLSL `makeupAutoShade`). */
+export declare const makeupAutoShade: (sample: Pick<MakeupSample, "skinSlow" | "skinLocal" | "lip" | "brow">, mode: MakeupAutoShade, color: Vec3) => MVec3;
+/** PCG3D (Jarzynski & Olano 2020): the shader's integer cell hash, bit-exact. */
+export declare const makeupPcg3d: (x0: number, y0: number, z0: number) => MVec3;
+/** Rotates a colour's hue by `angle` radians around the grey axis. */
+export declare const makeupHueRotate: (c: Vec3, angle: number) => MVec3;
+/** Expected flake coverage of the surface: density × sphere volume / cell volume (Delesse). */
+export declare const makeupFlakeVolume: (density: number, cellScale: number) => number;
+/**
+ * The mean glint `exp(s · (n_f·h − 1))` over flake normals drawn from a
+ * von Mises–Fisher distribution of concentration κ around `n` (closed form).
+ */
+export declare const makeupFlakeGlintMean: (n: Vec3, h: Vec3, kappa: number, sharpness: number) => number;
+export type MakeupFlakeParams = {
+    /** Flake diameter, canonical cm (`sparkleSize` mm / 10). */
+    diameter: number;
+    /** Cell edge / flake diameter (≥ 1). */
+    cellScale: number;
+    /** Probability that a cell holds a flake, 0..1. */
+    density: number;
+    /** Concentration of flake normals around the surface normal. */
+    kappa: number;
+    /** Glint lobe sharpness. */
+    sharpness: number;
+    /** Hue jitter amplitude, radians. */
+    hueJitter: number;
+    /** 1 = resolve flakes; 0 = always their smooth expected value. */
+    quality: number;
+};
+/** What the flakes add at one pixel (GLSL `MakeupFlakes`). */
+export type MakeupFlakeSample = {
+    /** Fraction of the pixel covered by flakes. */
+    cover: number;
+    /** Coverage-weighted glint. */
+    glint: number;
+    /** The flake tint (hue-jittered when a flake is resolved). */
+    tint: MVec3;
+    /** 0 = expected value only, 1 = fully resolved. */
+    resolved: number;
+};
+/**
+ * Flakes hashed on 3D cells of the rest position, so they stick to the skin.
+ * A flake is a sphere inside its cell; the surface (the rest-space facet)
+ * slices it into a disc whose edge ramp integrates to exactly the disc's
+ * area. Flakes under `resolveFullPx` fade to their expected value, so the
+ * mean energy is the same at every pixel size (GLSL `makeupFlakes`).
+ */
+export declare const makeupFlakes: (p: Vec3, facet: Vec3, n: Vec3, up: Vec3, h: Vec3, pixelCm: number, params: MakeupFlakeParams, tint: Vec3) => MakeupFlakeSample;
+/** Region settings the finish reads (the shader's uniforms). */
+export type MakeupFinishParams = {
+    finish: MakeupShadingFinish;
+    opacity: number;
+    coverage: number;
+    shine: number;
+    /** Linear flake colour; `null` derives it from the shade (`sparkleColor: ""`). */
+    sparkleColor: Vec3 | null;
+    sparkleDensity: number;
+    /** Flake diameter, mm. */
+    sparkleSize: number;
+    /** 1 on the high and medium tiers, 0 on low. */
+    sparkleQuality: number;
+};
+/** One layer of product, before the output operator (GLSL `MakeupLayer`). */
+export type MakeupLayer = {
+    diffuse: MVec3;
+    amount: number;
+    highlight: MVec3;
+};
+/** Blinn-Phong lobe with a peak of 1, gated to the lit side (GLSL `makeupLobe`). */
+export declare const makeupLobe: (n: Vec3, h: Vec3, l: Vec3, roughness: number) => number;
+/** Schlick Fresnel. */
+export declare const makeupFresnel: (nv: number, f0: number) => number;
+/** The flake tint: `sparkleColor`, or `mix(white, shade, sparkleTintMix)`. */
+export declare const makeupSparkleTint: (color: Vec3, sparkleColor: Vec3 | null) => MVec3;
+/** The flake parameters a finish uses (GLSL builds the same inline). */
+export declare const makeupFlakeParamsFor: (finish: "shimmer" | "glitter", params: Pick<MakeupFinishParams, "sparkleDensity" | "sparkleSize" | "sparkleQuality">) => MakeupFlakeParams;
+/**
+ * One region's product at one fragment (GLSL `makeupFinish`). `mask` is the
+ * region's shape (0..1); the sample's `fade` applies on top. Pigment scales
+ * with `opacity`; gloss highlights and glitter flakes scale with the mask,
+ * so they keep their strength at low opacity, and fade out only below
+ * `maskTermsFullOpacity` (opacity 0 shows nothing).
+ */
+export declare const makeupFinishLayer: (sample: MakeupSample, color: Vec3, mask: number, params: MakeupFinishParams) => MakeupLayer;
+/**
+ * The output operator (GLSL `makeupOutput`): premultiplied
+ * `(amount · enc(D) + enc(base + H) − enc(base), amount)` with
+ * `base = mix(C, D, amount)`, drawn with `MAKEUP_BLENDING` (One,
+ * OneMinusSrcAlpha). `null` where the shader discards.
+ */
+export declare const makeupOutput: (camera: Vec3, layer: MakeupLayer) => [number, number, number, number] | null;
+/** Premultiplied-over blending of an output onto an encoded destination, clamped like a UNORM target. */
+export declare const makeupComposite: (destination: Vec3, output: readonly [number, number, number, number] | null) => MVec3;
+export {};

package/dist/face-atlas/shapes.d.ts

@@ -0,0 +1,86 @@
+import { Vec3 } from './shading';
+/**
+ * Analytic makeup shapes (FACE-1): soft tapered capsules in the canonical
+ * head frame (cm, +X toward landmark 263, +Y up, +Z out of the face),
+ * evaluated per fragment on the interpolated rest position, so nothing is
+ * baked. A blob is a capsule whose ends meet; an elongated or tapered one
+ * gives anisotropic, Gaussian-like blush, contour lines and highlight blobs.
+ *
+ * Shapes are authored on the canonical −X half (landmark 33's side) and the
+ * rest point is folded onto it (`x → −|x|`), so every shape is mirror-
+ * symmetric; which sides show is the `uSide` weight (the person's own sides).
+ * This file is the TypeScript mirror of `MAKEUP_GLSL.shapes` (tests, region
+ * triangle selection) plus the CPU helpers that place capsules on the face.
+ */
+/** Most capsules one region draws (`uShapeStart` / `uShapeEnd` / `uShapeWeight` length). */
+export declare const MAKEUP_SHAPE_MAX = 8;
+/** Softness floor of the edge profile: `softness` 0 is still antialiased over ±5 % of the radius. */
+export declare const MAKEUP_SHAPE_SOFTNESS_MIN = 0.05;
+/** A tapered capsule: segment `a → b` (cm) with radius `ra` at `a` and `rb` at `b`, scaled by `weight`. */
+export type MakeupCapsule = {
+    a: Vec3;
+    b: Vec3;
+    ra: number;
+    rb: number;
+    /** 0..1: the capsule's strength in the union. */
+    weight: number;
+};
+/**
+ * Capsules packed as the shader reads them: `start` / `end` hold
+ * `[x, y, z, radius]` per capsule, `weight` one value per capsule, `count`
+ * the capsules in use. The arrays keep their identity (uniform values).
+ */
+export type MakeupShapePrimitives = {
+    count: number;
+    start: Float32Array;
+    end: Float32Array;
+    weight: Float32Array;
+};
+export declare const createMakeupShapePrimitives: () => MakeupShapePrimitives;
+/** Packs capsules into `out` (unused slots zeroed). More than `MAKEUP_SHAPE_MAX` throws. */
+export declare const packMakeupShapePrimitives: (capsules: readonly MakeupCapsule[], out?: MakeupShapePrimitives) => MakeupShapePrimitives;
+/**
+ * The edge profile at `x` = distance / radius: 1 inside, 0.5 on the radius,
+ * 0 from `1 + softness` out (a C¹ bump with compact support, so the shape
+ * ends exactly and triangles outside it can be skipped).
+ */
+export declare const makeupShapeProfile: (x: number, softness: number) => number;
+/**
+ * Distance (cm) from `p` to the capsule's segment and the capsule's radius at
+ * the closest point, written to `out` as `[distance, radius]`.
+ */
+export declare const makeupCapsuleDistance: (p: Vec3, a: Vec3, b: Vec3, ra: number, rb: number, out?: [number, number]) => [number, number];
+/**
+ * The shape mask at a rest point (GLSL `makeupShapeMask`): the point folded
+ * onto the −X half, each capsule's profile times its weight, combined as a
+ * soft union `1 − Π(1 − wᵢ·mᵢ)` (overlaps blend, no creases).
+ */
+export declare const evaluateMakeupShapeMask: (primitives: MakeupShapePrimitives, softness: number, rest: Vec3) => number;
+/**
+ * The eye guard (GLSL `makeupEyeGuard`): keeps a shape off the lash line and
+ * lids by the `eyeRing` attribute (edge hops from the lash ring: 0 on the
+ * lash line, 3 on the under-eye row and the brow's lower edge). `[start,
+ * full]`; `start >= full` turns it off.
+ */
+export declare const makeupEyeGuard: (eyeRing: number, guard: readonly [number, number]) => number;
+/**
+ * The lip guard (GLSL `makeupLipGuard`): fades a shape to 0 on the outer lip
+ * line by the `lipEdge` attribute (0 on the outer lip ring, 1 one triangle
+ * row off the lips), so a shape the lips' own triangles leave out never ends
+ * at a hard edge there. `guard` is the `lipEdge` where the shape is full;
+ * 0 turns it off.
+ */
+export declare const makeupLipGuard: (lipEdge: number, guard: number) => number;
+/**
+ * The face surface under a frontal point: `(x, y)` in canonical cm projected
+ * along Z onto the front-most atlas triangle, so a shape placed by its
+ * frontal outline sits on the skin. Outside the face's frontal outline it
+ * takes the z of the nearest landmark. Writes and returns `out`.
+ */
+export declare const faceAtlasSurfacePoint: (x: number, y: number, out?: [number, number, number]) => [number, number, number];
+/**
+ * Triangle indices (into `FACE_ATLAS_TRIANGLES`, sorted) of `from` with at
+ * least one corner where `covered(vertex)` holds: the triangles a region's
+ * mesh needs to draw everything its shapes can reach.
+ */
+export declare const selectFaceAtlasTriangles: (from: ArrayLike<number>, covered: (vertex: number) => boolean) => Uint16Array;

package/dist/face-atlas/sides.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sides on the face atlas (#298): every `side` setting means the PERSON'S
+ * OWN side on every feed. Static atlas data is keyed by canonical axis
+ * (`negX` / `posX`: landmark 33's half / landmark 263's half); a feed turns
+ * the person's side into a canonical half with `personLeftSign(mirrored)`:
+ * +1 (unmirrored: rear camera, image, video) puts the person's left on +X,
+ * −1 (the mirrored webcam) puts it on −X. Shaders do the same per fragment
+ * (`MAKEUP_GLSL.common`: `uSide` mixed by `vMakeupRest.x * uPersonLeftSign`).
+ */
+/** Which of the person's own sides a sided layer paints. */
+export type FaceAtlasSide = "both" | "left" | "right";
+/**
+ * `uSide`: `[leftOn, rightOn]` for a side setting, in the person's own sides
+ * (the shader turns them into canonical halves with `uPersonLeftSign`).
+ */
+export declare const makeupSideWeights: (side: FaceAtlasSide) => readonly [left: number, right: number];
+/**
+ * The canonical halves a side setting paints on a feed: `{ negX, posX }`
+ * weights (1 painted, 0 not). On an unmirrored feed the person's left is
+ * +X; on the mirrored webcam it is −X.
+ */
+export declare const faceAtlasSideHalves: (side: FaceAtlasSide, mirrored: boolean) => {
+    negX: number;
+    posX: number;
+};
+/**
+ * Whether art painted on the face atlas as on an unmirrored photo (image-left
+ * = the person's right) samples `(1 − u, v)` on this feed: only on a mirrored
+ * feed, so each side of the art lands on the person's own side. The atlas is
+ * symmetric to 0.001, so the flip is exact (`mirrorFaceAtlasUv`).
+ */
+export declare const faceAtlasDesignFlipU: (mirrored: boolean) => boolean;
+/**
+ * The blink blendshape of each canonical half. MediaPipe names blendshapes
+ * as the image shows them, so `eyeBlinkLeft` is landmark 263's eye (+X) on
+ * every feed: blink gating stays on mesh sides, never on the person's side.
+ */
+export declare const FACE_ATLAS_BLINK_MORPHS: Readonly<{
+    readonly negX: "eyeBlinkRight";
+    readonly posX: "eyeBlinkLeft";
+}>;

package/dist/face-atlas/skinMask.d.ts

@@ -0,0 +1,35 @@
+import { DataTexture } from 'three';
+import { FaceAtlasMask } from './masks';
+/**
+ * About how many cm of face one unit of atlas UV spans: the median over the
+ * skin's edges (3D length over UV length; p10 21, p90 30, larger toward the
+ * sides of the face, which the atlas foreshortens). For sizing blurs and
+ * erosions in cm.
+ */
+export declare const FACE_ATLAS_CM_PER_UV = 23.5;
+/** How the skin mask is cut back from the features it borders. */
+export declare const FACE_SKIN_MASK: {
+    /** The region painted: the face without lips, brows, eye and mouth fills and nostrils. */
+    readonly region: "skin";
+    /**
+     * Erosion, cm: the mask is 0 on and just inside the region's edge (the
+     * lash line, the brows, the lips, the face oval) and reaches 1 about this
+     * far inside it, so lashes, liner, brow hairs, lip colour and hair at the
+     * hairline stay out of skin statistics.
+     */
+    readonly erodeCm: 0.5;
+};
+/**
+ * The skin of the face atlas as a coverage mask, cut back from its edges by
+ * `FACE_SKIN_MASK.erodeCm`: 0 outside, on and just inside the edge of the
+ * `skin` region, rising smoothly to 1 inside. `origin` as in
+ * `createFaceAtlasMask` (default `"top"`, an image's row order).
+ */
+export declare const createFaceSkinMask: (size?: number, origin?: "top" | "bottom") => FaceAtlasMask;
+/**
+ * The eroded skin mask (`createFaceSkinMask`) as a single-channel
+ * `THREE.DataTexture` sampled at atlas UVs (read `.r`; rows stored from
+ * `v = 0`). One shared texture per size, made on first use: never dispose it
+ * (16 KB at 128²).
+ */
+export declare const getFaceSkinMaskTexture: (size?: number) => DataTexture;