@visutry/tryon-core 0.2.0

package/dist/pose/GlassesPoseSolver.js

@@ -0,0 +1,299 @@
+import { clamp, clamp01, distance3D, DEG2RAD } from "../utils/math.js";
+import { CoordinateSystem } from "../coordinate/CoordinateSystem.js";
+/**
+ * Calibration constant: maps millimetres to render-world units.
+ *
+ * The render-world is defined so that the full frame height maps to 1.0 unit and
+ * the x-axis is scaled by aspect ratio. We assume a representative adult face
+ * height of ~200 mm, hence 1 mm ≈ 0.005 render-world units. This is a documented
+ * calibration anchor; the manifest `defaultScale` and `GlassesFittingConfig`
+ * fine-tune per model.
+ */
+export const MM_TO_RENDER_WORLD = 1 / 200;
+/** Default fitting configuration. */
+export const DEFAULT_FITTING_CONFIG = {
+    scaleMultiplier: 1,
+    positionOffset: { x: 0, y: 0, z: 0 },
+    rotationOffset: { x: 0, y: 0, z: 0 },
+    useTransformationMatrix: false,
+    fitBy: "eyeOuterDistance",
+    verticalAnchor: "noseBridge",
+    depthStrategy: "noseTip",
+};
+/**
+ * Converts a normalized `NormalizedFaceResult` into a `GlassesPose` that the
+ * renderer can apply directly to a glasses model.
+ *
+ * Coordinate contract:
+ *  - Face landmarks arrive in *normalized-image* space (origin top-left, y down).
+ *  - The solver converts them to *render-world* space (origin centre, y up,
+ *    x scaled by aspect ratio, 1.0 unit = frame height) before computing.
+ *  - The renderer must use the same render-world convention so that
+ *    `GlassesPose.position` lands the model on the face.
+ *
+ * Solve pipeline (spec §15.5):
+ *   1. eye centre line → roll
+ *   2. outer-eye distance → scale
+ *   3. noseBridge / eyeLine → position
+ *   4. yaw / pitch (or matrix) → 3D rotation
+ *   5. manifest defaults + config offsets applied
+ */
+export class GlassesPoseSolver {
+    /**
+     * Solve the glasses pose for a single face result.
+     */
+    solve(input) {
+        const { face, asset, config } = input;
+        const cfg = { ...DEFAULT_FITTING_CONFIG, ...config };
+        const aspect = this.deriveAspect(face);
+        const sem = face.landmarks.semantic;
+        // Visibility / confidence gate (tryon-level, spec §11.4).
+        const visibility = this.assessVisibility(face);
+        if (!visibility.visible) {
+            return {
+                position: { x: 0, y: 0, z: 0 },
+                rotation: { x: 0, y: 0, z: 0 },
+                scale: { x: asset.fitting.defaultScale, y: asset.fitting.defaultScale, z: asset.fitting.defaultScale },
+                visible: false,
+                confidence: visibility.confidence,
+                reason: visibility.reason,
+            };
+        }
+        // --- 1. Roll from the eye centre line --------------------------------
+        const roll = this.computeRoll(sem, aspect);
+        // --- 2. Scale from the chosen fit metric -----------------------------
+        const scale = this.computeScale(face, asset, cfg, aspect);
+        // --- 3. Position -----------------------------------------------------
+        const position = this.computePosition(sem, asset, cfg, aspect, face);
+        // --- 4. Rotation (yaw/pitch + roll) ----------------------------------
+        const rotation = this.computeRotation(face, cfg, roll);
+        // --- 5. Apply manifest defaults & config offsets ---------------------
+        const finalPosition = this.applyPositionOffsets(position, asset, cfg);
+        const finalRotation = this.applyRotationOffsets(rotation, asset, cfg);
+        const finalScale = this.clampScale(scale, asset, cfg);
+        return {
+            position: finalPosition,
+            rotation: finalRotation,
+            scale: { x: finalScale, y: finalScale, z: finalScale },
+            visible: true,
+            confidence: clamp01(visibility.confidence * 0.7 + face.pose.confidence * 0.3),
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Roll
+    // -----------------------------------------------------------------------
+    computeRoll(sem, aspect) {
+        const le = sem.leftEyeCenter ?? sem.leftEyeOuter;
+        const re = sem.rightEyeCenter ?? sem.rightEyeOuter;
+        if (!le || !re)
+            return 0;
+        const leRW = CoordinateSystem.normalizedToRenderWorld(le, aspect);
+        const reRW = CoordinateSystem.normalizedToRenderWorld(re, aspect);
+        // Angle of the eye line in render-world (y up). Rotating the glasses by
+        // this angle around Z keeps it parallel to the eyes.
+        return Math.atan2(reRW.y - leRW.y, reRW.x - leRW.x);
+    }
+    // -----------------------------------------------------------------------
+    // Scale
+    // -----------------------------------------------------------------------
+    computeScale(face, asset, cfg, aspect) {
+        const sem = face.landmarks.semantic;
+        const fitMetric = this.fitMetricRW(sem, cfg.fitBy ?? "eyeOuterDistance", aspect);
+        const modelWidthMm = this.modelFrameWidthMm(asset);
+        const modelWidthRW = modelWidthMm * MM_TO_RENDER_WORLD;
+        if (fitMetric <= 1e-6 || modelWidthRW <= 1e-6) {
+            return asset.fitting.defaultScale;
+        }
+        const rawScale = fitMetric / modelWidthRW;
+        const scale = rawScale * asset.fitting.defaultScale * (cfg.scaleMultiplier ?? 1);
+        return scale;
+    }
+    /**
+     * The face-side width in render-world units used to fit the glasses. The model
+     * frame width should match the outer-eye span, so we use that directly.
+     */
+    fitMetricRW(sem, fitBy, aspect) {
+        const toRW = (p) => (p ? CoordinateSystem.normalizedToRenderWorld(p, aspect) : undefined);
+        let a;
+        let b;
+        switch (fitBy) {
+            case "eyeOuterDistance":
+                a = toRW(sem.leftEyeOuter);
+                b = toRW(sem.rightEyeOuter);
+                break;
+            case "eyeCenterDistance":
+                a = toRW(sem.leftEyeCenter);
+                b = toRW(sem.rightEyeCenter);
+                break;
+            case "faceWidth":
+                a = toRW(sem.leftCheek);
+                b = toRW(sem.rightCheek);
+                break;
+        }
+        if (!a || !b) {
+            // Fallback to whatever eye points exist.
+            a = toRW(sem.leftEyeOuter ?? sem.leftEyeCenter);
+            b = toRW(sem.rightEyeOuter ?? sem.rightEyeCenter);
+        }
+        if (!a || !b)
+            return 0;
+        return distance3D(a, b);
+    }
+    modelFrameWidthMm(asset) {
+        const unitFactor = asset.coordinateSystem.unit === "millimeter"
+            ? 1
+            : asset.coordinateSystem.unit === "centimeter"
+                ? 10
+                : 1000;
+        return asset.dimensions.frameWidthMm * unitFactor;
+    }
+    // -----------------------------------------------------------------------
+    // Position
+    // -----------------------------------------------------------------------
+    computePosition(sem, _asset, cfg, aspect, face) {
+        const anchor = cfg.verticalAnchor ?? "noseBridge";
+        let baseNorm;
+        switch (anchor) {
+            case "noseBridge":
+                baseNorm = sem.noseBridge ?? sem.eyesCenter;
+                break;
+            case "eyeLine":
+                baseNorm = sem.eyesCenter;
+                break;
+            case "browLine":
+                baseNorm =
+                    sem.leftBrowCenter && sem.rightBrowCenter
+                        ? {
+                            x: (sem.leftBrowCenter.x + sem.rightBrowCenter.x) / 2,
+                            y: (sem.leftBrowCenter.y + sem.rightBrowCenter.y) / 2,
+                            z: (sem.leftBrowCenter.z + sem.rightBrowCenter.z) / 2,
+                        }
+                        : sem.eyesCenter;
+                break;
+        }
+        if (!baseNorm) {
+            return { x: 0, y: 0, z: 0 };
+        }
+        const rw = CoordinateSystem.normalizedToRenderWorld(baseNorm, aspect);
+        // Depth strategy.
+        let z = 0;
+        const depth = cfg.depthStrategy ?? "noseTip";
+        if (depth === "noseTip" && sem.noseTip) {
+            // The nose tip z (relative to face centre) pushes the glasses forward.
+            z = (sem.noseTip.z ?? 0) * 0.5;
+        }
+        else if (depth === "matrix" && face.pose.matrix) {
+            z = face.pose.matrix[14] ?? 0; // translation z of a column-major 4x4
+        }
+        return { x: rw.x, y: rw.y, z };
+    }
+    // -----------------------------------------------------------------------
+    // Rotation
+    // -----------------------------------------------------------------------
+    computeRotation(face, cfg, roll) {
+        if (cfg.useTransformationMatrix && face.pose.matrix) {
+            const euler = decomposeMatrixToEuler(face.pose.matrix);
+            // Replace roll with the eye-line-derived value (more stable than matrix roll).
+            return { x: euler.x, y: euler.y, z: roll };
+        }
+        return { x: face.pose.pitch, y: face.pose.yaw, z: roll };
+    }
+    // -----------------------------------------------------------------------
+    // Offsets & clamping
+    // -----------------------------------------------------------------------
+    applyPositionOffsets(position, asset, cfg) {
+        const off = asset.fitting.defaultOffset;
+        const cfgOff = cfg.positionOffset ?? { x: 0, y: 0, z: 0 };
+        return {
+            x: position.x + off.x + cfgOff.x,
+            y: position.y + off.y + cfgOff.y,
+            z: position.z + off.z + cfgOff.z,
+        };
+    }
+    applyRotationOffsets(rotation, asset, cfg) {
+        const off = asset.fitting.defaultRotation;
+        const cfgOff = cfg.rotationOffset ?? { x: 0, y: 0, z: 0 };
+        return {
+            x: rotation.x + off.x + cfgOff.x,
+            y: rotation.y + off.y + cfgOff.y,
+            z: rotation.z + off.z + cfgOff.z,
+        };
+    }
+    clampScale(scale, asset, cfg) {
+        const min = asset.fitting.minScale ?? 0.1;
+        const max = asset.fitting.maxScale ?? 5;
+        const mult = cfg.scaleMultiplier ?? 1;
+        return clamp(scale / (mult || 1) * mult, min, max);
+    }
+    // -----------------------------------------------------------------------
+    // Visibility
+    // -----------------------------------------------------------------------
+    assessVisibility(face) {
+        const sem = face.landmarks.semantic;
+        const hasEyesCenter = !!sem.eyesCenter;
+        const hasNose = !!sem.noseBridge || !!sem.noseTip;
+        const confidence = face.pose.confidence;
+        const bboxWidth = face.bbox.width;
+        if (!hasEyesCenter) {
+            return { visible: false, confidence, reason: "MISSING_EYES_CENTER" };
+        }
+        if (!hasNose) {
+            return { visible: false, confidence, reason: "MISSING_NOSE_REFERENCE" };
+        }
+        if (confidence < 0.55) {
+            return { visible: false, confidence, reason: "LOW_TRACKER_CONFIDENCE" };
+        }
+        if (bboxWidth < 0.18) {
+            return { visible: false, confidence, reason: "FACE_TOO_SMALL" };
+        }
+        return { visible: true, confidence };
+    }
+    // -----------------------------------------------------------------------
+    deriveAspect(face) {
+        // Without an explicit frame size we fall back to a 4:3 aspect, which is the
+        // default camera resolution. The web adapter passes the real aspect via the
+        // renderer setup; the solver stays robust to a missing value.
+        const b = face.bbox;
+        if (b.width > 0 && b.height > 0) {
+            return b.width / b.height;
+        }
+        return 4 / 3;
+    }
+}
+/**
+ * Decompose a column-major 4x4 rigid transformation matrix into Euler angles
+ * (radians) in YXZ order. Used when `useTransformationMatrix` is enabled.
+ */
+export function decomposeMatrixToEuler(matrix) {
+    // Column-major: matrix[0..3] = column 0, [4..7] = column 1, etc.
+    // Rotation sub-matrix:
+    //   | m0 m4 m8 |
+    //   | m1 m5 m9 |
+    //   | m2 m6 m10|
+    const m0 = matrix[0] ?? 1;
+    const m1 = matrix[1] ?? 0;
+    const m2 = matrix[2] ?? 0;
+    const m5 = matrix[5] ?? 1;
+    const m6 = matrix[6] ?? 0;
+    const m9 = matrix[9] ?? 0;
+    const m10 = matrix[10] ?? 1;
+    // YXZ extraction.
+    const y = Math.asin(clamp(-m2, -1, 1));
+    let x;
+    let z;
+    if (Math.abs(m2) < 0.99999) {
+        x = Math.atan2(m6, m10);
+        z = Math.atan2(m1, m0);
+    }
+    else {
+        // Gimbal lock fallback.
+        x = Math.atan2(-m9, m5);
+        z = 0;
+    }
+    return { x, y, z };
+}
+/** Convert degrees to radians for manifest authors who think in degrees. */
+export function degreesToRadians(deg) {
+    return deg * DEG2RAD;
+}
+//# sourceMappingURL=GlassesPoseSolver.js.map

package/dist/pose/GlassesPoseSolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlassesPoseSolver.js","sourceRoot":"","sources":["../../src/pose/GlassesPoseSolver.ts"],"names":[],"mappings":"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"}

package/dist/privacy/PrivacyGuard.d.ts

@@ -0,0 +1,44 @@
+import type { PrivacyConfig, SDKError } from "../types/index.js";
+/** Safe default privacy configuration (spec §19.2). */
+export declare const DEFAULT_PRIVACY_CONFIG: PrivacyConfig;
+/**
+ * Enforces the SDK privacy contract.
+ *
+ * The guard is the single source of truth for what may leave the device. By
+ * default everything stays on-device; analytics is off; snapshots require
+ * explicit opt-in. The guard exposes intent-revealing methods so the rest of
+ * the SDK never has to reason about the raw config flags.
+ */
+export declare class PrivacyGuard {
+    private config;
+    constructor(config?: Partial<PrivacyConfig>);
+    /** Re-apply a (partial) configuration. */
+    configure(config: Partial<PrivacyConfig>): void;
+    get config_(): PrivacyConfig;
+    /** Whether image / video frames may be sent to a server. Always false in v1.0. */
+    canUploadFrames(): boolean;
+    /** Whether face landmarks may leave the device. Always false in v1.0. */
+    canUploadLandmarks(): boolean;
+    /** Whether face geometry / metrics may leave the device. Always false in v1.0. */
+    canUploadFaceGeometry(): boolean;
+    /** Whether the business layer may request a snapshot export. */
+    canExportSnapshot(): boolean;
+    /** Whether any analytics payload may be emitted. */
+    canEmitAnalytics(): boolean;
+    /** Whether performance metrics may be reported (only if analytics enabled). */
+    canReportPerformance(): boolean;
+    /** Whether diagnostic (non-image) data may be reported. */
+    canReportDiagnostics(): boolean;
+    /**
+     * Guarded executor: runs `action` only if `predicate` allows it, otherwise
+     * returns a privacy-violation error. Centralises the "ask permission" pattern.
+     */
+    guard<T>(predicate: () => boolean, action: () => T, errorCode?: SDKError["code"], message?: string): T;
+    /**
+     * Returns a redaction summary for diagnostic logging: lists which data
+     * categories are allowed to leave the device. Never includes actual data.
+     */
+    redactionSummary(): Record<string, boolean>;
+    private assertDefaults;
+}
+//# sourceMappingURL=PrivacyGuard.d.ts.map

package/dist/privacy/PrivacyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivacyGuard.d.ts","sourceRoot":"","sources":["../../src/privacy/PrivacyGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEjE,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,EAAE,aAKpC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAK/C,0CAA0C;IAC1C,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAK/C,IAAI,OAAO,IAAI,aAAa,CAE3B;IAED,kFAAkF;IAClF,eAAe,IAAI,OAAO;IAK1B,yEAAyE;IACzE,kBAAkB,IAAI,OAAO;IAI7B,kFAAkF;IAClF,qBAAqB,IAAI,OAAO;IAIhC,gEAAgE;IAChE,iBAAiB,IAAI,OAAO;IAI5B,oDAAoD;IACpD,gBAAgB,IAAI,OAAO;IAI3B,+EAA+E;IAC/E,oBAAoB,IAAI,OAAO;IAM/B,2DAA2D;IAC3D,oBAAoB,IAAI,OAAO;IAK/B;;;OAGG;IACH,KAAK,CAAC,CAAC,EACL,SAAS,EAAE,MAAM,OAAO,EACxB,MAAM,EAAE,MAAM,CAAC,EACf,SAAS,GAAE,QAAQ,CAAC,MAAM,CAAa,EACvC,OAAO,SAAqC,GAC3C,CAAC;IAYJ;;;OAGG;IACH,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAW3C,OAAO,CAAC,cAAc;CAMvB"}

package/dist/privacy/PrivacyGuard.js

@@ -0,0 +1,105 @@
+/** Safe default privacy configuration (spec §19.2). */
+export const DEFAULT_PRIVACY_CONFIG = {
+    processOnDeviceOnly: true,
+    allowSnapshotExport: true,
+    allowAnalytics: false,
+    analyticsLevel: "none",
+};
+/**
+ * Enforces the SDK privacy contract.
+ *
+ * The guard is the single source of truth for what may leave the device. By
+ * default everything stays on-device; analytics is off; snapshots require
+ * explicit opt-in. The guard exposes intent-revealing methods so the rest of
+ * the SDK never has to reason about the raw config flags.
+ */
+export class PrivacyGuard {
+    constructor(config = {}) {
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.config = { ...DEFAULT_PRIVACY_CONFIG, ...config };
+        this.assertDefaults();
+    }
+    /** Re-apply a (partial) configuration. */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+        this.assertDefaults();
+    }
+    get config_() {
+        return { ...this.config };
+    }
+    /** Whether image / video frames may be sent to a server. Always false in v1.0. */
+    canUploadFrames() {
+        // On-device-only is the hard contract; uploads are never permitted.
+        return false;
+    }
+    /** Whether face landmarks may leave the device. Always false in v1.0. */
+    canUploadLandmarks() {
+        return false;
+    }
+    /** Whether face geometry / metrics may leave the device. Always false in v1.0. */
+    canUploadFaceGeometry() {
+        return false;
+    }
+    /** Whether the business layer may request a snapshot export. */
+    canExportSnapshot() {
+        return this.config.allowSnapshotExport ?? false;
+    }
+    /** Whether any analytics payload may be emitted. */
+    canEmitAnalytics() {
+        return this.config.allowAnalytics === true && this.config.analyticsLevel !== "none";
+    }
+    /** Whether performance metrics may be reported (only if analytics enabled). */
+    canReportPerformance() {
+        if (!this.canEmitAnalytics())
+            return false;
+        const level = this.config.analyticsLevel ?? "none";
+        return level === "performance" || level === "diagnostic";
+    }
+    /** Whether diagnostic (non-image) data may be reported. */
+    canReportDiagnostics() {
+        if (!this.canEmitAnalytics())
+            return false;
+        return this.config.analyticsLevel === "diagnostic";
+    }
+    /**
+     * Guarded executor: runs `action` only if `predicate` allows it, otherwise
+     * returns a privacy-violation error. Centralises the "ask permission" pattern.
+     */
+    guard(predicate, action, errorCode = "UNKNOWN", message = "Action blocked by privacy policy") {
+        if (!predicate()) {
+            const error = {
+                code: errorCode,
+                message,
+                recoverable: false,
+            };
+            throw error;
+        }
+        return action();
+    }
+    /**
+     * Returns a redaction summary for diagnostic logging: lists which data
+     * categories are allowed to leave the device. Never includes actual data.
+     */
+    redactionSummary() {
+        return {
+            frames: this.canUploadFrames(),
+            landmarks: this.canUploadLandmarks(),
+            faceGeometry: this.canUploadFaceGeometry(),
+            snapshot: this.canExportSnapshot(),
+            performance: this.canReportPerformance(),
+            diagnostics: this.canReportDiagnostics(),
+        };
+    }
+    assertDefaults() {
+        // The on-device-only flag is a hard requirement; it cannot be disabled.
+        if (!this.config.processOnDeviceOnly) {
+            this.config.processOnDeviceOnly = true;
+        }
+    }
+}
+//# sourceMappingURL=PrivacyGuard.js.map

package/dist/privacy/PrivacyGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivacyGuard.js","sourceRoot":"","sources":["../../src/privacy/PrivacyGuard.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,mBAAmB,EAAE,IAAI;IACzB,mBAAmB,EAAE,IAAI;IACzB,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,MAAM;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IAGvB,YAAY,SAAiC,EAAE;QAFvC;;;;;WAAsB;QAG5B,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,sBAAsB,EAAE,GAAG,MAAM,EAAE,CAAC;QACvD,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED,0CAA0C;IAC1C,SAAS,CAAC,MAA8B;QACtC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;QAC5C,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,kFAAkF;IAClF,eAAe;QACb,oEAAoE;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yEAAyE;IACzE,kBAAkB;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kFAAkF;IAClF,qBAAqB;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gEAAgE;IAChE,iBAAiB;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,KAAK,CAAC;IAClD,CAAC;IAED,oDAAoD;IACpD,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC;IACtF,CAAC;IAED,+EAA+E;IAC/E,oBAAoB;QAClB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC;QACnD,OAAO,KAAK,KAAK,aAAa,IAAI,KAAK,KAAK,YAAY,CAAC;IAC3D,CAAC;IAED,2DAA2D;IAC3D,oBAAoB;QAClB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YAAE,OAAO,KAAK,CAAC;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,YAAY,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,KAAK,CACH,SAAwB,EACxB,MAAe,EACf,YAA8B,SAAS,EACvC,OAAO,GAAG,kCAAkC;QAE5C,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;YACjB,MAAM,KAAK,GAAa;gBACtB,IAAI,EAAE,SAAS;gBACf,OAAO;gBACP,WAAW,EAAE,KAAK;aACnB,CAAC;YACF,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,MAAM,EAAE,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE;YAC9B,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE;YACpC,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE;YAC1C,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE;YAClC,WAAW,EAAE,IAAI,CAAC,oBAAoB,EAAE;YACxC,WAAW,EAAE,IAAI,CAAC,oBAAoB,EAAE;SACzC,CAAC;IACJ,CAAC;IAEO,cAAc;QACpB,wEAAwE;QACxE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,CAAC,mBAAmB,GAAG,IAAI,CAAC;QACzC,CAAC;IACH,CAAC;CACF"}

package/dist/quality/QualityGate.d.ts

@@ -0,0 +1,22 @@
+import type { QualityGateInput, QualityGateResult } from "../types/index.js";
+/**
+ * Decides whether a face result is good enough for analysis, try-on, or
+ * snapshot, emitting structured warnings when it is not (spec §11).
+ *
+ * The gate is stateless and pure: given the same input it always returns the
+ * same verdict, which makes it trivially testable.
+ */
+export declare class QualityGate {
+    evaluate(input: QualityGateInput): QualityGateResult;
+    /**
+     * Photo quality checks adapted from visutry: eye line tilt, facial symmetry,
+     * and face span. These help reject poor-quality selfies before analysis.
+     */
+    private checkPhotoQuality;
+    /**
+     * Composite quality score in [0,1] blending confidence, frontality,
+     * stability, lighting and occlusion (when available).
+     */
+    private computeScore;
+}
+//# sourceMappingURL=QualityGate.d.ts.map

package/dist/quality/QualityGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QualityGate.d.ts","sourceRoot":"","sources":["../../src/quality/QualityGate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,gBAAgB,EAEhB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AA2C3B;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB;IAsEpD;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA2CzB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAUrB"}

package/dist/quality/QualityGate.js

@@ -0,0 +1,161 @@
+import { FaceSemanticMapper } from "../face/FaceSemanticMapper.js";
+import { clamp01 } from "../utils/math.js";
+const THRESHOLDS = {
+    analysis: {
+        minConfidence: 0.75,
+        minFrontalScore: 0.75,
+        minStabilityScore: 0.7,
+        minBboxWidth: 0.25,
+        requiredSemanticPoints: [
+            "leftEyeCenter",
+            "rightEyeCenter",
+            "noseBridge",
+            "chin",
+            "leftCheek",
+            "rightCheek",
+            "leftJaw",
+            "rightJaw",
+        ],
+    },
+    tryon: {
+        minConfidence: 0.55,
+        minBboxWidth: 0.18,
+        requiredSemanticPoints: ["eyesCenter"],
+        anyOfSemanticPoints: [["noseBridge", "noseTip"]],
+    },
+    snapshot: {
+        minConfidence: 0.6,
+        minBboxWidth: 0.1,
+        requiredSemanticPoints: ["eyesCenter"],
+    },
+};
+/**
+ * Decides whether a face result is good enough for analysis, try-on, or
+ * snapshot, emitting structured warnings when it is not (spec §11).
+ *
+ * The gate is stateless and pure: given the same input it always returns the
+ * same verdict, which makes it trivially testable.
+ */
+export class QualityGate {
+    evaluate(input) {
+        const { face, mode } = input;
+        const thresholds = THRESHOLDS[mode];
+        const warnings = [];
+        const sem = face.landmarks.semantic;
+        // --- Confidence -------------------------------------------------------
+        if (face.quality.confidence < thresholds.minConfidence) {
+            warnings.push("LOW_CONFIDENCE");
+        }
+        // --- Frontality -------------------------------------------------------
+        if (thresholds.minFrontalScore !== undefined && face.quality.frontalScore < thresholds.minFrontalScore) {
+            warnings.push("NOT_FRONTAL");
+        }
+        // --- Stability --------------------------------------------------------
+        if (thresholds.minStabilityScore !== undefined && face.quality.stabilityScore < thresholds.minStabilityScore) {
+            warnings.push("UNSTABLE");
+        }
+        // --- Bounding box size ------------------------------------------------
+        if (face.bbox.width < thresholds.minBboxWidth) {
+            warnings.push("FACE_TOO_SMALL");
+        }
+        if (face.bbox.width > 0.7) {
+            warnings.push("FACE_TOO_CLOSE");
+        }
+        // --- Semantic point presence -----------------------------------------
+        if (thresholds.requiredSemanticPoints) {
+            const missing = FaceSemanticMapper.countMissing(sem, thresholds.requiredSemanticPoints).missing;
+            if (missing.length > 0)
+                warnings.push("MISSING_KEY_POINTS");
+        }
+        if (thresholds.anyOfSemanticPoints) {
+            for (const group of thresholds.anyOfSemanticPoints) {
+                const any = group.some((k) => sem[k]);
+                if (!any) {
+                    if (!warnings.includes("MISSING_KEY_POINTS"))
+                        warnings.push("MISSING_KEY_POINTS");
+                }
+            }
+        }
+        // --- Lighting / occlusion passthrough --------------------------------
+        if (face.quality.lightingScore !== undefined && face.quality.lightingScore < 0.4) {
+            warnings.push("LOW_LIGHT");
+        }
+        if (face.quality.occlusionScore !== undefined && face.quality.occlusionScore < 0.4) {
+            warnings.push("OCCLUDED");
+        }
+        // --- visutry additions: photo quality checks (analysis mode only) ----
+        if (mode === "analysis") {
+            const photoWarnings = this.checkPhotoQuality(sem);
+            for (const w of photoWarnings) {
+                if (!warnings.includes(w))
+                    warnings.push(w);
+            }
+        }
+        // --- Snapshot-specific: faceVisible ----------------------------------
+        if (mode === "snapshot" && !face.quality.faceVisible) {
+            warnings.push("LOW_CONFIDENCE");
+        }
+        const score = this.computeScore(face, mode);
+        const passed = warnings.length === 0 && face.quality.faceVisible;
+        return { passed, score, warnings };
+    }
+    /**
+     * Photo quality checks adapted from visutry: eye line tilt, facial symmetry,
+     * and face span. These help reject poor-quality selfies before analysis.
+     */
+    checkPhotoQuality(sem) {
+        const warnings = [];
+        const MAX_TILT_DEG = 15;
+        const MAX_SYMMETRY_OFFSET = 0.14;
+        const MIN_FACE_SPAN = 0.16;
+        // Eye line tilt
+        if (sem.leftEyeOuter && sem.rightEyeOuter) {
+            const dx = sem.rightEyeOuter.x - sem.leftEyeOuter.x;
+            const dy = sem.rightEyeOuter.y - sem.leftEyeOuter.y;
+            if (Math.abs(dx) > 1e-6) {
+                const tiltDeg = Math.abs(Math.atan2(dy, dx) * (180 / Math.PI));
+                if (tiltDeg > MAX_TILT_DEG) {
+                    warnings.push("EXCESSIVE_TILT");
+                }
+            }
+        }
+        // Symmetry offset: nose bridge deviation from face center
+        if (sem.noseBridge && sem.leftFace && sem.rightFace) {
+            const faceWidth = Math.abs(sem.rightFace.x - sem.leftFace.x);
+            if (faceWidth > 1e-6) {
+                const faceCenterX = (sem.leftFace.x + sem.rightFace.x) / 2;
+                const offset = Math.abs(sem.noseBridge.x - faceCenterX) / faceWidth;
+                if (offset > MAX_SYMMETRY_OFFSET) {
+                    warnings.push("ASYMMETRIC_FACE");
+                }
+            }
+        }
+        // Face span: bounding box max dimension
+        if (sem.leftFace && sem.rightFace && sem.foreheadCenter && sem.chin) {
+            const w = Math.abs(sem.rightFace.x - sem.leftFace.x);
+            const h = Math.abs(sem.chin.y - sem.foreheadCenter.y);
+            const span = Math.max(w, h);
+            if (span < MIN_FACE_SPAN) {
+                warnings.push("FACE_TOO_SMALL");
+            }
+        }
+        return warnings;
+    }
+    /**
+     * Composite quality score in [0,1] blending confidence, frontality,
+     * stability, lighting and occlusion (when available).
+     */
+    computeScore(face, mode) {
+        const q = face.quality;
+        let score = q.confidence * 0.4 + q.frontalScore * 0.3 + q.stabilityScore * 0.3;
+        if (q.lightingScore !== undefined)
+            score = score * 0.8 + q.lightingScore * 0.2;
+        if (q.occlusionScore !== undefined)
+            score = score * 0.9 + q.occlusionScore * 0.1;
+        // Mode weighting: analysis is stricter.
+        if (mode === "analysis")
+            score *= 0.95;
+        return clamp01(score);
+    }
+}
+//# sourceMappingURL=QualityGate.js.map