@visutry/tryon-core 0.2.0

package/dist/face/FaceSemanticMapper.d.ts

@@ -0,0 +1,54 @@
+import type { FaceResultSource, FaceSemanticPoints, Point3D } from "../types/index.js";
+/**
+ * Mapping from a semantic point name to the index in the raw landmark array.
+ * Adapters supply the index map appropriate for their tracker; the core ships a
+ * default MediaPipe Face Landmarker map.
+ */
+export type SemanticIndexMap = Partial<Record<keyof FaceSemanticPoints, number>>;
+/**
+ * Default MediaPipe Face Landmarker (468/478 point topology) index map, as
+ * specified in the SDK spec §10.1.
+ */
+export declare const MEDIAPIPE_SEMANTIC_INDEX_MAP: SemanticIndexMap;
+export interface FaceSemanticMapperOptions {
+    indexMap?: SemanticIndexMap;
+    /** When true, derive eye centers / eyes center from outer+inner corners. Default true. */
+    deriveCenters?: boolean;
+}
+/**
+ * Maps raw tracker landmarks onto the stable `FaceSemanticPoints` contract.
+ *
+ * This class is intentionally side-effect free and tracker-agnostic: it only
+ * needs an index map describing where each semantic point lives in the raw
+ * array. The web adapter passes the MediaPipe map; the WeChat adapter passes a
+ * custom map or relies on direct construction.
+ */
+export declare class FaceSemanticMapper {
+    private readonly indexMap;
+    private readonly deriveCenters;
+    constructor(options?: FaceSemanticMapperOptions);
+    /**
+     * Build a `FaceSemanticPoints` from a raw normalized landmark array.
+     * Missing indices or undefined landmarks are silently skipped — downstream
+     * consumers must tolerate optional points.
+     */
+    map(landmarks: Point3D[]): FaceSemanticPoints;
+    /**
+     * Derive leftEyeCenter, rightEyeCenter and eyesCenter from the outer/inner
+     * eye corners when they are available. These derived points are the backbone
+     * of the glasses pose solver and face metrics.
+     */
+    private deriveEyeCenters;
+    /**
+     * Count how many of the *required* semantic points (for analysis) are present.
+     * Used by the quality gate to emit `MISSING_KEY_POINTS`.
+     */
+    static countMissing(semantic: FaceSemanticPoints, required?: (keyof FaceSemanticPoints)[]): {
+        missing: string[];
+        present: number;
+        total: number;
+    };
+    /** Convenience factory bound to a specific source's default map. */
+    static forSource(source: FaceResultSource): FaceSemanticMapper;
+}
+//# sourceMappingURL=FaceSemanticMapper.d.ts.map

package/dist/face/FaceSemanticMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaceSemanticMapper.d.ts","sourceRoot":"","sources":["../../src/face/FaceSemanticMapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGvF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,gBAsB1C,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,0FAA0F;IAC1F,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAE5B,OAAO,GAAE,yBAA8B;IAKnD;;;;OAIG;IACH,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,kBAAkB;IAuB7C;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;;OAGG;IACH,MAAM,CAAC,YAAY,CACjB,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,GAAE,CAAC,MAAM,kBAAkB,CAAC,EASnC,GACA;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAYxD,oEAAoE;IACpE,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB;CAO/D"}

package/dist/face/FaceSemanticMapper.js

@@ -0,0 +1,129 @@
+import { midpoint } from "../utils/math.js";
+/**
+ * Default MediaPipe Face Landmarker (468/478 point topology) index map, as
+ * specified in the SDK spec §10.1.
+ */
+export const MEDIAPIPE_SEMANTIC_INDEX_MAP = {
+    leftEyeOuter: 33,
+    leftEyeInner: 133,
+    rightEyeInner: 362,
+    rightEyeOuter: 263,
+    noseBridge: 168,
+    noseTip: 1,
+    leftBrowCenter: 105,
+    rightBrowCenter: 334,
+    foreheadCenter: 10,
+    chin: 152,
+    leftCheek: 123,
+    rightCheek: 352,
+    leftJaw: 172,
+    rightJaw: 397,
+    // visutry additions — used for richer face shape classification
+    leftFace: 234,
+    rightFace: 454,
+    leftForehead: 103,
+    rightForehead: 332,
+    noseLeft: 98,
+    noseRight: 327,
+};
+/**
+ * Maps raw tracker landmarks onto the stable `FaceSemanticPoints` contract.
+ *
+ * This class is intentionally side-effect free and tracker-agnostic: it only
+ * needs an index map describing where each semantic point lives in the raw
+ * array. The web adapter passes the MediaPipe map; the WeChat adapter passes a
+ * custom map or relies on direct construction.
+ */
+export class FaceSemanticMapper {
+    constructor(options = {}) {
+        Object.defineProperty(this, "indexMap", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "deriveCenters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.indexMap = options.indexMap ?? MEDIAPIPE_SEMANTIC_INDEX_MAP;
+        this.deriveCenters = options.deriveCenters ?? true;
+    }
+    /**
+     * Build a `FaceSemanticPoints` from a raw normalized landmark array.
+     * Missing indices or undefined landmarks are silently skipped — downstream
+     * consumers must tolerate optional points.
+     */
+    map(landmarks) {
+        const semantic = {};
+        for (const key of Object.keys(this.indexMap)) {
+            const idx = this.indexMap[key];
+            if (idx === undefined)
+                continue;
+            const pt = landmarks[idx];
+            if (pt && typeof pt.x === "number" && typeof pt.y === "number") {
+                semantic[key] = {
+                    x: pt.x,
+                    y: pt.y,
+                    z: pt.z ?? 0,
+                };
+            }
+        }
+        if (this.deriveCenters) {
+            this.deriveEyeCenters(semantic);
+        }
+        return semantic;
+    }
+    /**
+     * Derive leftEyeCenter, rightEyeCenter and eyesCenter from the outer/inner
+     * eye corners when they are available. These derived points are the backbone
+     * of the glasses pose solver and face metrics.
+     */
+    deriveEyeCenters(semantic) {
+        if (!semantic.leftEyeCenter && semantic.leftEyeOuter && semantic.leftEyeInner) {
+            semantic.leftEyeCenter = midpoint(semantic.leftEyeOuter, semantic.leftEyeInner);
+        }
+        if (!semantic.rightEyeCenter && semantic.rightEyeInner && semantic.rightEyeOuter) {
+            semantic.rightEyeCenter = midpoint(semantic.rightEyeInner, semantic.rightEyeOuter);
+        }
+        if (!semantic.eyesCenter && semantic.leftEyeCenter && semantic.rightEyeCenter) {
+            semantic.eyesCenter = midpoint(semantic.leftEyeCenter, semantic.rightEyeCenter);
+        }
+    }
+    /**
+     * Count how many of the *required* semantic points (for analysis) are present.
+     * Used by the quality gate to emit `MISSING_KEY_POINTS`.
+     */
+    static countMissing(semantic, required = [
+        "leftEyeCenter",
+        "rightEyeCenter",
+        "noseBridge",
+        "chin",
+        "leftCheek",
+        "rightCheek",
+        "leftJaw",
+        "rightJaw",
+    ]) {
+        const missing = [];
+        for (const key of required) {
+            if (!semantic[key])
+                missing.push(key);
+        }
+        return {
+            missing,
+            present: required.length - missing.length,
+            total: required.length,
+        };
+    }
+    /** Convenience factory bound to a specific source's default map. */
+    static forSource(source) {
+        if (source === "mediapipe") {
+            return new FaceSemanticMapper({ indexMap: MEDIAPIPE_SEMANTIC_INDEX_MAP });
+        }
+        // wechat-vk and custom callers must supply their own map at construction.
+        return new FaceSemanticMapper({ indexMap: {} });
+    }
+}
+//# sourceMappingURL=FaceSemanticMapper.js.map

package/dist/face/FaceSemanticMapper.js.map

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

package/dist/face/FaceShapeScorer.d.ts

@@ -0,0 +1,35 @@
+import type { FaceMetrics, FaceQualityWarning, FaceShapeResult, NormalizedFaceResult } from "../types/index.js";
+import { FaceMetricsCalculator } from "./FaceMetricsCalculator.js";
+export declare const FACE_SHAPE_SCORER_VERSION = "0.2.0";
+/**
+ * Scores face shapes from geometric metrics.
+ *
+ * v0.2.0: Exact port of visutry's classifyFaceGeometry algorithm.
+ * Uses if/else integer scoring on 2D ratios — not bell/softmax.
+ * This ensures numerical equivalence with visutry's main site.
+ *
+ * Future enhancements (bell functions, softmax, chinType, multi-frame)
+ * can be layered on top of this known-good baseline.
+ */
+export declare class FaceShapeScorer {
+    private readonly metricsCalculator;
+    constructor(metricsCalculator?: FaceMetricsCalculator);
+    /**
+     * Score a single face result.
+     */
+    score(face: NormalizedFaceResult): FaceShapeResult;
+    /**
+     * Score from pre-aggregated metrics.
+     */
+    scoreFromMetrics(metrics: FaceMetrics, warnings?: FaceQualityWarning[]): FaceShapeResult;
+    /**
+     * Multi-frame scoring: aggregate metrics first, then score.
+     */
+    scoreFrames(frames: NormalizedFaceResult[]): FaceShapeResult;
+    /**
+     * Get raw integer scores for all 7 shapes — same as visutry's scoring.
+     */
+    private getAllScores;
+    private unknownResult;
+}
+//# sourceMappingURL=FaceShapeScorer.d.ts.map

package/dist/face/FaceShapeScorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaceShapeScorer.d.ts","sourceRoot":"","sources":["../../src/face/FaceShapeScorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAGlB,eAAe,EACf,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAyHjD;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;gBAE9C,iBAAiB,CAAC,EAAE,qBAAqB;IAIrD;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe;IAKlD;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,GAAE,kBAAkB,EAAO,GAAG,eAAe;IA6E5F;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,eAAe;IAa5D;;OAEG;IACH,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,aAAa;CA0BtB"}

package/dist/face/FaceShapeScorer.js

@@ -0,0 +1,265 @@
+import { FaceMetricsCalculator } from "./FaceMetricsCalculator.js";
+export const FACE_SHAPE_SCORER_VERSION = "0.2.0";
+/**
+ * All canonical face shapes, in the same order as visutry's CANONICAL_FACE_SHAPES.
+ */
+const CANONICAL_SHAPES = [
+    "oval",
+    "round",
+    "square",
+    "heart",
+    "diamond",
+    "oblong",
+    "triangle",
+];
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function round(value, digits = 3) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+/**
+ * Build geometry signals — exact port of visutry's buildGeometrySignals().
+ */
+function buildGeometrySignals(shape, ratios) {
+    const lengthSignal = ratios.faceAspectRatio >= 1.42
+        ? "Longer vertical face proportion"
+        : ratios.faceAspectRatio < 1.2
+            ? "Compact face length relative to width"
+            : "Balanced face length-to-width ratio";
+    const jawSignal = ratios.jawToCheekWidth >= 0.94
+        ? "Jaw width is close to cheekbone width"
+        : ratios.jawToCheekWidth <= 0.78
+            ? "Jawline tapers below the cheekbones"
+            : "Jawline has moderate taper";
+    const upperSignal = ratios.foreheadToCheekWidth >= 0.9
+        ? "Forehead width is close to cheekbone width"
+        : "Cheekbones read wider than the upper face";
+    const shapeSignal = shape.charAt(0).toUpperCase() + shape.slice(1) + " shape supported by measured proportions";
+    return [shapeSignal, lengthSignal, jawSignal, upperSignal];
+}
+/**
+ * classifyFaceGeometry — exact port of visutry's classifyFaceGeometry().
+ *
+ * Uses integer if/else scoring on three key ratios:
+ *   - faceAspectRatio (H/W, 2D)
+ *   - jawToCheekWidth
+ *   - foreheadToCheekWidth
+ *
+ * Confidence: clamp(0.56 + best.score * 0.065 + margin * 0.035, 0.58, 0.93)
+ */
+function classifyFaceGeometry(ratios) {
+    const scores = {
+        round: 0,
+        square: 0,
+        oval: 0,
+        heart: 0,
+        diamond: 0,
+        oblong: 0,
+        triangle: 0,
+    };
+    const { faceAspectRatio, jawToCheekWidth, foreheadToCheekWidth } = ratios;
+    // --- Exact replication of visutry's scoring rules ---
+    if (faceAspectRatio >= 1.42)
+        scores.oblong += 4;
+    if (faceAspectRatio >= 1.27 && faceAspectRatio < 1.42)
+        scores.oval += 3;
+    if (faceAspectRatio < 1.2)
+        scores.round += 2;
+    if (faceAspectRatio < 1.18 && jawToCheekWidth >= 0.86)
+        scores.square += 3;
+    if (jawToCheekWidth >= 0.92 && foreheadToCheekWidth >= 0.9)
+        scores.square += 3;
+    if (jawToCheekWidth < 0.76 && foreheadToCheekWidth >= 0.84)
+        scores.heart += 4;
+    if (jawToCheekWidth < 0.78 && foreheadToCheekWidth < 0.84)
+        scores.diamond += 4;
+    if (jawToCheekWidth > 0.98 && foreheadToCheekWidth < 0.88)
+        scores.triangle += 4;
+    if (jawToCheekWidth >= 0.78 && jawToCheekWidth <= 0.9 && faceAspectRatio >= 1.2) {
+        scores.oval += 2;
+    }
+    if (jawToCheekWidth >= 0.82 && jawToCheekWidth <= 0.94 && faceAspectRatio < 1.22) {
+        scores.round += 2;
+    }
+    // --- Rank candidates ---
+    const ranked = CANONICAL_SHAPES.map((shape) => ({ shape, score: scores[shape] })).sort((a, b) => b.score - a.score);
+    const best = ranked[0];
+    const second = ranked[1];
+    const confidence = clamp(0.56 + best.score * 0.065 + (best.score - second.score) * 0.035, 0.58, 0.93);
+    const alternatives = ranked
+        .slice(1, 3)
+        .filter((candidate) => candidate.score > 0)
+        .map((candidate) => candidate.shape);
+    return {
+        shape: best.shape,
+        alternatives,
+        confidence: round(confidence, 2),
+        signals: buildGeometrySignals(best.shape, ratios),
+    };
+}
+/**
+ * Scores face shapes from geometric metrics.
+ *
+ * v0.2.0: Exact port of visutry's classifyFaceGeometry algorithm.
+ * Uses if/else integer scoring on 2D ratios — not bell/softmax.
+ * This ensures numerical equivalence with visutry's main site.
+ *
+ * Future enhancements (bell functions, softmax, chinType, multi-frame)
+ * can be layered on top of this known-good baseline.
+ */
+export class FaceShapeScorer {
+    constructor(metricsCalculator) {
+        Object.defineProperty(this, "metricsCalculator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.metricsCalculator = metricsCalculator ?? new FaceMetricsCalculator();
+    }
+    /**
+     * Score a single face result.
+     */
+    score(face) {
+        const metrics = this.metricsCalculator.compute(face);
+        return this.scoreFromMetrics(metrics, face.quality.warnings);
+    }
+    /**
+     * Score from pre-aggregated metrics.
+     */
+    scoreFromMetrics(metrics, warnings = []) {
+        // Require visutry-compatible ratios for classification.
+        if (!metrics.visutry) {
+            return this.unknownResult(metrics, [...warnings, "MISSING_KEY_POINTS"]);
+        }
+        const v = metrics.visutry;
+        // --- Quality gates (exact match to visutry's analyzeFaceLandmarks) ---
+        const MAX_TILT = 15;
+        const MAX_SYMMETRY = 0.14;
+        const MIN_SPAN = 0.16;
+        const allWarnings = [...warnings];
+        // Face span check
+        if (metrics.faceSpan !== undefined && metrics.faceSpan < MIN_SPAN) {
+            allWarnings.push("FACE_TOO_SMALL");
+        }
+        // Tilt check — visutry rejects > 15° as unavailable
+        if (Math.abs(v.eyeLineTiltDeg) > MAX_TILT) {
+            allWarnings.push("EXCESSIVE_TILT");
+        }
+        // Symmetry check — visutry rejects > 0.14 as unavailable
+        if (v.symmetryOffset > MAX_SYMMETRY) {
+            allWarnings.push("ASYMMETRIC_FACE");
+        }
+        // If quality gates failed, return unknown
+        if (allWarnings.some((w) => w === "EXCESSIVE_TILT" || w === "ASYMMETRIC_FACE" || w === "FACE_TOO_SMALL")) {
+            return this.unknownResult(metrics, allWarnings);
+        }
+        // --- Classify using visutry's exact algorithm ---
+        const result = classifyFaceGeometry(v);
+        // --- Build candidates list ---
+        // visutry returns shape + alternatives; we also include all shapes with
+        // their integer scores as candidates for SDK consumers.
+        const scores = this.getAllScores(v);
+        const ranked = CANONICAL_SHAPES.map((shape) => ({
+            shape,
+            score: scores[shape],
+        })).sort((a, b) => b.score - a.score);
+        const maxScore = Math.max(...ranked.map((r) => r.score), 1);
+        const candidates = ranked.map((r) => ({
+            shape: r.shape,
+            score: round(r.score / maxScore, 3),
+            reasons: buildGeometrySignals(r.shape, v),
+        }));
+        // --- Soft warnings for borderline quality ---
+        if (Math.abs(v.eyeLineTiltDeg) > 8) {
+            if (!allWarnings.includes("EXCESSIVE_TILT")) {
+                allWarnings.push("EXCESSIVE_TILT");
+            }
+        }
+        if (v.symmetryOffset > 0.08) {
+            if (!allWarnings.includes("ASYMMETRIC_FACE")) {
+                allWarnings.push("ASYMMETRIC_FACE");
+            }
+        }
+        return {
+            primary: result.shape,
+            candidates,
+            confidence: result.confidence,
+            metrics,
+            warnings: allWarnings,
+            version: FACE_SHAPE_SCORER_VERSION,
+        };
+    }
+    /**
+     * Multi-frame scoring: aggregate metrics first, then score.
+     */
+    scoreFrames(frames) {
+        if (frames.length === 0) {
+            return this.unknownResult();
+        }
+        const metrics = this.metricsCalculator.aggregate(frames);
+        const warnings = frames[0].quality.warnings;
+        return this.scoreFromMetrics(metrics, warnings);
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Get raw integer scores for all 7 shapes — same as visutry's scoring.
+     */
+    getAllScores(v) {
+        const scores = {
+            round: 0, square: 0, oval: 0, heart: 0, diamond: 0, oblong: 0, triangle: 0,
+        };
+        const { faceAspectRatio, jawToCheekWidth, foreheadToCheekWidth } = v;
+        if (faceAspectRatio >= 1.42)
+            scores.oblong += 4;
+        if (faceAspectRatio >= 1.27 && faceAspectRatio < 1.42)
+            scores.oval += 3;
+        if (faceAspectRatio < 1.2)
+            scores.round += 2;
+        if (faceAspectRatio < 1.18 && jawToCheekWidth >= 0.86)
+            scores.square += 3;
+        if (jawToCheekWidth >= 0.92 && foreheadToCheekWidth >= 0.9)
+            scores.square += 3;
+        if (jawToCheekWidth < 0.76 && foreheadToCheekWidth >= 0.84)
+            scores.heart += 4;
+        if (jawToCheekWidth < 0.78 && foreheadToCheekWidth < 0.84)
+            scores.diamond += 4;
+        if (jawToCheekWidth > 0.98 && foreheadToCheekWidth < 0.88)
+            scores.triangle += 4;
+        if (jawToCheekWidth >= 0.78 && jawToCheekWidth <= 0.9 && faceAspectRatio >= 1.2) {
+            scores.oval += 2;
+        }
+        if (jawToCheekWidth >= 0.82 && jawToCheekWidth <= 0.94 && faceAspectRatio < 1.22) {
+            scores.round += 2;
+        }
+        return scores;
+    }
+    unknownResult(metrics, warnings = ["LOW_CONFIDENCE"]) {
+        return {
+            primary: "unknown",
+            candidates: [],
+            confidence: 0,
+            metrics: metrics ?? {
+                faceWidth: 0,
+                faceHeight: 0,
+                cheekboneWidth: 0,
+                jawWidth: 0,
+                eyeOuterDistance: 0,
+                eyeInnerDistance: 0,
+                eyeCenterDistance: 0,
+                noseBridgeToEyeLine: 0,
+                widthHeightRatio: 0,
+                jawCheekRatio: 0,
+                chinType: "unknown",
+                measurementQuality: 0,
+            },
+            warnings,
+            version: FACE_SHAPE_SCORER_VERSION,
+        };
+    }
+}
+//# sourceMappingURL=FaceShapeScorer.js.map

package/dist/face/FaceShapeScorer.js.map

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

package/dist/face/feature-extractor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Feature extraction for the logistic-regression classifier (spec §9.3).
+ *
+ * The feature vector is derived from `FaceMetrics` and must use exactly the
+ * same canonical order, missing-value strategy and preprocessing in both the
+ * Python training script and the TypeScript inference module. Any change to
+ * this file MUST bump `LOGREG_FEATURE_SCHEMA_VERSION` and trigger retraining.
+ */
+import type { FaceMetrics } from "../types/index.js";
+/**
+ * Feature schema version — must match the version baked into every exported
+ * model JSON. When the feature set changes (add/remove/reorder), bump this and
+ * retrain. See spec §9.3.
+ */
+export declare const LOGREG_FEATURE_SCHEMA_VERSION = "2.1.0";
+/**
+ * Canonical feature names in fixed order. The index in this array is the
+ * column index used in `weights`, `mean` and `std` arrays of the model JSON.
+ *
+ * Design rationale:
+ *  - Only scale-invariant, pose-robust ratios and curvatures are used.
+ *    Raw pixel widths/heights depend on image resolution and camera distance.
+ *  - `chinType` is ordinal-encoded: pointed (0) < rounded (1) < square (2).
+ *    `unknown` maps to the midpoint (0.5) so it does not bias the model.
+ *  - Missing optionals default to 0 (ratio neutral) — see `missingValueStrategy`
+ *    in the model JSON.
+ */
+export declare const LOGREG_FEATURE_NAMES: readonly ["faceWidthToHeight", "jawCheekRatio", "foreheadCheekRatio", "jawToEyeOuter", "eyeOuterToCheek", "noseBridgeRatio", "jawCurvature", "foreheadCurvature", "symmetryOffset", "smileIntensity", "chinTypeEncoded"];
+/** Number of features — convenience constant. */
+export declare const LOGREG_NUM_FEATURES: 11;
+/** Ordinal encoding for `chinType`. */
+export declare function encodeChinType(chinType: FaceMetrics["chinType"]): number;
+/**
+ * Extract the canonical feature vector from `FaceMetrics`.
+ *
+ * The returned array is in the exact order defined by `LOGREG_FEATURE_NAMES`.
+ * Missing optional fields default to 0 (ratios/curvatures) or 0.5 (chinType
+ * unknown). This matches the `missingValueStrategy: "zero"` declared in the
+ * model JSON.
+ *
+ * **This function is the single source of truth for feature order.** Both the
+ * TS inference module and the Python training script must replicate this
+ * exact extraction logic.
+ */
+export declare function extractFeatures(metrics: FaceMetrics): number[];
+//# sourceMappingURL=feature-extractor.d.ts.map

package/dist/face/feature-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-extractor.d.ts","sourceRoot":"","sources":["../../src/face/feature-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,UAAU,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,0NAYvB,CAAC;AAEX,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,IAA8B,CAAC;AAM/D,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,MAAM,CAaxE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CA4B9D"}

package/dist/face/feature-extractor.js

@@ -0,0 +1,106 @@
+/**
+ * Feature extraction for the logistic-regression classifier (spec §9.3).
+ *
+ * The feature vector is derived from `FaceMetrics` and must use exactly the
+ * same canonical order, missing-value strategy and preprocessing in both the
+ * Python training script and the TypeScript inference module. Any change to
+ * this file MUST bump `LOGREG_FEATURE_SCHEMA_VERSION` and trigger retraining.
+ */
+// ---------------------------------------------------------------------------
+// Feature schema
+// ---------------------------------------------------------------------------
+/**
+ * Feature schema version — must match the version baked into every exported
+ * model JSON. When the feature set changes (add/remove/reorder), bump this and
+ * retrain. See spec §9.3.
+ */
+export const LOGREG_FEATURE_SCHEMA_VERSION = "2.1.0";
+/**
+ * Canonical feature names in fixed order. The index in this array is the
+ * column index used in `weights`, `mean` and `std` arrays of the model JSON.
+ *
+ * Design rationale:
+ *  - Only scale-invariant, pose-robust ratios and curvatures are used.
+ *    Raw pixel widths/heights depend on image resolution and camera distance.
+ *  - `chinType` is ordinal-encoded: pointed (0) < rounded (1) < square (2).
+ *    `unknown` maps to the midpoint (0.5) so it does not bias the model.
+ *  - Missing optionals default to 0 (ratio neutral) — see `missingValueStrategy`
+ *    in the model JSON.
+ */
+export const LOGREG_FEATURE_NAMES = [
+    "faceWidthToHeight",
+    "jawCheekRatio",
+    "foreheadCheekRatio",
+    "jawToEyeOuter",
+    "eyeOuterToCheek",
+    "noseBridgeRatio",
+    "jawCurvature",
+    "foreheadCurvature",
+    "symmetryOffset",
+    "smileIntensity",
+    "chinTypeEncoded",
+];
+/** Number of features — convenience constant. */
+export const LOGREG_NUM_FEATURES = LOGREG_FEATURE_NAMES.length;
+// ---------------------------------------------------------------------------
+// chinType encoding
+// ---------------------------------------------------------------------------
+/** Ordinal encoding for `chinType`. */
+export function encodeChinType(chinType) {
+    switch (chinType) {
+        case "pointed":
+            return 0;
+        case "rounded":
+            return 1;
+        case "square":
+            return 2;
+        case "unknown":
+            return 0.5;
+        default:
+            return 0.5;
+    }
+}
+// ---------------------------------------------------------------------------
+// Feature extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract the canonical feature vector from `FaceMetrics`.
+ *
+ * The returned array is in the exact order defined by `LOGREG_FEATURE_NAMES`.
+ * Missing optional fields default to 0 (ratios/curvatures) or 0.5 (chinType
+ * unknown). This matches the `missingValueStrategy: "zero"` declared in the
+ * model JSON.
+ *
+ * **This function is the single source of truth for feature order.** Both the
+ * TS inference module and the Python training script must replicate this
+ * exact extraction logic.
+ */
+export function extractFeatures(metrics) {
+    const eyeOuter = metrics.eyeOuterDistance || 1e-6;
+    const cheek = metrics.cheekboneWidth || 1e-6;
+    return [
+        // 0: faceWidthToHeight (W/H)
+        metrics.faceWidthToHeight,
+        // 1: jawCheekRatio (jawWidth / cheekboneWidth)
+        metrics.jawCheekRatio,
+        // 2: foreheadCheekRatio (foreheadWidth / cheekboneWidth)
+        metrics.foreheadCheekRatio ?? 0,
+        // 3: jawToEyeOuter (jawWidth / eyeOuterDistance)
+        (metrics.jawWidth || 0) / eyeOuter,
+        // 4: eyeOuterToCheek (eyeOuterDistance / cheekboneWidth)
+        eyeOuter / cheek,
+        // 5: noseBridgeRatio (noseBridgeWidth / faceWidth)
+        metrics.noseBridgeRatio ?? 0,
+        // 6: jawCurvature
+        metrics.jawCurvature ?? 0,
+        // 7: foreheadCurvature
+        metrics.foreheadCurvature ?? 0,
+        // 8: symmetryOffset
+        metrics.symmetryOffset ?? 0,
+        // 9: smileIntensity
+        metrics.smileIntensity ?? 0,
+        // 10: chinTypeEncoded
+        encodeChinType(metrics.chinType),
+    ];
+}
+//# sourceMappingURL=feature-extractor.js.map