id-scanner-lib/dist/types/modules/face/face-detector.d.ts

Browser-based ID card, QR code, and face recognition scanner with liveness detection

/**
 * @file 人脸检测模块
 * @description 提供人脸检测、跟踪和分析功能
 * @module modules/face/face-detector
 */
import { BaseScannerModule, ModuleCapabilities, ModuleInitOptions, ModuleType } from '../../interfaces/scanner-module';
import { FaceDetectionOptions, FaceDetectionResult, LivenessDetectionType } from '../../interfaces/face-detection';
import { Result } from '../../core/result';
/**
 * 人脸检测模型类型
 */
export declare enum FaceModelType {
    /** SSD MobileNet V1 模型 */
    SSD_MOBILENET = "ssd_mobilenetv1",
    /** Tiny Face 模型 */
    TINY_FACE = "tiny_face",
    /** MTCNN 模型 */
    MTCNN = "mtcnn",
    /** BlazeFace 模型 */
    BLAZE_FACE = "blazeface"
}
/**
 * 人脸检测模块配置
 */
export interface FaceDetectorConfig {
    /** 是否启用 */
    enabled: boolean;
    /** 检测模型类型 */
    detectionModel: FaceModelType;
    /** 置信度阈值 */
    minConfidence: number;
    /** 最大检测人脸数 */
    maxFaces: number;
    /** 是否检测关键点 */
    detectLandmarks: boolean;
    /** 关键点模型类型 */
    landmarksModel: 'tiny' | '68_points';
    /** 是否检测表情 */
    detectExpressions: boolean;
    /** 是否检测年龄和性别 */
    detectAgeGender: boolean;
    /** 是否提取人脸特征向量 */
    extractEmbeddings: boolean;
    /** 人脸匹配阈值(0-1) */
    matchThreshold: number;
    /** 是否启用跟踪 */
    enableTracking: boolean;
    /** 活体检测类型 */
    livenessDetection: LivenessDetectionType | 'none';
    /** 模型路径 */
    modelPath: string;
}
/**
 * 人脸检测模块
 */
export declare class FaceDetector extends BaseScannerModule {
    /** 模块类型 */
    readonly type: ModuleType;
    /** 模块配置 */
    protected config: FaceDetectorConfig;
    /** 默认配置 */
    private static readonly DEFAULT_CONFIG;
    /** 模型加载状态 */
    private modelsLoaded;
    /** 处理计时器ID */
    private processingTimerId;
    /** 处理间隔(ms) */
    private processingInterval;
    /** 摄像头管理器 */
    private cameraManager;
    /** 配置管理器 */
    private configManager;
    /** 资源管理器 */
    private resourceManager;
    /** 日志记录器 */
    private logger;
    /** 画布元素，用于处理帧 */
    private canvas;
    /** 画布渲染上下文 */
    private canvasCtx;
    /** 最后一次检测结果 */
    private lastDetectionResult;
    /** 人脸跟踪状态 */
    private faceTrackers;
    /**
     * 构造函数
     * @param config 初始配置
     */
    constructor(config?: Partial<FaceDetectorConfig>);
    /**
     * 获取模块能力
     */
    get capabilities(): ModuleCapabilities;
    /**
     * 初始化模块
     * @param options 初始化选项
     */
    initialize(options?: ModuleInitOptions): Promise<void>;
    /**
     * 加载人脸检测模型
     * @param modelPath 模型路径
     */
    private loadModels;
    /**
     * 处理图片
     * @param image 图片源
     * @param options 处理选项
     */
    processImage(image: string | HTMLImageElement | HTMLCanvasElement | ImageData, options?: FaceDetectionOptions): Promise<Result<FaceDetectionResult[]>>;
    /**
     * 开始实时处理
     * @param videoElement 视频元素
     * @param options 处理选项
     */
    startRealtime(videoElement?: HTMLVideoElement, options?: FaceDetectionOptions): Promise<Result<boolean>>;
    /**
     * 停止实时处理
     */
    stopRealtime(): void;
    /**
     * 释放资源
     */
    dispose(): Promise<void>;
    /**
     * 加载图片
     * @param src 图片URL
     */
    private loadImage;
    /**
     * 处理视频帧
     * @param video 视频元素
     * @param options 处理选项
     */
    private processVideoFrame;
    /**
     * 处理摄像头帧
     */
    private handleCameraFrame;
    /**
     * 执行人脸检测
     * @param input 输入图像
     * @param options 检测选项
     */
    private detectFaces;
    /**
     * 跟踪人脸
     * @param detection 人脸检测结果
     */
    private trackFace;
    /**
     * 比对两个人脸
     * @param source 源人脸
     * @param target 目标人脸
     */
    compareFaces(source: string | HTMLImageElement | FaceDetectionResult, target: string | HTMLImageElement | FaceDetectionResult): Promise<Result<{
        similarity: number;
        isMatch: boolean;
        threshold: number;
    }>>;
    /**
     * 计算两个特征向量的余弦相似度
     * @param v1 特征向量1
     * @param v2 特征向量2
     */
    private calculateSimilarity;
    /**
     * 获取最近的检测结果
     */
    getLatestResults(): FaceDetectionResult[];
}