id-scanner-lib 1.3.2 → 1.5.0

package/src/interfaces/external-types.ts

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

package/src/interfaces/face-detection.ts

@@ -0,0 +1,309 @@
+/**
+ * @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 enum LivenessDetectionType {
+  /** 被动活体检测（单图分析） */
+  PASSIVE = 'passive',
+  /** 主动活体检测（动作挑战） */
+  ACTIVE = 'active',
+  /** 混合活体检测（结合多种方法） */
+  HYBRID = 'hybrid'
+}
+
+/**
+ * 活体检测动作类型
+ */
+export 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;
+}