id-scanner-lib 1.6.7 → 1.7.0

package/src/modules/face/face-model-loader.ts

@@ -0,0 +1,222 @@
+/**
+ * @file 人脸模型加载器
+ * @description 统一管理 face-api 模型的懒加载和缓存
+ * @module modules/face/face-model-loader
+ */
+
+import * as faceapi from '@vladmandic/face-api';
+import { Logger } from '../../core/logger';
+import { ResourceLoadError } from '../../core/errors';
+import { FaceModelType } from './face-detector';
+
+/**
+ * 已加载模型记录
+ */
+interface LoadedModelRecord {
+  /** 模型名称 */
+  name: string;
+  /** 加载时间戳 */
+  loadedAt: number;
+}
+
+/**
+ * 模型加载器配置
+ */
+export interface ModelLoaderConfig {
+  /** 模型路径 */
+  modelPath: string;
+  /** 检测模型类型 */
+  detectionModel: FaceModelType;
+  /** 关键点模型类型 */
+  landmarksModel: 'tiny' | '68_points';
+  /** 是否检测关键点 */
+  detectLandmarks: boolean;
+  /** 是否检测表情 */
+  detectExpressions: boolean;
+  /** 是否检测年龄和性别 */
+  detectAgeGender: boolean;
+  /** 是否提取人脸特征向量 */
+  extractEmbeddings: boolean;
+}
+
+/**
+ * 人脸模型加载器
+ *
+ * 负责按需加载 face-api 模型，避免一次性加载所有模型造成内存浪费
+ */
+export class FaceModelLoader {
+  /** 日志记录器 */
+  private logger: Logger;
+
+  /** 已加载模型集合 */
+  private loadedModels: Set<string> = new Set();
+
+  /** 模型是否已全部加载 */
+  private modelsLoaded: boolean = false;
+
+  /** 配置 */
+  private config: ModelLoaderConfig;
+
+  /**
+   * 构造函数
+   * @param config 模型加载配置
+   */
+  constructor(config: ModelLoaderConfig) {
+    this.logger = Logger.getInstance();
+    this.config = config;
+  }
+
+  /**
+   * 获取检测模型选项
+   */
+  private getDetectorOptions(minConfidence: number): faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions {
+    switch (this.config.detectionModel) {
+      case FaceModelType.SSD_MOBILENET:
+        return new faceapi.SsdMobilenetv1Options({ minConfidence });
+      case FaceModelType.TINY_FACE:
+        return new faceapi.TinyFaceDetectorOptions({ scoreThreshold: minConfidence });
+      case FaceModelType.MTCNN:
+        return new faceapi.MtcnnOptions({ minConfidence });
+      default:
+        return new faceapi.SsdMobilenetv1Options({ minConfidence });
+    }
+  }
+
+  /**
+   * 懒加载单个模型
+   * @param modelType 模型类型
+   * @param modelPath 模型路径
+   */
+  async lazyLoadModel(modelType: string, modelPath: string): Promise<void> {
+    if (this.loadedModels.has(modelType)) {
+      return;
+    }
+
+    this.logger.info('FaceModelLoader', `懒加载模型: ${modelType}`);
+
+    try {
+      switch (modelType) {
+        case 'ssdMobilenetv1':
+          await faceapi.nets.ssdMobilenetv1.loadFromUri(modelPath);
+          break;
+        case 'tinyFaceDetector':
+          await faceapi.nets.tinyFaceDetector.loadFromUri(modelPath);
+          break;
+        case 'faceLandmark68Net':
+          await faceapi.nets.faceLandmark68Net.loadFromUri(modelPath);
+          break;
+        case 'faceLandmark68TinyNet':
+          await faceapi.nets.faceLandmark68TinyNet.loadFromUri(modelPath);
+          break;
+        case 'faceExpressionNet':
+          await faceapi.nets.faceExpressionNet.loadFromUri(modelPath);
+          break;
+        case 'ageGenderNet':
+          await faceapi.nets.ageGenderNet.loadFromUri(modelPath);
+          break;
+        case 'faceRecognitionNet':
+          await faceapi.nets.faceRecognitionNet.loadFromUri(modelPath);
+          break;
+        default:
+          this.logger.warn('FaceModelLoader', `未知模型类型: ${modelType}`);
+          return;
+      }
+
+      this.loadedModels.add(modelType);
+      this.logger.info('FaceModelLoader', `模型加载完成: ${modelType}`);
+    } catch (error) {
+      this.logger.error('FaceModelLoader', `模型加载失败: ${modelType}`, error as Error);
+      throw new ResourceLoadError(modelType, `模型加载失败: ${error}`);
+    }
+  }
+
+  /**
+   * 根据需求加载模型
+   * @param options 检测选项
+   */
+  async loadModelsOnDemand(options: {
+    withLandmarks?: boolean;
+    withAttributes?: boolean;
+    withEmbedding?: boolean;
+  }): Promise<void> {
+    const { modelPath, landmarksModel, detectExpressions, detectAgeGender, extractEmbeddings } = this.config;
+
+    // 基础检测模型
+    const detectionModelKey = this.config.detectionModel === FaceModelType.TINY_FACE
+      ? 'tinyFaceDetector'
+      : 'ssdMobilenetv1';
+    await this.lazyLoadModel(detectionModelKey, modelPath);
+
+    // 关键点模型
+    if (options.withLandmarks || this.config.detectLandmarks) {
+      await this.lazyLoadModel(
+        landmarksModel === '68_points' ? 'faceLandmark68Net' : 'faceLandmark68TinyNet',
+        modelPath
+      );
+    }
+
+    // 表情模型
+    if (options.withAttributes || detectExpressions) {
+      await this.lazyLoadModel('faceExpressionNet', modelPath);
+    }
+
+    // 年龄性别模型
+    if (options.withAttributes || detectAgeGender) {
+      await this.lazyLoadModel('ageGenderNet', modelPath);
+    }
+
+    // 人脸识别模型
+    if (options.withEmbedding || extractEmbeddings) {
+      await this.lazyLoadModel('faceRecognitionNet', modelPath);
+    }
+
+    this.modelsLoaded = true;
+  }
+
+  /**
+   * 确保模型已加载（用于需要所有模型的场景）
+   */
+  async ensureModelsLoaded(): Promise<void> {
+    if (this.modelsLoaded) return;
+    await this.loadModelsOnDemand({});
+  }
+
+  /**
+   * 获取模型加载状态
+   */
+  isModelsLoaded(): boolean {
+    return this.modelsLoaded;
+  }
+
+  /**
+   * 获取已加载模型列表
+   */
+  getLoadedModels(): string[] {
+    return Array.from(this.loadedModels);
+  }
+
+  /**
+   * 释放所有模型（释放 TensorFlow.js 内存）
+   */
+  async dispose(): Promise<void> {
+    if (this.loadedModels.size > 0) {
+      try {
+        // face-api 使用 TensorFlow.js，需要显式释放
+        const tf = await import('@tensorflow/tfjs');
+        tf.dispose();
+        this.loadedModels.clear();
+        this.modelsLoaded = false;
+        this.logger.debug('FaceModelLoader', '模型资源已释放');
+      } catch (error) {
+        this.logger.error('FaceModelLoader', `释放模型失败: ${error}`);
+      }
+    }
+  }
+
+  /**
+   * 获取检测器选项（用于 detectAllFaces）
+   */
+  getFaceDetectionOptions(minConfidence: number): faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions {
+    return this.getDetectorOptions(minConfidence);
+  }
+}

package/src/modules/face/face-result-converter.ts

@@ -0,0 +1,225 @@
+/**
+ * @file 人脸检测结果转换器
+ * @description 将 face-api 检测结果转换为标准格式
+ * @module modules/face/face-result-converter
+ */
+
+import { FaceDetectionResult, Rect } from '../../interfaces/face-detection';
+import { generateUUID } from '../../utils';
+
+/**
+ * 人脸关键点索引（对应 face-api 的 68 点模型）
+ */
+export const FaceLandmarkIndex = {
+  LEFT_EYE: 36,
+  RIGHT_EYE: 45,
+  NOSE: 30,
+  MOUTH_CENTER: 57
+} as const;
+
+/**
+ * face-api 原始检测结果
+ */
+export interface RawFaceDetection {
+  /** 检测框 */
+  detection?: {
+    box?: { x?: number; y?: number; width?: number; height?: number };
+    score?: number;
+  };
+  /** 关键点 */
+  landmarks?: {
+    positions: Array<{ x: number; y: number }>;
+  };
+  /** 表情 */
+  expressions?: {
+    angry?: number;
+    disgusted?: number;
+    fearful?: number;
+    happy?: number;
+    neutral?: number;
+    sad?: number;
+    surprised?: number;
+  };
+  /** 年龄 */
+  age?: number;
+  /** 性别 */
+  gender?: string;
+  /** 性别概率 */
+  genderProbability?: number;
+  /** 人脸描述符（特征向量） */
+  descriptor?: Float32Array | number[];
+}
+
+/**
+ * 结果转换器配置
+ */
+export interface ResultConverterConfig {
+  /** 是否检测关键点 */
+  detectLandmarks: boolean;
+  /** 关键点模型类型 */
+  landmarksModel: 'tiny' | '68_points';
+  /** 是否检测表情 */
+  detectExpressions: boolean;
+  /** 是否检测年龄和性别 */
+  detectAgeGender: boolean;
+  /** 是否提取特征向量 */
+  extractEmbeddings: boolean;
+}
+
+/**
+ * 人脸检测结果转换器
+ *
+ * 负责将 face-api 原始检测结果转换为标准格式
+ */
+export class FaceResultConverter {
+  /** 配置 */
+  private config: ResultConverterConfig;
+
+  /**
+   * 构造函数
+   * @param config 转换器配置
+   */
+  constructor(config: ResultConverterConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 批量转换检测结果
+   * @param detections 原始检测结果数组
+   * @param options 检测选项
+   * @param processingTime 处理时间
+   * @returns 标准化检测结果
+   */
+  convertBatch(
+    detections: RawFaceDetection[],
+    options: {
+      maxFaces?: number;
+      enableTracking?: boolean;
+    },
+    processingTime: number
+  ): FaceDetectionResult[] {
+    // 限制检测数量
+    const maxFaces = options.maxFaces || 10;
+    const limitedDetections = detections.slice(0, maxFaces);
+
+    const results: FaceDetectionResult[] = [];
+
+    for (const detection of limitedDetections) {
+      const result = this.convertSingle(detection, processingTime);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * 转换单个检测结果
+   * @param detection 原始检测结果
+   * @param processingTime 处理时间
+   * @returns 标准化检测结果
+   */
+  convertSingle(detection: RawFaceDetection, processingTime: number): FaceDetectionResult {
+    // 转换边界框
+    const boundingBox: Rect = {
+      x: detection.detection?.box?.x || 0,
+      y: detection.detection?.box?.y || 0,
+      width: detection.detection?.box?.width || 0,
+      height: detection.detection?.box?.height || 0
+    };
+
+    // 创建基本结果
+    const result: FaceDetectionResult = {
+      id: generateUUID(),
+      type: 'face',
+      boundingBox,
+      confidence: detection.detection?.score || 0,
+      processingTime,
+      timestamp: Date.now()
+    };
+
+    // 转换关键点
+    if (detection.landmarks && this.config.detectLandmarks) {
+      result.landmarks = this.convertLandmarks(detection.landmarks);
+    }
+
+    // 转换表情属性
+    if (detection.expressions && this.config.detectExpressions) {
+      result.attributes = {
+        ...result.attributes,
+        emotion: {
+          angry: detection.expressions.angry || 0,
+          disgust: detection.expressions.disgusted || 0,
+          fear: detection.expressions.fearful || 0,
+          happy: detection.expressions.happy || 0,
+          neutral: detection.expressions.neutral || 0,
+          sad: detection.expressions.sad || 0,
+          surprise: detection.expressions.surprised || 0
+        }
+      };
+    }
+
+    // 转换年龄
+    if (detection.age !== undefined && this.config.detectAgeGender) {
+      result.attributes = {
+        ...result.attributes,
+        age: detection.age
+      };
+    }
+
+    // 转换性别
+    if (detection.gender !== undefined && detection.genderProbability !== undefined && this.config.detectAgeGender) {
+      result.attributes = {
+        ...result.attributes,
+        gender: detection.gender === 'male' ? detection.genderProbability : 1 - detection.genderProbability
+      };
+    }
+
+    // 转换特征向量
+    if (detection.descriptor && this.config.extractEmbeddings) {
+      result.embedding = {
+        vector: Array.from(detection.descriptor),
+        dimension: detection.descriptor.length
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * 转换关键点
+   */
+  private convertLandmarks(landmarks: RawFaceDetection['landmarks']): FaceDetectionResult['landmarks'] {
+    if (!landmarks || !landmarks.positions) {
+      return undefined as any;
+    }
+
+    const positions = landmarks.positions;
+
+    return {
+      leftEye: {
+        x: positions[FaceLandmarkIndex.LEFT_EYE].x,
+        y: positions[FaceLandmarkIndex.LEFT_EYE].y
+      },
+      rightEye: {
+        x: positions[FaceLandmarkIndex.RIGHT_EYE].x,
+        y: positions[FaceLandmarkIndex.RIGHT_EYE].y
+      },
+      nose: {
+        x: positions[FaceLandmarkIndex.NOSE].x,
+        y: positions[FaceLandmarkIndex.NOSE].y
+      },
+      mouth: {
+        x: positions[FaceLandmarkIndex.MOUTH_CENTER].x,
+        y: positions[FaceLandmarkIndex.MOUTH_CENTER].y
+      },
+      points: positions.map((p) => ({ x: p.x, y: p.y }))
+    };
+  }
+
+  /**
+   * 更新配置
+   */
+  updateConfig(config: Partial<ResultConverterConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+}

package/src/modules/face/face-tracker.ts

@@ -0,0 +1,207 @@
+/**
+ * @file 人脸跟踪器
+ * @description 提供人脸跟踪功能，基于 IOU 匹配算法
+ * @module modules/face/face-tracker
+ */
+
+import { FaceDetectionResult, Rect } from '../../interfaces/face-detection';
+import { generateUUID } from '../../utils';
+
+/**
+ * 人脸跟踪状态
+ */
+interface FaceTrackerState {
+  /** 跟踪ID */
+  trackId: string;
+  /** 最后检测到的时间戳 */
+  lastSeen: number;
+  /** 检测结果 */
+  detection: FaceDetectionResult;
+  /** 连续跟踪帧数 */
+  consecutiveFrames: number;
+}
+
+/**
+ * 人脸跟踪器配置
+ */
+export interface FaceTrackerConfig {
+  /** 跟踪超时时间(ms)，超过此时间未检测到则移除 */
+  trackTimeout?: number;
+  /** 匹配阈值，值越小越严格 */
+  matchThreshold?: number;
+}
+
+/**
+ * 人脸跟踪器
+ *
+ * 基于 IOU（交并比）和中心点距离的人脸跟踪算法
+ */
+export class FaceTracker {
+  /** 跟踪状态映射 */
+  private trackers: Map<string, FaceTrackerState> = new Map();
+
+  /** 配置 */
+  private config: Required<FaceTrackerConfig>;
+
+  /**
+   * 构造函数
+   * @param config 跟踪器配置
+   */
+  constructor(config: FaceTrackerConfig = {}) {
+    this.config = {
+      trackTimeout: config.trackTimeout ?? 1000,
+      matchThreshold: config.matchThreshold ?? 0.3
+    };
+  }
+
+  /**
+   * 计算两个矩形的 IOU（交并比）
+   */
+  private computeIOU(a: Rect, b: Rect): number {
+    const x1 = Math.max(a.x, b.x);
+    const y1 = Math.max(a.y, b.y);
+    const x2 = Math.min(a.x + a.width, b.x + b.width);
+    const y2 = Math.min(a.y + a.height, b.y + b.height);
+
+    if (x2 <= x1 || y2 <= y1) {
+      return 0;
+    }
+
+    const intersection = (x2 - x1) * (y2 - y1);
+    const areaA = a.width * a.height;
+    const areaB = b.width * b.height;
+    const union = areaA + areaB - intersection;
+
+    return union > 0 ? intersection / union : 0;
+  }
+
+  /**
+   * 计算两个矩形的中心点距离
+   */
+  private computeCenterDistance(a: Rect, b: Rect): number {
+    const centerA = {
+      x: a.x + a.width / 2,
+      y: a.y + a.height / 2
+    };
+    const centerB = {
+      x: b.x + b.width / 2,
+      y: b.y + b.height / 2
+    };
+
+    return Math.sqrt(
+      Math.pow(centerA.x - centerB.x, 2) +
+      Math.pow(centerA.y - centerB.y, 2)
+    );
+  }
+
+  /**
+   * 匹配检测结果到现有跟踪器
+   * @param detections 当前帧的检测结果
+   * @returns 更新后的跟踪结果（带有 trackId）
+   */
+  update(detections: FaceDetectionResult[]): FaceDetectionResult[] {
+    const now = Date.now();
+    const results: FaceDetectionResult[] = [];
+
+    // 清理过期的跟踪器
+    for (const [id, tracker] of this.trackers) {
+      if (now - tracker.lastSeen > this.config.trackTimeout) {
+        this.trackers.delete(id);
+      }
+    }
+
+    // 标记所有检测结果为"未匹配"
+    const unmatchedDetections = [...detections];
+
+    // 尝试将检测结果匹配到现有跟踪器
+    for (const [trackId, tracker] of this.trackers) {
+      let bestMatchIdx = -1;
+      let bestScore = Infinity;
+
+      for (let i = 0; i < unmatchedDetections.length; i++) {
+        const detection = unmatchedDetections[i];
+        const iou = this.computeIOU(tracker.detection.boundingBox, detection.boundingBox);
+        const centerDist = this.computeCenterDistance(
+          tracker.detection.boundingBox,
+          detection.boundingBox
+        );
+
+        // 计算综合分数：IOU 权重 0.4，中心距离权重 0.6
+        const maxDim = Math.max(detection.boundingBox.width, detection.boundingBox.height);
+        const score = iou * 0.4 + (1 - centerDist / (maxDim * 2)) * 0.6;
+
+        if (score > 0.5 && score < bestScore) {
+          bestScore = score;
+          bestMatchIdx = i;
+        }
+      }
+
+      if (bestMatchIdx !== -1) {
+        // 匹配成功，更新跟踪器
+        const matched = unmatchedDetections[bestMatchIdx];
+        matched.trackId = trackId;
+        results.push(matched);
+
+        // 更新跟踪状态
+        tracker.lastSeen = now;
+        tracker.detection = matched;
+        tracker.consecutiveFrames++;
+
+        // 移除已匹配的检测
+        unmatchedDetections.splice(bestMatchIdx, 1);
+      }
+    }
+
+    // 剩余未匹配的检测创建新的跟踪器
+    for (const detection of unmatchedDetections) {
+      const trackId = generateUUID();
+      detection.trackId = trackId;
+      results.push(detection);
+
+      this.trackers.set(trackId, {
+        trackId,
+        lastSeen: now,
+        detection,
+        consecutiveFrames: 1
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * 获取当前跟踪状态
+   */
+  getTrackerStates(): Map<string, FaceTrackerState> {
+    return this.trackers;
+  }
+
+  /**
+   * 获取活跃跟踪器数量
+   */
+  getActiveCount(): number {
+    const now = Date.now();
+    let count = 0;
+    for (const [, tracker] of this.trackers) {
+      if (now - tracker.lastSeen <= this.config.trackTimeout) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * 重置跟踪器
+   */
+  reset(): void {
+    this.trackers.clear();
+  }
+
+  /**
+   * 移除指定跟踪器
+   * @param trackId 跟踪ID
+   */
+  remove(trackId: string): boolean {
+    return this.trackers.delete(trackId);
+  }
+}

package/src/modules/face/liveness-detector.ts

@@ -308,7 +308,7 @@ export class LivenessDetector extends BaseScannerModule {
         id: this.currentSession.id,
         requiredActions
       }
-    } as any);
+    });
     
     return Result.success(this.currentSession);
   }
@@ -327,7 +327,7 @@ export class LivenessDetector extends BaseScannerModule {
           id: this.currentSession.id,
           status: this.currentSession.status
         }
-      } as any );
+      });
       
       this.currentSession = null;
     }