id-scanner-lib 1.6.7 → 2.0.0

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

@@ -0,0 +1,150 @@
+/**
+ * @file 人脸比对器
+ * @description 提供人脸特征向量比对功能
+ * @module modules/face/face-comparator
+ */
+
+import { FaceDetectionResult } from '../../interfaces/face-detection';
+import { Result } from '../../core/result';
+import { FaceComparisonError } from '../../core/errors';
+import { Logger } from '../../core/logger';
+
+/**
+ * 人脸比对结果
+ */
+export interface ComparisonResult {
+  /** 相似度 (0-1) */
+  similarity: number;
+  /** 是否匹配（基于阈值） */
+  isMatch: boolean;
+  /** 使用的阈值 */
+  threshold: number;
+}
+
+/**
+ * 人脸比对器配置
+ */
+export interface FaceComparatorConfig {
+  /** 人脸匹配阈值 (0-1) */
+  matchThreshold?: number;
+}
+
+/**
+ * 人脸比对器
+ *
+ * 负责计算两个人脸特征向量的相似度
+ */
+export class FaceComparator {
+  /** 日志记录器 */
+  private logger: Logger;
+
+  /** 匹配阈值 */
+  private matchThreshold: number;
+
+  /**
+   * 构造函数
+   * @param config 比对器配置
+   */
+  constructor(config: FaceComparatorConfig = {}) {
+    this.logger = Logger.getInstance();
+    this.matchThreshold = config.matchThreshold ?? 0.6;
+  }
+
+  /**
+   * 计算两个特征向量的余弦相似度
+   *
+   * @param v1 特征向量1
+   * @param v2 特征向量2
+   * @returns 相似度 (0-1)
+   */
+  computeSimilarity(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));
+  }
+
+  /**
+   * 比对两个人脸
+   *
+   * @param source 源人脸（特征向量或检测结果）
+   * @param target 目标人脸（特征向量或检测结果）
+   * @returns 比对结果
+   */
+  compare(
+    source: number[] | FaceDetectionResult,
+    target: number[] | FaceDetectionResult
+  ): Result<ComparisonResult> {
+    try {
+      // 提取特征向量
+      const sourceEmbedding = this.extractEmbedding(source);
+      const targetEmbedding = this.extractEmbedding(target);
+
+      if (!sourceEmbedding || !targetEmbedding) {
+        return Result.failure(new FaceComparisonError('无法获取特征向量'));
+      }
+
+      // 计算相似度
+      const similarity = this.computeSimilarity(sourceEmbedding, targetEmbedding);
+      const isMatch = similarity >= this.matchThreshold;
+
+      return Result.success({
+        similarity,
+        isMatch,
+        threshold: this.matchThreshold
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error('FaceComparator', `人脸比对失败: ${errorMessage}`, error as Error);
+      return Result.failure(new FaceComparisonError(`人脸比对失败: ${errorMessage}`));
+    }
+  }
+
+  /**
+   * 从输入中提取特征向量
+   */
+  private extractEmbedding(input: number[] | FaceDetectionResult): number[] | null {
+    if (Array.isArray(input)) {
+      return input;
+    }
+
+    if (input.embedding?.vector) {
+      return input.embedding.vector;
+    }
+
+    return null;
+  }
+
+  /**
+   * 设置匹配阈值
+   */
+  setThreshold(threshold: number): void {
+    if (threshold < 0 || threshold > 1) {
+      throw new Error('阈值必须在 0-1 范围内');
+    }
+    this.matchThreshold = threshold;
+  }
+
+  /**
+   * 获取当前阈值
+   */
+  getThreshold(): number {
+    return this.matchThreshold;
+  }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @file 人脸检测选项工厂
+ * @description 创建 face-api 检测选项和处理选项
+ * @module modules/face/face-detector-options
+ */
+
+import * as faceapi from '@vladmandic/face-api';
+import { FaceDetectionOptions } from '../../interfaces/face-detection';
+import { FaceModelType, FaceDetectorConfig } from './face-detector';
+
+/**
+ * 人脸检测选项工厂
+ *
+ * 负责创建 face-api 兼容的检测选项和处理选项
+ */
+export class FaceDetectorOptionsFactory {
+  /**
+   * 创建 face-api 检测选项
+   * @param detectionModel 检测模型类型
+   * @param minConfidence 最小置信度
+   * @returns face-api 检测选项
+   */
+  static createFaceAPIOptions(
+    detectionModel: FaceModelType,
+    minConfidence: number
+  ): faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions {
+    switch (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 config 人脸检测器配置
+   * @param options 用户提供的选项
+   * @returns 合并后的检测选项
+   */
+  static mergeOptions(
+    config: FaceDetectorConfig,
+    options: FaceDetectionOptions = {}
+  ): FaceDetectionOptions {
+    return {
+      minConfidence: config.minConfidence,
+      maxFaces: config.maxFaces,
+      withLandmarks: config.detectLandmarks,
+      withAttributes: config.detectExpressions || config.detectAgeGender,
+      withEmbedding: config.extractEmbeddings,
+      enableTracking: config.enableTracking,
+      ...options
+    };
+  }
+
+  /**
+   * 执行人脸检测
+   * @param input 输入图像/视频/画布
+   * @param faceapiOptions face-api 检测选项
+   * @param detectOptions 检测选项
+   * @param landmarksModel 关键点模型类型
+   * @returns face-api 检测结果
+   */
+  static async detect(
+    input: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement,
+    faceapiOptions: faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions,
+    detectOptions: FaceDetectionOptions,
+    landmarksModel: 'tiny' | '68_points'
+  ): Promise<any> {
+    const withLandmarks = detectOptions.withLandmarks;
+    const withAttributes = detectOptions.withAttributes;
+    const withEmbedding = detectOptions.withEmbedding;
+
+    // 根据选项组合选择检测方法链
+    if (withLandmarks && withAttributes && withEmbedding) {
+      // 全功能检测
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny')
+        .withFaceExpressions()
+        .withAgeAndGender()
+        .withFaceDescriptors();
+    } else if (withLandmarks && withAttributes) {
+      // 检测带关键点和属性
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny')
+        .withFaceExpressions()
+        .withAgeAndGender();
+    } else if (withLandmarks) {
+      // 检测带关键点
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny');
+    } else {
+      // 仅检测
+      return await faceapi.detectAllFaces(input, faceapiOptions);
+    }
+  }
+}