id-scanner-lib 1.3.2 → 1.5.0

package/dist/types/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @file 主入口文件
+ * @description ID Scanner库的主入口点，提供统一的API和模块导出
+ * @module index
+ */
+import { IDCardModule } from './modules/id-card';
+import { QRCodeModule } from './modules/qrcode';
+import { FaceModule } from './modules/face';
+import { LogLevel } from './core/logger';
+import { IDCardModuleOptions } from './modules/id-card/types';
+import { QRCodeModuleOptions } from './modules/qrcode/types';
+import { FaceModuleOptions } from './modules/face/types';
+/**
+ * IDScanner配置选项
+ */
+export interface IDScannerOptions {
+    /** 日志级别 */
+    logLevel?: LogLevel;
+    /** 是否启用身份证识别模块 */
+    enableIDCard?: boolean;
+    /** 是否启用二维码识别模块 */
+    enableQRCode?: boolean;
+    /** 是否启用人脸识别模块 */
+    enableFace?: boolean;
+    /** 身份证模块配置 */
+    idCard?: IDCardModuleOptions;
+    /** 二维码模块配置 */
+    qrCode?: QRCodeModuleOptions;
+    /** 人脸识别模块配置 */
+    face?: FaceModuleOptions;
+}
+/**
+ * IDScanner类
+ * 提供整合的身份证、二维码和人脸识别功能
+ */
+export declare class IDScanner {
+    /** 版本号 */
+    static readonly VERSION = "1.5.0";
+    /** 构建日期 */
+    static readonly BUILD_DATE: string;
+    /** 模块管理器 */
+    private moduleManager;
+    /** 是否已经初始化 */
+    private initialized;
+    /** 日志工具 */
+    private logger;
+    /**
+     * 构造函数
+     * @param options 配置选项
+     */
+    constructor(options?: IDScannerOptions);
+    /**
+     * 初始化库
+     */
+    initialize(): Promise<void>;
+    /**
+     * 获取身份证模块实例
+     * @returns 身份证模块
+     */
+    getIDCardModule(): IDCardModule | undefined;
+    /**
+     * 获取二维码模块实例
+     * @returns 二维码模块
+     */
+    getQRCodeModule(): QRCodeModule | undefined;
+    /**
+     * 获取人脸识别模块实例
+     * @returns 人脸识别模块
+     */
+    getFaceModule(): FaceModule | undefined;
+    /**
+     * 释放所有资源
+     */
+    dispose(): Promise<void>;
+}
+export * from './core/module-manager';
+export * from './core/logger';
+export * from './core/errors';
+export { IDCardModule } from './modules/id-card';
+export { QRCodeModule } from './modules/qrcode';
+export { FaceModule } from './modules/face';
+export * from './utils/types';
+export { IDCardModuleOptions, IDCardInfo, IDCardType, IDCardVerificationResult } from './modules/id-card/types';
+export { QRCodeModuleOptions, QRCodeResult } from './modules/qrcode/types';
+export { FaceModuleOptions, FaceDetectionResult, FaceComparisonResult } from './modules/face/types';
+export default IDScanner;

package/dist/types/interfaces/external-types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @file 外部库类型声明
+ * @description 为外部依赖库声明类型定义
+ */
+/**
+ * TensorFlow.js 相关类型
+ */
+declare module '@tensorflow/tfjs' {
+    interface Tensor<R extends Rank = Rank> {
+        dataId: object;
+        id: number;
+        shape: number[];
+        dtype: string;
+        size: number;
+        rank: number;
+        dispose(): void;
+    }
+    type Rank = 'R0' | 'R1' | 'R2' | 'R3' | 'R4' | 'R5' | 'R6';
+    function ready(): Promise<void>;
+    function dispose(): void;
+}
+/**
+ * face-api.js 相关类型
+ */
+declare module '@vladmandic/face-api' {
+    namespace tf {
+        function dispose(): Promise<void>;
+    }
+    namespace env {
+        function monkeyPatch(env: any): void;
+    }
+    type TNetInput = HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | ImageData | {
+        toString(): string;
+    } | string;
+    interface FaceDetectionWithLandmarks {
+        detection: FaceDetection;
+        landmarks: FaceLandmarks68 | FaceLandmarks68TinyNet;
+        getRefRect(): any;
+        forwardFaceDetection(): FaceDetection;
+    }
+    interface WithFaceDescriptor<T> {
+        descriptor: Float32Array;
+    }
+    interface WithAge {
+        age: number;
+    }
+    interface WithGender {
+        gender: string;
+        genderProbability: number;
+    }
+    interface FaceMatch {
+        label: string;
+        distance: number;
+    }
+    interface WithFaceExpressions {
+        expressions: {
+            neutral: number;
+            happy: number;
+            sad: number;
+            angry: number;
+            fearful: number;
+            disgusted: number;
+            surprised: number;
+        };
+    }
+    interface IFaceLandmarks {
+        positions: Point[];
+        shift(point: Point): IFaceLandmarks;
+        forSize<T extends IFaceLandmarks>(width: number, height: number): T;
+    }
+    interface IRect {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }
+    interface IBoundingBox extends IRect {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    }
+    interface IFaceDetection {
+        score: number;
+        box: IBoundingBox;
+    }
+    class Point {
+        x: number;
+        y: number;
+        constructor(x: number, y: number);
+    }
+    class FaceDetection implements IFaceDetection {
+        score: number;
+        box: IBoundingBox;
+        constructor(score: number, box: IBoundingBox);
+    }
+    class FaceLandmarks68 implements IFaceLandmarks {
+        positions: Point[];
+        constructor(points: Point[]);
+        shift(point: Point): FaceLandmarks68;
+        forSize<T extends IFaceLandmarks>(width: number, height: number): T;
+    }
+    class FaceLandmarks68TinyNet extends FaceLandmarks68 {
+        constructor(points: Point[]);
+    }
+    class SsdMobilenetv1Options {
+        constructor(options?: {
+            minConfidence?: number;
+            maxResults?: number;
+        });
+    }
+    class TinyFaceDetectorOptions {
+        constructor(options?: {
+            inputSize?: number;
+            scoreThreshold?: number;
+        });
+    }
+    class MtcnnOptions {
+        constructor(options?: {
+            minFaceSize?: number;
+            scaleFactor?: number;
+            minConfidence?: number;
+        });
+    }
+    class FaceRecognitionNet {
+        constructor();
+        loadFromUri(uri: string): Promise<void>;
+    }
+    class FaceExpressionNet {
+        constructor();
+        loadFromUri(uri: string): Promise<void>;
+    }
+    class AgeGenderNet {
+        constructor();
+        loadFromUri(uri: string): Promise<void>;
+    }
+    interface NeuralNetwork {
+        loadFromUri(uri: string): Promise<void>;
+        isLoaded: boolean;
+        dispose(): void;
+    }
+    const nets: {
+        ssdMobilenetv1: NeuralNetwork;
+        tinyFaceDetector: NeuralNetwork;
+        faceLandmark68Net: NeuralNetwork;
+        faceLandmark68TinyNet: NeuralNetwork;
+        faceRecognitionNet: NeuralNetwork;
+        faceExpressionNet: NeuralNetwork;
+        ageGenderNet: NeuralNetwork;
+        mtcnn: NeuralNetwork;
+    };
+    function createCanvasFromMedia(media: TNetInput): HTMLCanvasElement;
+    function detectAllFaces(input: TNetInput, options?: SsdMobilenetv1Options | TinyFaceDetectorOptions | MtcnnOptions): DetectAllFacesTask;
+    interface DetectAllFacesTask {
+        withFaceLandmarks(useTinyModel?: boolean): DetectAllFacesWithLandmarksTask;
+        run(): Promise<FaceDetection[]>;
+    }
+    interface DetectAllFacesWithLandmarksTask {
+        withFaceExpressions(): DetectAllFacesWithFaceExpressionsTask;
+        withAgeAndGender(): DetectAllFacesWithAgeAndGenderTask;
+        run(): Promise<FaceDetectionWithLandmarks[]>;
+    }
+    interface DetectAllFacesWithFaceExpressionsTask {
+        withAgeAndGender(): DetectAllFacesWithAgeAndGenderTask;
+        run(): Promise<Array<FaceDetectionWithLandmarks & WithFaceExpressions>>;
+    }
+    interface DetectAllFacesWithAgeAndGenderTask {
+        withFaceDescriptors(): DetectAllFacesWithFaceDescriptorsTask;
+        run(): Promise<Array<FaceDetectionWithLandmarks & WithFaceExpressions & WithAge & WithGender>>;
+    }
+    interface DetectAllFacesWithFaceDescriptorsTask {
+        run(): Promise<Array<FaceDetectionWithLandmarks & WithFaceExpressions & WithAge & WithGender & WithFaceDescriptor<any>>>;
+    }
+}

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

@@ -0,0 +1,293 @@
+/**
+ * @file 人脸检测接口
+ * @description 定义人脸检测相关的数据类型和接口
+ * @module interfaces/face-detection
+ */
+import { BaseScannerResult } from './scanner-module';
+/**
+ * 坐标点接口，表示2D坐标
+ */
+export interface Point {
+    /** X坐标 */
+    x: number;
+    /** Y坐标 */
+    y: number;
+}
+/**
+ * 矩形接口，表示检测框
+ */
+export interface Rect {
+    /** 左上角X坐标 */
+    x: number;
+    /** 左上角Y坐标 */
+    y: number;
+    /** 宽度 */
+    width: number;
+    /** 高度 */
+    height: number;
+}
+/**
+ * 人脸关键点
+ */
+export interface FaceLandmarks {
+    /** 左眼位置 */
+    leftEye: Point;
+    /** 右眼位置 */
+    rightEye: Point;
+    /** 鼻尖位置 */
+    nose: Point;
+    /** 嘴巴中心位置 */
+    mouth: Point;
+    /** 左眼角位置 */
+    leftEyeOuterCorner?: Point;
+    /** 右眼角位置 */
+    rightEyeOuterCorner?: Point;
+    /** 左耳位置 */
+    leftEar?: Point;
+    /** 右耳位置 */
+    rightEar?: Point;
+    /** 所有关键点（有些实现可能提供更多点） */
+    points?: Point[];
+}
+/**
+ * 人脸角度
+ */
+export interface FaceAngle {
+    /** 俯仰角(上下) */
+    pitch: number;
+    /** 偏航角(左右) */
+    yaw: number;
+    /** 滚动角(倾斜) */
+    roll: number;
+}
+/**
+ * 人脸质量评估指标
+ */
+export interface FaceQualityMetrics {
+    /** 亮度评分(0-1) */
+    brightness: number;
+    /** 清晰度评分(0-1) */
+    sharpness: number;
+    /** 姿态合规程度(0-1) */
+    pose: number;
+    /** 人脸完整度(0-1) */
+    integrity: number;
+    /** 整体质量分数(0-1) */
+    overall: number;
+}
+/**
+ * 人脸属性
+ */
+export interface FaceAttributes {
+    /** 年龄估计(岁) */
+    age?: number;
+    /** 性别置信度(0-1，越大越倾向于男性) */
+    gender?: number;
+    /** 是否戴眼镜置信度 */
+    glasses?: number;
+    /** 是否戴口罩置信度 */
+    mask?: number;
+    /** 微笑程度置信度 */
+    smile?: number;
+    /** 人脸表情分类 */
+    emotion?: {
+        /** 生气程度 */
+        angry?: number;
+        /** 恐惧程度 */
+        fear?: number;
+        /** 厌恶程度 */
+        disgust?: number;
+        /** 高兴程度 */
+        happy?: number;
+        /** 平静程度 */
+        neutral?: number;
+        /** 伤心程度 */
+        sad?: number;
+        /** 惊讶程度 */
+        surprise?: number;
+    };
+    /** 人种类别置信度 */
+    ethnicity?: {
+        /** 亚洲人程度 */
+        asian?: number;
+        /** 黑人程度 */
+        black?: number;
+        /** 白人程度 */
+        caucasian?: number;
+        /** 其他人种程度 */
+        other?: number;
+    };
+    /** 其他自定义属性 */
+    [key: string]: any;
+}
+/**
+ * 人脸特征向量（人脸嵌入）
+ */
+export interface FaceEmbedding {
+    /** 特征向量数据 */
+    vector: number[];
+    /** 特征维度 */
+    dimension: number;
+    /** 模型版本 */
+    modelVersion?: string;
+}
+/**
+ * 人脸检测结果
+ */
+export interface FaceDetectionResult extends BaseScannerResult {
+    /** 人脸区域 */
+    boundingBox: Rect;
+    /** 人脸关键点 */
+    landmarks?: FaceLandmarks;
+    /** 人脸角度 */
+    angle?: FaceAngle;
+    /** 检测质量 */
+    quality?: FaceQualityMetrics;
+    /** 人脸属性 */
+    attributes?: FaceAttributes;
+    /** 人脸特征向量 */
+    embedding?: FaceEmbedding;
+    /** 相似度分数（用于比对场景） */
+    similarityScore?: number;
+    /** 是否有活体检测结果 */
+    isLive?: boolean;
+    /** 活体检测分数(0-1) */
+    livenessScore?: number;
+    /** 标识符（可用于跟踪） */
+    trackId?: string;
+    /** 人脸图像数据（裁剪后） */
+    faceImageData?: string;
+}
+/**
+ * 人脸比对结果
+ */
+export interface FaceComparisonResult {
+    /** 相似度分数(0-1) */
+    similarity: number;
+    /** 是否匹配（基于阈值判断） */
+    isMatch: boolean;
+    /** 使用的阈值 */
+    threshold: number;
+    /** 源人脸 */
+    sourceFace?: FaceDetectionResult;
+    /** 目标人脸 */
+    targetFace?: FaceDetectionResult;
+    /** 处理时间(毫秒) */
+    processingTime: number;
+}
+/**
+ * 活体检测类型
+ */
+export declare enum LivenessDetectionType {
+    /** 被动活体检测（单图分析） */
+    PASSIVE = "passive",
+    /** 主动活体检测（动作挑战） */
+    ACTIVE = "active",
+    /** 混合活体检测（结合多种方法） */
+    HYBRID = "hybrid"
+}
+/**
+ * 活体检测动作类型
+ */
+export declare enum LivenessAction {
+    /** 眨眼 */
+    BLINK = "blink",
+    /** 点头 */
+    NOD = "nod",
+    /** 摇头 */
+    SHAKE = "shake",
+    /** 微笑 */
+    SMILE = "smile",
+    /** 张嘴 */
+    MOUTH_OPEN = "mouth_open",
+    /** 注视点 */
+    GAZE = "gaze"
+}
+/**
+ * 活体检测结果
+ */
+export interface LivenessDetectionResult {
+    /** 是否为真人 */
+    isLive: boolean;
+    /** 活体分数(0-1) */
+    score: number;
+    /** 使用的活体检测类型 */
+    type: LivenessDetectionType;
+    /** 活体检测动作（如果使用了主动活体检测） */
+    actions?: LivenessAction[];
+    /** 检测时间(毫秒) */
+    processingTime: number;
+    /** 检测结果图片 */
+    imageData?: string;
+}
+/**
+ * 活体检测会话
+ */
+export interface LivenessSession {
+    /** 会话ID */
+    id: string;
+    /** 活体检测类型 */
+    type: LivenessDetectionType;
+    /** 需要完成的动作 */
+    requiredActions?: LivenessAction[];
+    /** 当前动作索引 */
+    currentActionIndex?: number;
+    /** 会话开始时间 */
+    startTime: number;
+    /** 会话超时时间(毫秒) */
+    timeout: number;
+    /** 会话状态 */
+    status: 'active' | 'completed' | 'failed' | 'timeout';
+    /** 完成的动作 */
+    completedActions?: LivenessAction[];
+    /** 活体检测结果 */
+    result?: LivenessDetectionResult;
+}
+/**
+ * 人脸跟踪结果
+ */
+export interface FaceTrackingResult {
+    /** 跟踪ID */
+    trackId: string;
+    /** 当前检测结果 */
+    detection: FaceDetectionResult;
+    /** 首次检测时间 */
+    firstDetectedAt: number;
+    /** 上次检测时间 */
+    lastDetectedAt: number;
+    /** 跟踪状态 */
+    status: 'tracked' | 'lost' | 'removed';
+    /** 连续跟踪帧数 */
+    consecutiveFrames: number;
+    /** 历史位置（最近几帧） */
+    history?: Rect[];
+}
+/**
+ * 人脸检测选项
+ */
+export interface FaceDetectionOptions {
+    /** 最低人脸置信度 */
+    minConfidence?: number;
+    /** 最大检测人脸数 */
+    maxFaces?: number;
+    /** 是否检测关键点 */
+    withLandmarks?: boolean;
+    /** 是否检测属性 */
+    withAttributes?: boolean;
+    /** 是否进行人脸对齐 */
+    doAlignment?: boolean;
+    /** 是否提取人脸特征 */
+    withEmbedding?: boolean;
+    /** 是否启用跟踪 */
+    enableTracking?: boolean;
+    /** 是否执行活体检测 */
+    withLiveness?: boolean;
+    /** 活体检测类型 */
+    livenessType?: LivenessDetectionType;
+    /** 返回人脸图像 */
+    returnFaceImage?: boolean;
+    /** 活体检测选项 */
+    livenessOptions?: Record<string, any>;
+    /** 其他选项 */
+    [key: string]: any;
+}