@sssxyd/face-liveness-detector 0.3.5 → 0.4.0-alpha.2

package/dist/types/config.d.ts

@@ -1,15 +1,12 @@
 /**
  * Face Detection Engine - Configuration
  */
-import type { ResolvedEngineConfig, FaceDetectionEngineConfig } from './types';
-/**
- * Default configuration for FaceDetectionEngine
- */
-export declare const DEFAULT_CONFIG: FaceDetectionEngineConfig;
+import type { ResolvedEngineOptions, FaceDetectionEngineOptions } from './types';
 /**
  * Merge user configuration with defaults
+ * Nested objects (face_frontal_features, image_quality_features) are deeply merged
  * @param userConfig - User provided configuration (partial, optional)
  * @returns Complete resolved configuration with all required fields
  */
-export declare function mergeConfig(userConfig?: Partial<FaceDetectionEngineConfig>): ResolvedEngineConfig;
+export declare function mergeOptions(userConfig?: Partial<FaceDetectionEngineOptions>): ResolvedEngineOptions;
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAG9E;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,yBA2C3B,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,UAAU,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,GAC9C,oBAAoB,CA0FtB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AA8EhF;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,UAAU,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,GAC/C,qBAAqB,CAwBvB"}

package/dist/types/enums.d.ts

@@ -40,6 +40,12 @@ export declare enum ErrorCode {
     DETECTOR_NOT_INITIALIZED = "DETECTOR_NOT_INITIALIZED",
     CAMERA_ACCESS_DENIED = "CAMERA_ACCESS_DENIED",
     STREAM_ACQUISITION_FAILED = "STREAM_ACQUISITION_FAILED",
-    SUSPECTED_FRAUDS_DETECTED = "SUSPECTED_FRAUDS_DETECTED"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+export declare enum EngineState {
+    IDLE = "idle",// 初始状态
+    INITIALIZING = "initializing",// 正在初始化
+    READY = "ready",// 初始化完成，就绪
+    DETECTING = "detecting"
 }
 //# sourceMappingURL=enums.d.ts.map

package/dist/types/enums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/enums.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,cAAc;IAExB,KAAK,UAAU;IAEf,UAAU,eAAe;IAEzB,GAAG,QAAQ;CACZ;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,OAAO,YAAY;CACpB;AAED,oBAAY,eAAe;IACzB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;CACpC;AAED;;GAEG;AACH,oBAAY,SAAS;IAEnB,wBAAwB,6BAA6B;IAErD,oBAAoB,yBAAyB;IAE7C,yBAAyB,8BAA8B;IAEvD,yBAAyB,8BAA8B;CACxD"}
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/enums.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,cAAc;IAExB,KAAK,UAAU;IAEf,UAAU,eAAe;IAEzB,GAAG,QAAQ;CACZ;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,OAAO,YAAY;CACpB;AAED,oBAAY,eAAe;IACzB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;CACpC;AAED;;GAEG;AACH,oBAAY,SAAS;IAEnB,wBAAwB,6BAA6B;IAErD,oBAAoB,yBAAyB;IAE7C,yBAAyB,8BAA8B;IAEvD,cAAc,mBAAmB;CAClC;AAED,oBAAY,WAAW;IACrB,IAAI,SAAS,CAAqB,OAAO;IACzC,YAAY,iBAAiB,CAAK,QAAQ;IAC1C,KAAK,UAAU,CAAmB,WAAW;IAC7C,SAAS,cAAc;CACxB"}

package/dist/types/face-detection-engine.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Face Detection Engine - Core Detection Engine
+ * Framework-agnostic face liveness detection engine
+ */
+import type { FaceDetectionEngineOptions } from './types';
+import { EngineState } from './enums';
+import { SimpleEventEmitter } from './event-emitter';
+/**
+ * Framework-agnostic face liveness detection engine
+ * Provides core detection logic without UI dependencies
+ */
+export declare class FaceDetectionEngine extends SimpleEventEmitter {
+    private options;
+    private cv;
+    private human;
+    private engineState;
+    private videoElement;
+    private stream;
+    private frameCanvasElement;
+    private frameCanvasContext;
+    private faceCanvasElement;
+    private faceCanvasContext;
+    private detectionFrameId;
+    private actualVideoWidth;
+    private actualVideoHeight;
+    private detectionState;
+    /**
+     * Constructor
+     * @param config - Configuration object
+     */
+    constructor(options?: Partial<FaceDetectionEngineOptions>);
+    updateOptions(options?: Partial<FaceDetectionEngineOptions>): void;
+    getEngineState(): EngineState;
+    /**
+     * Initialize the detection engine
+     * Loads Human.js and OpenCV.js libraries
+     *
+     * @returns Promise that resolves when initialization is complete
+     * @throws Error if initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Start face detection
+     * Requires initialize() to be called first and a video element to be provided
+     *
+     * @param videoElement - HTMLVideoElement to capture from
+     * @returns Promise that resolves when detection starts
+     * @throws Error if not initialized or video setup fails
+     */
+    startDetection(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * Stop face detection
+     * @param success - Whether to display the best collected image
+     */
+    stopDetection(success: boolean): void;
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    getOptions(): FaceDetectionEngineOptions;
+    /**
+     * Reset detection state
+     */
+    private resetDetectionState;
+    /**
+     * Schedule next detection frame
+     */
+    private scheduleNextDetection;
+    /**
+     * Cancel pending detection frame
+     */
+    private cancelPendingDetection;
+    /**
+     * Main detection loop
+     */
+    private detect;
+    private getPerformActionCount;
+    /**
+     * Handle single face detection
+     */
+    private handleSingleFace;
+    /**
+     * Handle detect phase
+     */
+    private handleDetectPhase;
+    /**
+     * Handle collect phase
+     */
+    private handleCollectPhase;
+    /**
+     * Handle verify phase
+     */
+    private handleVerifyPhase;
+    /**
+     * Handle multiple or no faces
+     */
+    private handleMultipleFaces;
+    private collectHighQualityImage;
+    private emitDetectorInfo;
+    /**
+     * Select next action
+     */
+    private selectNextAction;
+    /**
+     * Detect specific action
+     */
+    private detectAction;
+    /**
+     * Emit debug event
+     */
+    private emitDebug;
+    /**
+     * Draw video frame to canvas (internal use, not converted to Base64)
+     * @returns {HTMLCanvasElement | null} Canvas after drawing, returns null if failed
+     */
+    private drawVideoToCanvas;
+    private clearFrameCanvas;
+    private clearFaceCanvas;
+    /**
+     * 将 canvas 转换为 Base64 JPEG 图片数据
+     * @param {HTMLCanvasElement} canvas - 输入的 canvas
+     * @returns {string | null} Base64 格式的 JPEG 图片数据
+     */
+    private canvasToBase64;
+    /**
+     * Capture current video frame (returns Base64)
+     * @param {Box} box - Face box
+     * @returns {string | null} Base64 encoded JPEG image data
+     */
+    private captureFrame;
+}
+//# sourceMappingURL=face-detection-engine.d.ts.map

package/dist/types/face-detection-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-detection-engine.d.ts","sourceRoot":"","sources":["../../src/face-detection-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,0BAA0B,EAQ3B,MAAM,SAAS,CAAA;AAChB,OAAO,EAAmF,WAAW,EAAE,MAAM,SAAS,CAAA;AAEtH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAwBpD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,OAAO,CAAC,OAAO,CAAuB;IAEtC,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,KAAK,CAAqB;IAElC,OAAO,CAAC,WAAW,CAAgC;IAGnD,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,kBAAkB,CAAiC;IAC3D,OAAO,CAAC,kBAAkB,CAAwC;IAClE,OAAO,CAAC,iBAAiB,CAAiC;IAC1D,OAAO,CAAC,iBAAiB,CAAwC;IAEjE,OAAO,CAAC,gBAAgB,CAAsB;IAE9C,OAAO,CAAC,gBAAgB,CAAY;IACpC,OAAO,CAAC,iBAAiB,CAAY;IAErC,OAAO,CAAC,cAAc,CAAgB;IAEtC;;;OAGG;gBACS,OAAO,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC;IAMzD,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,GAAG,IAAI;IAQlE,cAAc,IAAI,WAAW;IAI7B;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+KjC;;;;;;;OAOG;IACG,cAAc,CAAC,YAAY,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0InE;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IA8BrC;;;OAGG;IACH,UAAU,IAAI,0BAA0B;IAMxC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;YACW,MAAM;IAwDpB,OAAO,CAAC,qBAAqB;IAY7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiNxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkDzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,uBAAuB;IA6B/B,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAuCpB;;OAEG;IACH,OAAO,CAAC,SAAS;IAgBjB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAwDzB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,eAAe;IAWvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CA+BrB"}

package/dist/types/face-detection-state.d.ts

@@ -0,0 +1,35 @@
+import { DetectionPeriod, LivenessAction } from "./enums";
+import { MotionLivenessDetector } from "./motion-liveness-detector";
+import { ScreenCaptureDetector } from './screen-capture-detector';
+import { ResolvedEngineOptions } from "./types";
+/**
+ * Internal detection state interface
+ */
+export declare class DetectionState {
+    period: DetectionPeriod;
+    startTime: number;
+    collectCount: number;
+    suspectedFraudsCount: number;
+    bestQualityScore: number;
+    bestFrameImage: string | null;
+    bestFaceImage: string | null;
+    completedActions: Set<LivenessAction>;
+    currentAction: LivenessAction | null;
+    actionVerifyTimeout: ReturnType<typeof setTimeout> | null;
+    lastFrontalScore: number;
+    motionDetector: MotionLivenessDetector | null;
+    liveness: boolean;
+    screenDetector: ScreenCaptureDetector | null;
+    constructor(options: Partial<DetectionState>);
+    reset(): void;
+    needFrontalFace(): boolean;
+    isReadyToVerify(minCollectCount: number): boolean;
+    onActionStarted(nextAction: LivenessAction, timeoutMills: number, timeoutCallback: () => void): void;
+    onActionCompleted(): void;
+    /**
+     * Clear action verify timeout
+     */
+    private clearActionVerifyTimeout;
+}
+export declare function createDetectionState(options: ResolvedEngineOptions): DetectionState;
+//# sourceMappingURL=face-detection-state.d.ts.map

package/dist/types/face-detection-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-detection-state.d.ts","sourceRoot":"","sources":["../../src/face-detection-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAwB,MAAM,SAAS,CAAA;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACnE,OAAO,EAAE,qBAAqB,EAA6B,MAAM,2BAA2B,CAAA;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,qBAAa,cAAc;IACvB,MAAM,EAAE,eAAe,CAAyB;IAChD,SAAS,EAAE,MAAM,CAAoB;IACrC,YAAY,EAAE,MAAM,CAAI;IACxB,oBAAoB,EAAE,MAAM,CAAI;IAChC,gBAAgB,EAAE,MAAM,CAAI;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAO;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAO;IACnC,gBAAgB,EAAE,GAAG,CAAC,cAAc,CAAC,CAAY;IACjD,aAAa,EAAE,cAAc,GAAG,IAAI,CAAO;IAC3C,mBAAmB,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAO;IAChE,gBAAgB,EAAE,MAAM,CAAI;IAC5B,cAAc,EAAE,sBAAsB,GAAG,IAAI,CAAO;IACpD,QAAQ,EAAE,OAAO,CAAQ;IACzB,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAO;gBAEvC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC;IAI5C,KAAK,IAAI,IAAI;IAeb,eAAe,IAAI,OAAO;IAK1B,eAAe,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO;IAUjD,eAAe,CAAC,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,IAAI,GAAG,IAAI;IASpG,iBAAiB,IAAI,IAAI;IASzB;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAMnC;AAID,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA4BnF"}

package/dist/types/face-frontal-calculator.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 人脸正对度检测模块 - 混合多尺度算法版本
+ *
+ * 使用四层混合检测策略：
+ * 1. 特征点对称性检测 (40%) - 眼睛水平线、鼻子中心、嘴角对称性
+ * 2. 轮廓对称性检测 (35%) - Sobel 边缘检测的轮廓对称性
+ * 3. 角度融合分析 (25%) - Yaw/Pitch/Roll 角度综合评分
+ * 4. 手势识别验证 - 作为额外验证
+ *
+ * 相比单一方法，混合算法提升准确度 30-40%
+ */
+import { FaceResult, GestureResult } from '@vladmandic/human';
+import { FaceFrontalFeatures } from './types';
+/**
+ * 角度分析结果接口
+ */
+export interface AngleAnalysisResult {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    score: number;
+}
+/**
+ * 检查人脸是否正对摄像头 - 主函数（混合多尺度版本）
+ *
+ * 使用四层混合检测策略：
+ * 1. 特征点对称性检测 (40%) - 最准确
+ * 2. 轮廓对称性检测 (35%) - 快速且鲁棒
+ * 3. 角度融合分析 (25%) - 补充验证
+ * 4. 手势识别验证 - 额外验证（如果提供手势数据）
+ *
+ * @param {any} cv - OpenCV 实例（用于轮廓对称性检测）
+ * @param {FaceResult} face - 人脸检测结果（包含 rotation 和 annotations 信息）
+ * @param {Array<GestureResult>} gestures - 检测到的手势/表情数组（可选）
+ * @param {any} matImage - OpenCV Mat 对象（图像数据，用于轮廓检测）
+ * @param {FaceFrontalFeatures} config - 正对度配置参数（包含角度阈值）
+ * @returns {number} 正对度评分 (0-1)，1 表示完全正对
+ *
+ * @example
+ * const mat = drawVideoToMat()
+ * const score = calcFaceFrontal(cv, face, gestures, mat, config)
+ * if (score > 0.9) {
+ *   console.log('人脸足够正对')
+ * }
+ * mat.delete()
+ */
+export declare function calcFaceFrontal(cv: any, face: FaceResult, gestures: Array<GestureResult>, matImage: any, config: FaceFrontalFeatures): number;
+/**
+ * 使用手势识别方法检查人脸正对度
+ *
+ * 从 Human.js 返回的手势中查找 "facing center" 标志
+ *
+ * @param {Array<GestureResult>} gestures - Human.js 检测到的手势数组
+ * @returns {number} 评分 (0-1)，0 表示未检测到相关手势
+ *
+ * @example
+ * const score = checkFaceFrontalWithGestures(result.gesture)
+ */
+export declare function checkFaceFrontalWithGestures(gestures: Array<GestureResult>): boolean;
+/**
+ * 使用角度分析方法检查人脸正对度
+ *
+ * 分析人脸的 yaw、pitch、roll 三个角度
+ * 使用加权评分：yaw (60%) + pitch (25%) + roll (15%)
+ * 直接使用 CONFIG.FACE_FRONTAL 中的参数
+ *
+ * @param {FaceResult} face - 人脸检测结果
+ * @param {FaceFrontalFeatures} config - 正对度配置参数
+ * @returns {number} 正对度评分 (0-1)
+ *
+ * @example
+ * const score = checkFaceFrontalWithAngles(face, config)
+ */
+export declare function checkFaceFrontalWithAngles(face: FaceResult, config: FaceFrontalFeatures): number;
+/**
+ * 从人脸检测结果中提取三维旋转角度
+ *
+ * 返回标准化的 yaw、pitch、roll 角度值（单位：度）
+ *
+ * @param {FaceResult} face - Human.js 人脸检测结果
+ * @returns {AngleAnalysisResult} 包含角度和评分的结果对象
+ */
+export declare function extractFaceAngles(face: FaceResult): AngleAnalysisResult;
+/**
+ * 获取角度分析的详细信息
+ *
+ * 返回每个角度维度的详细评分和状态
+ * 直接使用 CONFIG.FACE_FRONTAL 中的参数
+ *
+ * @param {FaceResult} face - 人脸检测结果
+ * @param {FaceFrontalFeatures} config - 正对度配置参数
+ * @returns {object} 包含各维度评分的详细对象
+ *
+ * @example
+ * const details = getAngleAnalysisDetails(face, config)
+ * console.log(details.yawScore)  // 0.85
+ * console.log(details.issues)    // ['Yaw 角度超过阈值']
+ */
+export declare function getAngleAnalysisDetails(face: FaceResult, config: FaceFrontalFeatures): Record<string, any>;
+/**
+ * 获取人脸正对度的描述文本
+ *
+ * 将评分转换为用户友好的描述
+ *
+ * @param {number} score - 正对度评分 (0-1)
+ * @returns {string} 描述文本
+ *
+ * @example
+ * console.log(getFrontalDescription(0.95))  // "非常正对"
+ * console.log(getFrontalDescription(0.6))   // "请调整角度"
+ */
+export declare function getFrontalDescription(score: number): string;
+/**
+ * 根据人脸角度给出具体的调整建议
+ *
+ * 直接使用 CONFIG.FACE_FRONTAL 中的参数
+ *
+ * @param {FaceResult} face - 人脸检测结果
+ * @param {FaceFrontalFeatures} config - 正对度配置参数
+ * @returns {string[]} 调整建议列表
+ *
+ * @example
+ * const suggestions = getAdjustmentSuggestions(face, config)
+ * suggestions.forEach(s => console.log(s))
+ * // 输出:
+ * // "请向左转动头部"
+ * // "请抬起头部"
+ */
+export declare function getAdjustmentSuggestions(face: FaceResult, config: FaceFrontalFeatures): string[];
+//# sourceMappingURL=face-frontal-calculator.d.ts.map

package/dist/types/face-frontal-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-frontal-calculator.d.ts","sourceRoot":"","sources":["../../src/face-frontal-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAG7C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,GAAG,EACP,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC,EAC9B,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAgCR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO,CAUpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,CA8BhG;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,mBAAmB,CAUvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiD1G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAwChG"}

package/dist/types/image-quality-calculator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 人脸图像质量检测模块 (统一版)
+ *
+ * 综合检测人脸图像的：
+ * 1. 完整度检测 - 人脸是否完整在框内
+ * 2. 模糊度检测 - 图像是否清晰
+ * 3. 轮廓清晰度 - 轮廓的连通性和完整度
+ *
+ * 使用混合检测策略，结合 Human.js 和 OpenCV.js 优势
+ */
+import { FaceResult } from '@vladmandic/human';
+import { ImageQualityFeatures } from './types';
+/**
+ * 单个检测指标的结果
+ */
+export interface QualityMetricResult {
+    name: string;
+    value: number;
+    threshold: number;
+    passed: boolean;
+    description: string;
+}
+/**
+ * 图像质量检测的综合结果
+ */
+export interface ImageQualityResult {
+    passed: boolean;
+    score: number;
+    completenessReasons: string[];
+    blurReasons: string[];
+    metrics: {
+        completeness: QualityMetricResult;
+        laplacianVariance: QualityMetricResult;
+        gradientSharpness: QualityMetricResult;
+        overallQuality: QualityMetricResult;
+    };
+    suggestions?: string[];
+}
+/**
+ * 计算图像质量（完整度 + 清晰度）
+ *
+ * 综合检测：
+ * - 人脸完整度（Human.js边界 + OpenCV轮廓）
+ * - 图像清晰度（拉普拉斯方差 + Sobel梯度）
+ *
+ * @param cv - OpenCV.js 对象，用于执行图像处理操作
+ * @param matImage - OpenCV Mat 对象，包含灰度图像数据
+ * @param face - 人脸检测结果，包含人脸框位置和其他检测信息
+ * @param imageWidth - 图片宽度（像素），用于边界检查和完整度计算
+ * @param imageHeight - 图片高度（像素），用于边界检查和完整度计算
+ * @param config - 检测配置对象，包含：
+ *   - require_full_face_in_bounds: 是否要求人脸完全在边界内
+ *   - use_opencv_enhancement: 是否使用 OpenCV 增强检测
+ *   - min_laplacian_variance: 拉普拉斯方差最小阈值
+ *   - min_gradient_sharpness: 梯度清晰度最小阈值
+ * @param threshold - 综合质量评分阈值 (0-1)，大于等于此值判定为通过
+ * @returns 综合质量检测结果，包含：
+ *   - passed: 是否通过质量检测
+ *   - score: 综合质量评分 (0-1)
+ *   - completenessReasons: 完整度不通过原因列表
+ *   - blurReasons: 清晰度不通过原因列表
+ *   - metrics: 各维度详细指标（完整度、拉普拉斯方差、梯度清晰度、综合质量）
+ *   - suggestions: 改进建议列表
+ */
+export declare function calcImageQuality(cv: any, matImage: any, face: FaceResult, imageWidth: number, imageHeight: number, config: ImageQualityFeatures, threshold: number): ImageQualityResult;
+//# sourceMappingURL=image-quality-calculator.d.ts.map

package/dist/types/image-quality-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-quality-calculator.d.ts","sourceRoot":"","sources":["../../src/image-quality-calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAI9C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAEjC,MAAM,EAAE,OAAO,CAAA;IAEf,KAAK,EAAE,MAAM,CAAA;IAEb,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAA;IAErB,OAAO,EAAE;QACP,YAAY,EAAE,mBAAmB,CAAA;QACjC,iBAAiB,EAAE,mBAAmB,CAAA;QACtC,iBAAiB,EAAE,mBAAmB,CAAA;QACtC,cAAc,EAAE,mBAAmB,CAAA;KACpC,CAAA;IAED,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,GAAG,EACP,QAAQ,EAAE,GAAG,EACb,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAoEpB"}

package/dist/types/index.d.ts

@@ -2,198 +2,12 @@
  * Face Detection Engine - Core Detection Engine
  * Framework-agnostic face liveness detection engine
  */
-import type { FaceDetectionEngineConfig } from './types';
-import { SimpleEventEmitter } from './event-emitter';
-/**
- * Framework-agnostic face liveness detection engine
- * Provides core detection logic without UI dependencies
- *
- * @example
- * ```typescript
- * const engine = new FaceDetectionEngine({
- *   min_face_ratio: 0.5,
- *   max_face_ratio: 0.9,
- *   liveness_action_count: 1
- * })
- *
- * engine.on('detector-loaded', () => {
- *   console.log('Engine ready')
- *   engine.startDetection(videoElement, canvasElement)
- * })
- *
- * engine.on('detector-finish', (data) => {
- *   console.log('Liveness detection completed:', data)
- * })
- *
- * engine.on('detector-error', (error) => {
- *   console.error('Detection error:', error)
- * })
- *
- * await engine.initialize()
- * ```
- */
-export declare class FaceDetectionEngine extends SimpleEventEmitter {
-    private config;
-    private human;
-    private stream;
-    private isDetecting;
-    private isReady;
-    private isInitializing;
-    private videoElement;
-    private frameCanvasElement;
-    private frameCanvasContext;
-    private faceCanvasElement;
-    private faceCanvasContext;
-    private detectionFrameId;
-    private actualVideoWidth;
-    private actualVideoHeight;
-    private detectionState;
-    /**
-     * Constructor
-     * @param config - Configuration object
-     */
-    constructor(config?: Partial<FaceDetectionEngineConfig>);
-    /**
-     * Initialize the detection engine
-     * Loads Human.js and OpenCV.js libraries
-     *
-     * @returns Promise that resolves when initialization is complete
-     * @throws Error if initialization fails
-     */
-    initialize(): Promise<void>;
-    /**
-     * Start face detection
-     * Requires initialize() to be called first and a video element to be provided
-     *
-     * @param videoElement - HTMLVideoElement to capture from
-     * @returns Promise that resolves when detection starts
-     * @throws Error if not initialized or video setup fails
-     */
-    startDetection(videoElement: HTMLVideoElement): Promise<void>;
-    /**
-     * Stop face detection
-     * @param success - Whether to display the best collected image
-     */
-    stopDetection(success: boolean): void;
-    /**
-     * Update configuration
-     * Note: Some settings may not take effect if called during detection
-     *
-     * @param config - Configuration overrides
-     */
-    updateConfig(config: Partial<FaceDetectionEngineConfig>): void;
-    /**
-     * Get current configuration
-     * @returns Current configuration
-     */
-    getConfig(): FaceDetectionEngineConfig;
-    /**
-     * Get detection status
-     * @returns Object with status information
-     */
-    getStatus(): {
-        isReady: boolean;
-        isDetecting: boolean;
-        isInitializing: boolean;
-    };
-    /**
-     * Reset detection state
-     */
-    private resetDetectionState;
-    /**
-     * Schedule next detection frame
-     */
-    private scheduleNextDetection;
-    /**
-     * Cancel pending detection frame
-     */
-    private cancelPendingDetection;
-    /**
-     * Main detection loop
-     */
-    private detect;
-    private getPerformActionCount;
-    /**
-     * Handle single face detection
-     */
-    private handleSingleFace;
-    /**
-     * Validate face box existence
-     */
-    private validateFaceBox;
-    /**
-     * Validate face size ratio
-     */
-    private validateFaceSize;
-    /**
-     * Validate face frontal angle
-     */
-    private validateFaceFrontal;
-    /**
-     * Validate image quality
-     */
-    private validateImageQuality;
-    /**
-     * Validate silent liveness scores
-     */
-    private validateSilentLiveness;
-    /**
-     * Handle detect phase
-     */
-    private handleDetectPhase;
-    /**
-     * Handle collect phase
-     */
-    private handleCollectPhase;
-    /**
-     * Handle verify phase
-     */
-    private handleVerifyPhase;
-    /**
-     * Handle multiple or no faces
-     */
-    private handleMultipleFaces;
-    private collectHighQualityImage;
-    private emitDetectorInfo;
-    /**
-     * Select next action
-     */
-    private selectNextAction;
-    /**
-     * Clear action verify timeout
-     */
-    private clearActionVerifyTimeout;
-    /**
-     * Detect specific action
-     */
-    private detectAction;
-    /**
-     * Emit debug event
-     */
-    private emitDebug;
-    /**
-     * Draw video frame to canvas (internal use, not converted to Base64)
-     * @returns {HTMLCanvasElement | null} Canvas after drawing, returns null if failed
-     */
-    private drawVideoToCanvas;
-    private clearFrameCanvas;
-    private clearFaceCanvas;
-    /**
-     * 将 canvas 转换为 Base64 JPEG 图片数据
-     * @param {HTMLCanvasElement} canvas - 输入的 canvas
-     * @returns {string | null} Base64 格式的 JPEG 图片数据
-     */
-    private canvasToBase64;
-    /**
-     * Capture current video frame (returns Base64)
-     * @param {Box} box - Face box
-     * @returns {string | null} Base64 encoded JPEG image data
-     */
-    private captureFrame;
-}
-export type { FaceDetectionEngineConfig, FaceFrontalFeatures, ImageQualityFeatures, DetectorInfoEventData, DetectorFinishEventData, DetectorErrorEventData, DetectorDebugEventData, DetectorActionEventData, DetectorLoadedEventData, EventMap, EventEmitter, EventListener, ResolvedEngineConfig } from './types';
-export { LivenessAction, ErrorCode, DetectionCode, LivenessActionStatus, DetectionPeriod } from './enums';
+import { FaceDetectionEngine } from './face-detection-engine';
+export type { FaceDetectionEngineOptions, FaceFrontalFeatures, ImageQualityFeatures, DetectorInfoEventData, DetectorFinishEventData, DetectorErrorEventData, DetectorDebugEventData, DetectorActionEventData, DetectorLoadedEventData, EventMap, EventEmitter, EventListener, } from './types';
+export { LivenessAction, ErrorCode, DetectionCode, LivenessActionStatus, DetectionPeriod, EngineState } from './enums';
 export { preloadOpenCV, getCvSync, getOpenCVVersion, detectBrowserEngine } from './library-loader';
 export { SimpleEventEmitter } from './event-emitter';
+export { UniAppFaceDetectionEngine, createSDK, checkEnvironmentSupport } from './uniapp-sdk';
+export { FaceDetectionEngine };
 export default FaceDetectionEngine;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAG7D,YAAY,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAEtH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAElG,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,yBAAyB,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAE5F,OAAO,EAAE,mBAAmB,EAAE,CAAA;AAE9B,eAAe,mBAAmB,CAAA"}

package/dist/types/library-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-loader.d.ts","sourceRoot":"","sources":["../../src/library-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,mBAAmB,CAAA;AA6BrC,KAAK,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CA2BpE;AAiGD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB1E;AA2GD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,CAAC,CAmD9E;AAED;;;GAGG;AACH,wBAAgB,SAAS,QAYxB;AA+KD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAiEnI;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,QAwB/B"}
+{"version":3,"file":"library-loader.d.ts","sourceRoot":"","sources":["../../src/library-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,mBAAmB,CAAA;AA6BrC,KAAK,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CA2BpE;AAiGD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB1E;AA2GD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,CAAC,CAmD9E;AAED;;;GAGG;AACH,wBAAgB,SAAS,QAYxB;AAsLD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAiEnI;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,QAwB/B"}