@simprints/simface-sdk 0.3.1 → 0.5.1

package/dist/services/face-quality.d.ts

@@ -0,0 +1,23 @@
+import type { FaceQualityResult } from '../types/index.js';
+export interface FaceBoundingBox {
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+}
+export interface FaceKeypoint {
+    x: number;
+    y: number;
+}
+export interface FaceDetectionSnapshot {
+    boundingBox?: FaceBoundingBox;
+    confidence: number;
+    keypoints: FaceKeypoint[];
+}
+interface FaceQualityInput {
+    width: number;
+    height: number;
+    detections: FaceDetectionSnapshot[];
+}
+export declare function evaluateFaceQuality(input: FaceQualityInput): FaceQualityResult;
+export {};

package/dist/services/face-quality.js

@@ -0,0 +1,136 @@
+const MIN_FACE_AREA_RATIO = 0.1;
+const MAX_FACE_AREA_RATIO = 0.42;
+const IDEAL_FACE_AREA_RATIO = 0.24;
+const CENTER_TOLERANCE_X = 0.14;
+const CENTER_TOLERANCE_Y = 0.18;
+const MAX_NOSE_OFFSET_RATIO = 0.12;
+const KEYPOINT_RIGHT_EYE = 0;
+const KEYPOINT_LEFT_EYE = 1;
+const KEYPOINT_NOSE = 2;
+export function evaluateFaceQuality(input) {
+    const { detections, width, height } = input;
+    if (detections.length === 0) {
+        return createQualityResult({
+            hasFace: false,
+            faceCount: 0,
+            confidence: 0,
+            captureScore: 0,
+            isCentered: false,
+            passesQualityChecks: false,
+            feedback: 'no-face',
+            message: 'No face detected. Center your face in the oval and look at the camera.',
+        });
+    }
+    if (detections.length > 1) {
+        return createQualityResult({
+            hasFace: true,
+            faceCount: detections.length,
+            confidence: detections[0]?.confidence ?? 0,
+            captureScore: 0,
+            isCentered: false,
+            passesQualityChecks: false,
+            feedback: 'multiple-faces',
+            message: 'Multiple faces detected. Make sure only one person is in view.',
+        });
+    }
+    const detection = detections[0];
+    const bbox = detection.boundingBox;
+    if (!bbox) {
+        return createQualityResult({
+            hasFace: true,
+            faceCount: 1,
+            confidence: detection.confidence,
+            captureScore: 0,
+            isCentered: false,
+            passesQualityChecks: false,
+            feedback: 'face-unclear',
+            message: 'Face detected, but the frame is unclear. Hold still and try again.',
+        });
+    }
+    const faceAreaRatio = (bbox.width * bbox.height) / (width * height);
+    if (faceAreaRatio < MIN_FACE_AREA_RATIO) {
+        return createFrameAdjustmentResult(detection.confidence, 'too-far', 'Move closer to the camera.');
+    }
+    if (faceAreaRatio > MAX_FACE_AREA_RATIO) {
+        return createFrameAdjustmentResult(detection.confidence, 'too-close', 'Move slightly farther away.');
+    }
+    const faceCenterX = (bbox.originX + bbox.width / 2) / width;
+    const faceCenterY = (bbox.originY + bbox.height / 2) / height;
+    if (faceCenterX < 0.5 - CENTER_TOLERANCE_X) {
+        return createFrameAdjustmentResult(detection.confidence, 'move-right', 'Move your face a little to the right.');
+    }
+    if (faceCenterX > 0.5 + CENTER_TOLERANCE_X) {
+        return createFrameAdjustmentResult(detection.confidence, 'move-left', 'Move your face a little to the left.');
+    }
+    if (faceCenterY < 0.5 - CENTER_TOLERANCE_Y) {
+        return createFrameAdjustmentResult(detection.confidence, 'move-down', 'Move your face slightly down.');
+    }
+    if (faceCenterY > 0.5 + CENTER_TOLERANCE_Y) {
+        return createFrameAdjustmentResult(detection.confidence, 'move-up', 'Move your face slightly up.');
+    }
+    const turnFeedback = detectTurnFeedback(detection.keypoints);
+    if (turnFeedback) {
+        return createFrameAdjustmentResult(detection.confidence, turnFeedback.feedback, turnFeedback.message);
+    }
+    return createQualityResult({
+        hasFace: true,
+        faceCount: 1,
+        confidence: detection.confidence,
+        captureScore: calculateCaptureScore(detection.confidence, faceCenterX, faceCenterY, faceAreaRatio),
+        isCentered: true,
+        passesQualityChecks: true,
+        feedback: 'good',
+        message: 'Hold still. Capturing automatically...',
+    });
+}
+function detectTurnFeedback(keypoints) {
+    const rightEye = keypoints[KEYPOINT_RIGHT_EYE];
+    const leftEye = keypoints[KEYPOINT_LEFT_EYE];
+    const nose = keypoints[KEYPOINT_NOSE];
+    if (!rightEye || !leftEye || !nose) {
+        return null;
+    }
+    const eyeMidpointX = (rightEye.x + leftEye.x) / 2;
+    const eyeDistance = Math.abs(leftEye.x - rightEye.x);
+    if (eyeDistance === 0) {
+        return null;
+    }
+    const noseOffsetRatio = (nose.x - eyeMidpointX) / eyeDistance;
+    if (noseOffsetRatio <= -MAX_NOSE_OFFSET_RATIO) {
+        return {
+            feedback: 'turn-right',
+            message: 'Turn slightly right so your face points at the camera.',
+        };
+    }
+    if (noseOffsetRatio >= MAX_NOSE_OFFSET_RATIO) {
+        return {
+            feedback: 'turn-left',
+            message: 'Turn slightly left so your face points at the camera.',
+        };
+    }
+    return null;
+}
+function createFrameAdjustmentResult(confidence, feedback, message) {
+    return createQualityResult({
+        hasFace: true,
+        faceCount: 1,
+        confidence,
+        captureScore: 0,
+        isCentered: false,
+        passesQualityChecks: false,
+        feedback,
+        message,
+    });
+}
+function createQualityResult(result) {
+    return result;
+}
+function calculateCaptureScore(confidence, faceCenterX, faceCenterY, faceAreaRatio) {
+    const xPenalty = Math.abs(faceCenterX - 0.5) / CENTER_TOLERANCE_X;
+    const yPenalty = Math.abs(faceCenterY - 0.5) / CENTER_TOLERANCE_Y;
+    const centerScore = 1 - Math.min((xPenalty + yPenalty) / 2, 1);
+    const maxAreaDistance = Math.max(Math.abs(IDEAL_FACE_AREA_RATIO - MIN_FACE_AREA_RATIO), Math.abs(MAX_FACE_AREA_RATIO - IDEAL_FACE_AREA_RATIO));
+    const sizeScore = 1 - Math.min(Math.abs(faceAreaRatio - IDEAL_FACE_AREA_RATIO) / maxAreaDistance, 1);
+    return Number((confidence * 0.55 + centerScore * 0.3 + sizeScore * 0.15).toFixed(4));
+}
+//# sourceMappingURL=face-quality.js.map

package/dist/services/face-quality.js.map

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