id-scanner-lib 1.3.2 → 1.5.0

package/dist/types/interfaces/scanner-module.d.ts

@@ -0,0 +1,280 @@
+/**
+ * @file 扫描器模块接口
+ * @description 定义所有扫描模块共享的核心接口
+ * @module interfaces/scanner-module
+ */
+import { EventEmitter } from '../core/event-emitter';
+import { Result } from '../core/result';
+import { ModuleConfig } from '../core/config';
+import { Module } from '../core/module-manager';
+/**
+ * 模块状态枚举
+ */
+export declare enum ModuleStatus {
+    /** 未初始化 */
+    NOT_INITIALIZED = "not_initialized",
+    /** 初始化中 */
+    INITIALIZING = "initializing",
+    /** 就绪 */
+    READY = "ready",
+    /** 处理中 */
+    PROCESSING = "processing",
+    /** 暂停 */
+    PAUSED = "paused",
+    /** 错误 */
+    ERROR = "error"
+}
+/**
+ * 模块类型枚举
+ */
+export declare enum ModuleType {
+    /** 人脸识别模块 */
+    FACE = "face",
+    /** 二维码扫描模块 */
+    QR = "qr",
+    /** 身份证识别模块 */
+    IDCARD = "idcard",
+    /** OCR识别模块 */
+    OCR = "ocr"
+}
+/**
+ * 模块能力接口
+ * 描述模块支持的功能
+ */
+export interface ModuleCapabilities {
+    /** 是否支持视频处理 */
+    supportsVideo: boolean;
+    /** 是否支持图片处理 */
+    supportsImage: boolean;
+    /** 是否支持批量处理 */
+    supportsBatch: boolean;
+    /** 是否支持实时处理 */
+    supportsRealtime: boolean;
+    /** 是否支持Web Worker处理 */
+    supportsWebWorker: boolean;
+    /** 支持的媒体类型 */
+    supportedMediaTypes: string[];
+    /** 其他能力 */
+    [key: string]: any;
+}
+/**
+ * 模块事件
+ */
+export declare enum ModuleEvent {
+    /** 初始化开始 */
+    INIT_START = "module:init:start",
+    /** 初始化完成 */
+    INIT_COMPLETE = "module:init:complete",
+    /** 初始化失败 */
+    INIT_ERROR = "module:init:error",
+    /** 处理开始 */
+    PROCESS_START = "module:process:start",
+    /** 处理完成 */
+    PROCESS_COMPLETE = "module:process:complete",
+    /** 处理失败 */
+    PROCESS_ERROR = "module:process:error",
+    /** 处理进度 */
+    PROCESS_PROGRESS = "module:process:progress",
+    /** 实时结果 */
+    REALTIME_RESULT = "module:realtime:result",
+    /** 状态变更 */
+    STATUS_CHANGE = "module:status:change"
+}
+/**
+ * 模块初始化选项
+ */
+export interface ModuleInitOptions {
+    /** 模块配置 */
+    config?: ModuleConfig;
+    /** 使用Web Worker */
+    useWorker?: boolean;
+    /** Web Worker脚本路径 */
+    workerPath?: string;
+    /** 是否启用调试 */
+    debug?: boolean;
+    /** 是否绑定摄像头 */
+    bindCamera?: boolean;
+    /** 目标DOM元素 */
+    targetElement?: HTMLElement;
+    /** 模型路径 */
+    modelPath?: string;
+    /** 其他选项 */
+    [key: string]: any;
+}
+/**
+ * 扫描器模块接口
+ * 定义所有扫描模块必须实现的基础接口
+ */
+export interface IScannerModule extends EventEmitter, Module {
+    /** 模块类型 */
+    readonly type: ModuleType;
+    /** 模块当前状态 */
+    readonly status: ModuleStatus;
+    /** 模块能力 */
+    readonly capabilities: ModuleCapabilities;
+    /**
+     * 处理图片
+     * @param image 图片源（URL、HTMLImageElement或其他支持的格式）
+     * @param options 处理选项
+     */
+    processImage(image: string | HTMLImageElement | HTMLCanvasElement | ImageData, options?: Record<string, any>): Promise<Result<any>>;
+    /**
+     * 开始实时处理
+     * @param videoElement 视频元素，不提供时将使用绑定的摄像头
+     * @param options 处理选项
+     */
+    startRealtime(videoElement?: HTMLVideoElement, options?: Record<string, any>): Promise<Result<boolean>>;
+    /**
+     * 停止实时处理
+     */
+    stopRealtime(): void;
+    /**
+     * 暂停处理
+     */
+    pause(): void;
+    /**
+     * 恢复处理
+     */
+    resume(): Promise<boolean>;
+    /**
+     * 重置模块状态
+     */
+    reset(): void;
+    /**
+     * 获取模块版本
+     */
+    getVersion(): string;
+    /**
+     * 获取模块状态
+     */
+    getStatus(): ModuleStatus;
+    /**
+     * 获取模块配置
+     */
+    getConfig(): ModuleConfig;
+    /**
+     * 更新模块配置
+     * @param config 新配置
+     */
+    updateConfig(config: Partial<ModuleConfig>): void;
+}
+/**
+ * 基础扫描器结果接口
+ */
+export interface BaseScannerResult {
+    /** 结果ID */
+    id: string;
+    /** 结果类型 */
+    type: string;
+    /** 处理时间(毫秒) */
+    processingTime: number;
+    /** 时间戳 */
+    timestamp: number;
+    /** 置信度(0-1) */
+    confidence: number;
+    /** 原始数据 */
+    rawData?: any;
+}
+/**
+ * 基础扫描器模块抽象类
+ * 提供通用的模块功能实现
+ */
+export declare abstract class BaseScannerModule extends EventEmitter implements IScannerModule {
+    /** 模块类型 */
+    abstract readonly type: ModuleType;
+    /** 模块当前状态 */
+    protected _status: ModuleStatus;
+    /** 模块配置 */
+    protected config: ModuleConfig;
+    /** 模块版本 */
+    readonly version: string;
+    /** 是否为调试模式 */
+    protected debug: boolean;
+    /**
+     * 构造函数
+     * @param config 初始配置
+     */
+    constructor(config?: ModuleConfig);
+    /**
+     * 获取模块状态
+     */
+    get status(): ModuleStatus;
+    /**
+     * 设置模块状态
+     */
+    protected setStatus(status: ModuleStatus): void;
+    /**
+     * 获取模块能力
+     */
+    abstract get capabilities(): ModuleCapabilities;
+    /**
+     * 初始化模块
+     * @param options 初始化选项
+     */
+    abstract initialize(options?: ModuleInitOptions): Promise<void>;
+    /**
+     * 处理图片
+     * @param image 图片源（URL、HTMLImageElement或其他支持的格式）
+     * @param options 处理选项
+     */
+    abstract processImage(image: string | HTMLImageElement | HTMLCanvasElement | ImageData, options?: Record<string, any>): Promise<Result<any>>;
+    /**
+     * 开始实时处理
+     * @param videoElement 视频元素，不提供时将使用绑定的摄像头
+     * @param options 处理选项
+     */
+    abstract startRealtime(videoElement?: HTMLVideoElement, options?: Record<string, any>): Promise<Result<boolean>>;
+    /**
+     * 停止实时处理
+     */
+    abstract stopRealtime(): void;
+    /**
+     * 暂停处理
+     */
+    pause(): void;
+    /**
+     * 恢复处理
+     */
+    resume(): Promise<boolean>;
+    /**
+     * 释放模块资源
+     */
+    abstract dispose(): Promise<void>;
+    /**
+     * 重置模块状态
+     */
+    reset(): void;
+    /**
+     * 获取模块版本
+     */
+    getVersion(): string;
+    /**
+     * 获取模块状态
+     */
+    getStatus(): ModuleStatus;
+    /**
+     * 获取模块配置
+     */
+    getConfig(): ModuleConfig;
+    /**
+     * 更新模块配置
+     * @param config 新配置
+     */
+    updateConfig(config: Partial<ModuleConfig>): void;
+    /**
+     * 检查模块是否已初始化
+     */
+    protected checkInitialized(): void;
+    /**
+     * 检查模块是否就绪
+     */
+    protected checkReady(): void;
+    /**
+     * 获取模块名称
+     */
+    get name(): string;
+    /**
+     * 获取模块是否已初始化
+     */
+    get isInitialized(): boolean;
+}

package/dist/types/modules/face/face-detector.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @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[];
+}

package/dist/types/modules/face/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file 人脸模块入口
+ * @description 提供人脸检测、活体检测和人脸比对功能的模块入口
+ * @module modules/face
+ */
+import { BaseModule } from '../../core/base-module';
+import { FaceDetectionResult, FaceComparisonResult, FaceModuleOptions } from './types';
+/**
+ * 人脸模块
+ * 提供人脸检测、活体检测和人脸比对功能
+ */
+export declare class FaceModule extends BaseModule {
+    /** 模块名称 */
+    readonly name: string;
+    /** 模块配置 */
+    private options;
+    /** 最后一次检测结果 */
+    private lastDetectionResult?;
+    /**
+     * 构造函数
+     * @param options 模块配置选项
+     */
+    constructor(options?: FaceModuleOptions);
+    /**
+     * 初始化模块
+     */
+    initialize(): Promise<void>;
+    /**
+     * 检测图像中的人脸
+     * @param image 图像源
+     * @returns 人脸检测结果
+     */
+    detectFace(image: ImageData | HTMLImageElement | HTMLCanvasElement): Promise<FaceDetectionResult | undefined>;
+    /**
+     * 进行活体检测
+     * @param image 图像源
+     * @returns 活体检测结果
+     */
+    detectLiveness(image: ImageData | HTMLImageElement | HTMLCanvasElement): Promise<boolean>;
+    /**
+     * 比对两个人脸
+     * @param face1 第一个人脸图像
+     * @param face2 第二个人脸图像
+     * @returns 人脸比对结果
+     */
+    compareFaces(face1: ImageData | HTMLImageElement | HTMLCanvasElement, face2: ImageData | HTMLImageElement | HTMLCanvasElement): Promise<FaceComparisonResult>;
+    /**
+     * 获取最后一次检测结果
+     */
+    getLastDetectionResult(): FaceDetectionResult | undefined;
+    /**
+     * 释放模块资源
+     */
+    dispose(): Promise<void>;
+}
+export * from './types';

package/dist/types/modules/face/liveness-detector.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @file 活体检测模块
+ * @description 提供人脸活体检测功能
+ * @module modules/face/liveness-detector
+ */
+import { BaseScannerModule, ModuleCapabilities, ModuleInitOptions, ModuleType } from '../../interfaces/scanner-module';
+import { LivenessAction, LivenessDetectionResult, LivenessDetectionType, LivenessSession } from '../../interfaces/face-detection';
+import { Result } from '../../core/result';
+import { FaceDetector } from './face-detector';
+/**
+ * 眨眼检测阈值配置
+ */
+interface BlinkThresholds {
+    /** 眼睛闭合阈值 */
+    eyeClosedThreshold: number;
+    /** 眼睛张开阈值 */
+    eyeOpenThreshold: number;
+    /** 检测阈值 */
+    detectionThreshold: number;
+}
+/**
+ * 活体检测器配置
+ */
+export interface LivenessDetectorConfig {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 检测类型 */
+    detectionType: LivenessDetectionType;
+    /** 检测置信度阈值 */
+    confidenceThreshold: number;
+    /** 眨眼检测阈值 */
+    blinkThresholds: BlinkThresholds;
+    /** 活体挑战超时(毫秒) */
+    challengeTimeout: number;
+    /** 活体挑战动作 */
+    challengeActions: LivenessAction[];
+}
+/**
+ * 活体检测模块
+ * 提供人脸活体检测功能，支持被动式和主动式活体检测
+ */
+export declare class LivenessDetector extends BaseScannerModule {
+    /** 模块类型 */
+    readonly type: ModuleType;
+    /** 模块配置 */
+    protected config: LivenessDetectorConfig;
+    /** 默认配置 */
+    private static readonly DEFAULT_CONFIG;
+    /** 配置管理器 */
+    private configManager;
+    /** 日志记录器 */
+    private logger;
+    /** 资源管理器 */
+    private resourceManager;
+    /** 摄像头管理器 */
+    private cameraManager;
+    /** 人脸检测器 */
+    private faceDetector;
+    /** 当前活体会话 */
+    private currentSession;
+    /** 检测历史记录，用于分析眨眼等动作 */
+    private detectionHistory;
+    /** 最大历史记录长度 */
+    private readonly MAX_HISTORY_LENGTH;
+    /** 防抖处理函数 */
+    private debouncedProcessFrame;
+    /**
+     * 构造函数
+     * @param config 初始配置
+     * @param faceDetector 可选的人脸检测器实例
+     */
+    constructor(config?: Partial<LivenessDetectorConfig>, faceDetector?: FaceDetector);
+    /**
+     * 获取模块能力
+     */
+    get capabilities(): ModuleCapabilities;
+    /**
+     * 初始化模块
+     * @param options 初始化选项
+     */
+    initialize(options?: ModuleInitOptions): Promise<void>;
+    /**
+     * 处理图片
+     * @param image 图片源
+     * @param options 处理选项
+     */
+    processImage(image: string | HTMLImageElement | HTMLCanvasElement | ImageData, options?: Record<string, any>): Promise<Result<LivenessDetectionResult>>;
+    /**
+     * 开始活体检测会话
+     * @param type 活体检测类型
+     */
+    startSession(type?: LivenessDetectionType): Result<LivenessSession>;
+    /**
+     * 停止当前会话
+     */
+    stopSession(): void;
+    /**
+     * 获取当前活体检测会话
+     */
+    getCurrentSession(): LivenessSession | null;
+    /**
+     * 开始实时处理
+     * @param videoElement 视频元素
+     * @param options 处理选项
+     */
+    startRealtime(videoElement?: HTMLVideoElement, options?: Record<string, any>): Promise<Result<boolean>>;
+    /**
+     * 停止实时处理
+     */
+    stopRealtime(): void;
+    /**
+     * 释放资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 处理摄像头帧
+     */
+    private handleCameraFrame;
+    /**
+     * 处理视频帧
+     */
+    private processFrame;
+    /**
+     * 处理人脸检测结果
+     */
+    private handleFaceDetectionResult;
+    /**
+     * 处理被动式活体检测
+     */
+    private handlePassiveLivenessDetection;
+    /**
+     * 处理主动式活体检测
+     */
+    private handleActiveLivenessDetection;
+    /**
+     * 处理混合式活体检测
+     */
+    private handleHybridLivenessDetection;
+    /**
+     * 执行被动式活体检测
+     */
+    private performPassiveLivenessDetection;
+    /**
+     * 添加检测结果到历史记录
+     */
+    private addToHistory;
+    /**
+     * 计算眼睛纵横比(EAR)
+     * EAR是一种度量眼睛开合程度的指标
+     */
+    private calculateEyeAspectRatio;
+    /**
+     * 计算两点之间的距离
+     */
+    private distance;
+    /**
+     * 检测眨眼动作
+     */
+    private detectBlink;
+    /**
+     * 检测点头动作
+     */
+    private detectNod;
+    /**
+     * 检测摇头动作
+     */
+    private detectHeadShake;
+    /**
+     * 检测微笑动作
+     */
+    private detectSmile;
+    /**
+     * 检测张嘴动作
+     */
+    private detectMouthOpen;
+}
+export {};