id-scanner-lib 1.6.6 → 1.7.0

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

@@ -17,6 +17,11 @@ import { CameraManager, CameraEvent } from '../../core/camera-manager';
 import { Result } from '../../core/result';
 import { FaceDetectionError, FaceComparisonError, InitializationError, LivenessDetectionError, ResourceLoadError } from '../../core/errors';
 import { generateUUID } from '../../utils';
+import { FaceModelLoader } from './face-model-loader';
+import { FaceTracker } from './face-tracker';
+import { FaceComparator } from './face-comparator';
+import { FaceResultConverter } from './face-result-converter';
+import { FaceDetectorOptionsFactory } from './face-detector-options';
 
 /**
  * 人脸检测模型类型
@@ -106,66 +111,87 @@ export class FaceDetector extends BaseScannerModule {
     modelPath: '/models/face-api'
   };
   
-  /** 模型加载状态 */
-  private modelsLoaded: boolean = false;
-  private loadedModels: Set<string> = new Set();
-  
+  /** 模型加载器 */
+  private modelLoader: FaceModelLoader;
+
+  /** 人脸跟踪器 */
+  private faceTracker: FaceTracker;
+
+  /** 人脸比对器 */
+  private faceComparator: FaceComparator;
+
+  /** 结果转换器 */
+  private resultConverter: FaceResultConverter;
+
   /** 处理计时器ID */
   private processingTimerId: number | null = null;
-  
+
   /** 处理间隔(ms) */
   private processingInterval: number = 100;
-  
+
   /** 摄像头管理器 */
   private cameraManager: CameraManager;
-  
+
   /** 配置管理器 */
   private configManager: ConfigManager;
-  
+
   /** 资源管理器 */
   private resourceManager: ResourceManager;
-  
+
   /** 日志记录器 */
   private logger: Logger;
-  
+
   /** 画布元素，用于处理帧 */
   private canvas: HTMLCanvasElement;
-  
+
   /** 画布渲染上下文 */
   private canvasCtx: CanvasRenderingContext2D | null = null;
-  
+
   /** 最后一次检测结果 */
   private lastDetectionResult: FaceDetectionResult[] = [];
-  
-  /** 人脸跟踪状态 */
-  private faceTrackers: Map<string, {
-    trackId: string;
-    lastSeen: number;
-    detection: FaceDetectionResult;
-    consecutiveFrames: number;
-  }> = new Map();
-
-  /** 
+
+  /**
    * 构造函数
    * @param config 初始配置
    */
   constructor(config: Partial<FaceDetectorConfig> = {}) {
-    super({ 
-      enabled: true, 
-      ...config 
+    super({
+      enabled: true,
+      ...config
     });
-    
+
     this.configManager = ConfigManager.getInstance();
     this.cameraManager = CameraManager.getInstance();
     this.resourceManager = ResourceManager.getInstance();
     this.logger = Logger.getInstance();
-    
+
     // 合并配置
     this.config = {
       ...FaceDetector.DEFAULT_CONFIG,
       ...config
     };
-    
+
+    // 初始化组件
+    this.modelLoader = new FaceModelLoader({
+      modelPath: this.config.modelPath,
+      detectionModel: this.config.detectionModel,
+      landmarksModel: this.config.landmarksModel,
+      detectLandmarks: this.config.detectLandmarks,
+      detectExpressions: this.config.detectExpressions,
+      detectAgeGender: this.config.detectAgeGender,
+      extractEmbeddings: this.config.extractEmbeddings
+    });
+
+    this.faceTracker = new FaceTracker({ trackTimeout: 1000 });
+    this.faceComparator = new FaceComparator({ matchThreshold: this.config.matchThreshold });
+    this.resultConverter = new FaceResultConverter({
+      detectLandmarks: this.config.detectLandmarks,
+      landmarksModel: this.config.landmarksModel,
+      detectExpressions: this.config.detectExpressions,
+      detectAgeGender: this.config.detectAgeGender,
+      extractEmbeddings: this.config.extractEmbeddings
+    });
+
     // 创建画布
     this.canvas = document.createElement('canvas');
     this.canvasCtx = this.canvas.getContext('2d');
@@ -252,98 +278,34 @@ export class FaceDetector extends BaseScannerModule {
     }
   }
   
+  // ==================== 模型加载（委托给 FaceModelLoader） ====================
+
   /**
-   * 懒加载模型 - 仅在需要时加载特定模型
-   * @param modelType 模型类型
-   * @param modelPath 模型路径
+   * 懒加载模型 - 委托给 FaceModelLoader
+   * @deprecated 使用 modelLoader.lazyLoadModel 代替
    */
   private async lazyLoadModel(modelType: string, modelPath: string): Promise<void> {
-    // 检查模型是否已加载
-    const loadedModels = this.loadedModels || new Set();
-    if (loadedModels.has(modelType)) {
-      return;
-    }
-
-    this.logger.info('FaceDetector', `懒加载模型: ${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('FaceDetector', `未知模型类型: ${modelType}`);
-          return;
-      }
-
-      loadedModels.add(modelType);
-      this.loadedModels = loadedModels;
-      this.logger.info('FaceDetector', `模型加载完成: ${modelType}`);
-    } catch (error) {
-      this.logger.error('FaceDetector', `模型加载失败: ${modelType}`, error instanceof Error ? error : undefined);
-      throw new ResourceLoadError(modelType, `模型加载失败: ${error}`);
-    }
+    await this.modelLoader.lazyLoadModel(modelType, modelPath);
   }
 
   /**
-   * 根据需求加载模型
-   * @param options 检测选项
-   * @param modelPath 模型路径
+   * 根据需求加载模型 - 委托给 FaceModelLoader
+   * @deprecated 使用 modelLoader.loadModelsOnDemand 代替
    */
   private async loadModelsOnDemand(options: FaceDetectionOptions, modelPath: string): Promise<void> {
-    // 基础检测模型
-    await this.lazyLoadModel(this.config.detectionModel, modelPath);
-
-    // 关键点模型
-    if (options.withLandmarks || this.config.detectLandmarks) {
-      await this.lazyLoadModel(
-        this.config.landmarksModel === '68_points' ? 'faceLandmark68Net' : 'faceLandmark68TinyNet',
-        modelPath
-      );
-    }
-
-    // 表情模型
-    if (options.withExpressions || this.config.detectExpressions) {
-      await this.lazyLoadModel('faceExpressionNet', modelPath);
-    }
-
-    // 年龄性别模型
-    if (options.withAgeAndGender || this.config.detectAgeGender) {
-      await this.lazyLoadModel('ageGenderNet', modelPath);
-    }
-
-    // 人脸识别模型
-    if (options.withEmbedding || this.config.extractEmbeddings) {
-      await this.lazyLoadModel('faceRecognitionNet', modelPath);
-    }
-
-    this.modelsLoaded = true;
+    await this.modelLoader.loadModelsOnDemand({
+      withLandmarks: options.withLandmarks,
+      withAttributes: options.withAttributes,
+      withEmbedding: options.withEmbedding
+    });
   }
 
   /**
-   * 加载人脸检测模型 (旧版 - 保留兼容性)
-   * @param modelPath 模型路径
+   * 加载人脸检测模型 - 委托给 FaceModelLoader
+   * @deprecated 使用 modelLoader.ensureModelsLoaded 代替
    */
   private async loadModels(modelPath: string): Promise<void> {
-    await this.loadModelsOnDemand({}, modelPath);
+    await this.modelLoader.ensureModelsLoaded();
   }
   
   /**
@@ -492,7 +454,7 @@ export class FaceDetector extends BaseScannerModule {
     }
     
     // 清除人脸跟踪状态
-    this.faceTrackers.clear();
+    this.faceTracker.reset();
     this.lastDetectionResult = [];
   }
   
@@ -502,20 +464,16 @@ export class FaceDetector extends BaseScannerModule {
   async dispose(): Promise<void> {
     // 停止实时处理
     this.stopRealtime();
-    
-    // 释放模型
-    if (this.modelsLoaded) {
-      try {
-        await faceapi.tf.dispose();
-        this.modelsLoaded = false;
-      } catch (error) {
-        this.logger.error('FaceDetector', `释放模型失败: ${error}`);
-      }
-    }
-    
+
+    // 释放模型（通过 FaceModelLoader）
+    await this.modelLoader.dispose();
+
+    // 重置跟踪器
+    this.faceTracker.reset();
+
     // 移除事件监听
     this.cameraManager.off(CameraEvent.FRAME, this.handleCameraFrame.bind(this));
-    
+
     this._status = ModuleStatus.NOT_INITIALIZED;
   }
   
@@ -634,66 +592,27 @@ export class FaceDetector extends BaseScannerModule {
   ): Promise<FaceDetectionResult[]> {
     try {
       // 检查模型是否已加载
-      if (!this.modelsLoaded) {
+      if (!this.modelLoader.isModelsLoaded()) {
         throw new FaceDetectionError('人脸检测模型尚未加载');
       }
       
       // 合并选项和配置
-      const detectOptions: FaceDetectionOptions = {
-        minConfidence: this.config.minConfidence,
-        maxFaces: this.config.maxFaces,
-        withLandmarks: this.config.detectLandmarks,
-        withAttributes: this.config.detectExpressions || this.config.detectAgeGender,
-        withEmbedding: this.config.extractEmbeddings,
-        enableTracking: this.config.enableTracking,
-        ...options
-      };
-      
-      // 创建检测选项
-      let faceapiOptions;
-      
-      switch (this.config.detectionModel) {
-        case FaceModelType.SSD_MOBILENET:
-          faceapiOptions = new faceapi.SsdMobilenetv1Options({ minConfidence: detectOptions.minConfidence });
-          break;
-        case FaceModelType.TINY_FACE:
-          faceapiOptions = new faceapi.TinyFaceDetectorOptions({ scoreThreshold: detectOptions.minConfidence });
-          break;
-        case FaceModelType.MTCNN:
-          faceapiOptions = new faceapi.MtcnnOptions({ minConfidence: detectOptions.minConfidence });
-          break;
-        default:
-          faceapiOptions = new faceapi.SsdMobilenetv1Options({ minConfidence: detectOptions.minConfidence });
-      }
-      
+      const detectOptions = FaceDetectorOptionsFactory.mergeOptions(this.config, options);
+
+      // 创建 face-api 检测选项
+      const faceapiOptions = FaceDetectorOptionsFactory.createFaceAPIOptions(
+        this.config.detectionModel,
+        detectOptions.minConfidence ?? 0.5
+      );
+
       // 进行检测
-      let detections;
       const startTime = Date.now();
-      
-      if (detectOptions.withLandmarks && detectOptions.withAttributes && detectOptions.withEmbedding) {
-        // 全功能检测
-        detections = await faceapi
-          .detectAllFaces(input, faceapiOptions)
-          .withFaceLandmarks(this.config.landmarksModel === 'tiny')
-          .withFaceExpressions()
-          .withAgeAndGender()
-          .withFaceDescriptors();
-      } else if (detectOptions.withLandmarks && detectOptions.withAttributes) {
-        // 检测带关键点和属性
-        detections = await faceapi
-          .detectAllFaces(input, faceapiOptions)
-          .withFaceLandmarks(this.config.landmarksModel === 'tiny')
-          .withFaceExpressions()
-          .withAgeAndGender();
-      } else if (detectOptions.withLandmarks) {
-        // 检测带关键点
-        detections = await faceapi
-          .detectAllFaces(input, faceapiOptions)
-          .withFaceLandmarks(this.config.landmarksModel === 'tiny');
-      } else {
-        // 仅检测
-        detections = await faceapi.detectAllFaces(input, faceapiOptions);
-      }
+      const detections = await FaceDetectorOptionsFactory.detect(
+        input,
+        faceapiOptions,
+        detectOptions,
+        this.config.landmarksModel
+      );
       
       // 限制检测数量
       const maxFaces = detectOptions.maxFaces || this.config.maxFaces;
@@ -701,105 +620,30 @@ export class FaceDetector extends BaseScannerModule {
       if (detectionsArray.length > maxFaces) {
         detectionsArray.length = maxFaces;
       }
-      
+
       // 将结果转换为标准格式
-      const results: FaceDetectionResult[] = [];
       const processingTime = Date.now() - startTime;
-      
-      for (const detection of detectionsArray) {
-        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) {
-          const positions = detection.landmarks.positions;
-          
-          result.landmarks = {
-            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: any; y: any; }) => ({ x: p.x, y: p.y }))
-          };
-        }
-        
-        // 添加表情属性
-        if (detection.expressions) {
-          const emotion = {
-            angry: detection.expressions.angry,
-            disgust: detection.expressions.disgusted,
-            fear: detection.expressions.fearful,
-            happy: detection.expressions.happy,
-            neutral: detection.expressions.neutral,
-            sad: detection.expressions.sad,
-            surprise: detection.expressions.surprised
-          };
-          result.attributes = {
-            ...result.attributes,
-            emotion
-          };
-        }
-        
-        // 添加年龄和性别
-        if (detection.age !== undefined) {
-          result.attributes = {
-            ...result.attributes,
-            age: detection.age
-          };
-        }
-        
-        if (detection.gender !== undefined && detection.genderProbability !== undefined) {
-          result.attributes = {
-            ...result.attributes,
-            gender: detection.gender === 'male' ? detection.genderProbability : 1 - detection.genderProbability
-          };
-        }
-        
-        // 添加特征向量
-        if (detection.descriptor) {
-          result.embedding = {
-            vector: Array.from(detection.descriptor),
-            dimension: detection.descriptor.length
-          };
-        }
-        
-        // 处理人脸跟踪
-        if (detectOptions.enableTracking) {
-          const trackId = this.trackFace(result);
-          if (trackId) {
-            result.trackId = trackId;
+
+      // 临时更新转换器配置
+      this.resultConverter.updateConfig({
+        detectLandmarks: !!detectOptions.withLandmarks,
+        detectExpressions: !!detectOptions.withAttributes,
+        detectAgeGender: !!detectOptions.withAttributes,
+        extractEmbeddings: !!detectOptions.withEmbedding
+      });
+
+      const results = this.resultConverter.convertBatch(detectionsArray, { maxFaces }, processingTime);
+
+      // 处理人脸跟踪（使用 FaceTracker）
+      if (detectOptions.enableTracking) {
+        const trackedResults = this.faceTracker.update(results);
+        for (let i = 0; i < trackedResults.length; i++) {
+          if (trackedResults[i].trackId) {
+            results[i].trackId = trackedResults[i].trackId;
           }
         }
-        
-        results.push(result);
       }
-      
+
       return results;
     } catch (error) {
       this.logger.error('FaceDetector', `人脸检测失败: ${error}`);
@@ -807,79 +651,6 @@ export class FaceDetector extends BaseScannerModule {
     }
   }
   
-  /**
-   * 跟踪人脸
-   * @param detection 人脸检测结果
-   */
-  private trackFace(detection: FaceDetectionResult): string {
-    const now = Date.now();
-    const box = detection.boundingBox;
-    const boxCenter = {
-      x: box.x + box.width / 2,
-      y: box.y + box.height / 2
-    };
-    
-    // 查找最匹配的跟踪器
-    let bestMatchId: string | null = null;
-    let bestMatchScore = Number.MAX_VALUE;
-    
-    // 清理过期的跟踪器
-    const expireTime = 1000; // 1秒未检测到则过期
-    for (const [id, tracker] of this.faceTrackers) {
-      if (now - tracker.lastSeen > expireTime) {
-        this.faceTrackers.delete(id);
-      }
-    }
-    
-    // 查找最佳匹配
-    for (const [id, tracker] of this.faceTrackers) {
-      const trackerBox = tracker.detection.boundingBox;
-      const trackerCenter = {
-        x: trackerBox.x + trackerBox.width / 2,
-        y: trackerBox.y + trackerBox.height / 2
-      };
-      
-      // 计算中心点距离
-      const distance = Math.sqrt(
-        Math.pow(boxCenter.x - trackerCenter.x, 2) +
-        Math.pow(boxCenter.y - trackerCenter.y, 2)
-      );
-      
-      // 计算大小差异
-      const sizeDiff = Math.abs(
-        (box.width * box.height) - (trackerBox.width * trackerBox.height)
-      ) / (box.width * box.height);
-      
-      // 计算综合匹配分数
-      const score = distance * 0.7 + sizeDiff * 0.3;
-      
-      // 找到最佳匹配
-      if (score < bestMatchScore && score < 0.3 * Math.max(box.width, box.height)) {
-        bestMatchScore = score;
-        bestMatchId = id;
-      }
-    }
-    
-    if (bestMatchId) {
-      // 更新现有跟踪器
-      const tracker = this.faceTrackers.get(bestMatchId)!;
-      tracker.lastSeen = now;
-      tracker.detection = detection;
-      tracker.consecutiveFrames++;
-      return bestMatchId;
-    } else {
-      // 创建新的跟踪器
-      const trackId = generateUUID();
-      this.faceTrackers.set(trackId, {
-        trackId,
-        lastSeen: now,
-        detection,
-        consecutiveFrames: 1
-      });
-      return trackId;
-    }
-  }
-  
   /**
    * 比对两个人脸
    * @param source 源人脸
@@ -936,11 +707,13 @@ export class FaceDetector extends BaseScannerModule {
         targetEmbedding = target.embedding.vector;
       }
       
-      // 计算相似度
-      const similarity = this.calculateSimilarity(sourceEmbedding, targetEmbedding);
-      const threshold = this.config.matchThreshold;
-      const isMatch = similarity >= threshold;
-      
+      // 计算相似度（使用 FaceComparator）
+      const comparisonResult = this.faceComparator.compare(sourceEmbedding, targetEmbedding);
+      if (comparisonResult.isFailure()) {
+        throw comparisonResult.getError() || new FaceComparisonError('人脸比对失败');
+      }
+      const { similarity, isMatch, threshold } = comparisonResult.getData()!;
+
       return Result.success({
         similarity,
         isMatch,
@@ -949,39 +722,11 @@ export class FaceDetector extends BaseScannerModule {
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.logger.error('FaceDetector', `人脸比对失败: ${errorMessage}`, error as Error);
-      
+
       return Result.failure(new FaceComparisonError(`人脸比对失败: ${errorMessage}`));
     }
   }
-  
-  /**
-   * 计算两个特征向量的余弦相似度
-   * @param v1 特征向量1
-   * @param v2 特征向量2
-   */
-  private calculateSimilarity(v1: number[], v2: number[]): number {
-    if (v1.length !== v2.length) {
-      throw new Error('特征向量维度不匹配');
-    }
-    
-    let dotProduct = 0;
-    let norm1 = 0;
-    let norm2 = 0;
-    
-    for (let i = 0; i < v1.length; i++) {
-      dotProduct += v1[i] * v2[i];
-      norm1 += v1[i] * v1[i];
-      norm2 += v2[i] * v2[i];
-    }
-    
-    // 确保长度非零
-    if (norm1 === 0 || norm2 === 0) {
-      return 0;
-    }
-    
-    return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
-  }
-  
+
   /**
    * 获取最近的检测结果
    */