id-scanner-lib 1.6.7 → 2.0.0

package/src/core/utils/canvas-pool.ts

@@ -0,0 +1,171 @@
+/**
+ * @file Canvas 对象池
+ * @description 提供 OffscreenCanvas/HTMLCanvasElement 的复用机制，减少内存分配和 GC 压力
+ * @module core/utils/canvas-pool
+ */
+
+/**
+ * Canvas 池条目
+ */
+export interface PooledCanvas {
+  canvas: OffscreenCanvas | HTMLCanvasElement;
+  width: number;
+  height: number;
+  inUse: boolean;
+}
+
+interface PoolEntry {
+  canvas: OffscreenCanvas | HTMLCanvasElement;
+  width: number;
+  height: number;
+  inUse: boolean;
+  lastUsed: number;
+}
+
+/**
+ * Canvas 对象池
+ *
+ * 复用 Canvas 元素，避免频繁创建和销毁导致的内存抖动
+ *
+ * @example
+ * ```typescript
+ * const pool = new CanvasPool();
+ * const acquired = pool.acquire(640, 480);
+ * // 使用 canvas 进行绘制...
+ * pool.release(acquired);
+ * ```
+ */
+export class CanvasPool {
+  private _pool: PoolEntry[] = [];
+  private _maxSize: number = 4;
+  private _useOffscreen: boolean;
+
+  /**
+   * 创建 Canvas 池
+   * @param maxSize 最大池大小
+   * @param useOffscreen 是否使用 OffscreenCanvas
+   */
+  constructor(maxSize: number = 4, useOffscreen: boolean = true) {
+    this._maxSize = maxSize;
+    this._useOffscreen = useOffscreen && typeof OffscreenCanvas !== 'undefined';
+  }
+
+  /**
+   * 从池中获取 Canvas
+   *
+   * 1. 查找尺寸匹配的可用 canvas（允许 10% 误差）
+   * 2. 无匹配则创建新的
+   * 3. 超出 _maxSize 则回收最旧的 inUse=false 的
+   * 4. 返回 PooledCanvas，标记 inUse=true
+   *
+   * @param width  宽度
+   * @param height 高度
+   */
+  acquire(width: number, height: number): PooledCanvas {
+    // 1. 查找尺寸匹配的可用 canvas（允许 10% 误差）
+    const matched = this._pool.find(p =>
+      !p.inUse &&
+      Math.abs(p.width - width) / width <= 0.1 &&
+      Math.abs(p.height - height) / height <= 0.1
+    );
+
+    if (matched) {
+      matched.inUse = true;
+      matched.lastUsed = Date.now();
+      return {
+        canvas: matched.canvas,
+        width: matched.width,
+        height: matched.height,
+        inUse: true,
+      };
+    }
+
+    // 2. 无匹配则创建新的
+    let canvas: OffscreenCanvas | HTMLCanvasElement;
+    if (this._useOffscreen) {
+      canvas = new OffscreenCanvas(width, height);
+    } else {
+      // 在非 OffscreenCanvas 环境（如 Node.js 测试）回退到 HTMLCanvasElement
+      if (typeof document !== 'undefined') {
+        canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+      } else {
+        // 无法创建 canvas
+        throw new Error('CanvasPool: 无法创建 canvas (OffscreenCanvas 不可用，且 document 不存在)');
+      }
+    }
+
+    const entry: PoolEntry = {
+      canvas,
+      width,
+      height,
+      inUse: true,
+      lastUsed: Date.now(),
+    };
+
+    // 3. 超出 _maxSize 则回收最旧的 inUse=false 的
+    if (this._pool.length >= this._maxSize) {
+      const oldestIdx = this._findOldestAvailableIndex();
+      if (oldestIdx !== -1) {
+        this._pool.splice(oldestIdx, 1);
+      }
+    }
+
+    this._pool.push(entry);
+    return {
+      canvas: entry.canvas,
+      width: entry.width,
+      height: entry.height,
+      inUse: true,
+    };
+  }
+
+  /**
+   * 归还 Canvas 到池中
+   * @param pooled 要归还的 PooledCanvas
+   */
+  release(pooled: PooledCanvas): void {
+    const entry = this._pool.find(p => p.canvas === pooled.canvas);
+    if (entry) {
+      entry.inUse = false;
+      entry.lastUsed = Date.now();
+    }
+  }
+
+  /**
+   * 清空池
+   */
+  clear(): void {
+    this._pool = [];
+  }
+
+  /**
+   * 获取池统计信息
+   */
+  getStats(): { total: number; inUse: number; available: number } {
+    return {
+      total: this._pool.length,
+      inUse: this._pool.filter(p => p.inUse).length,
+      available: this._pool.filter(p => !p.inUse).length,
+    };
+  }
+
+  /**
+   * 查找最旧的可用条目索引
+   */
+  private _findOldestAvailableIndex(): number {
+    let oldestIdx = -1;
+    let oldestTime = Infinity;
+    for (let i = 0; i < this._pool.length; i++) {
+      if (!this._pool[i].inUse && this._pool[i].lastUsed < oldestTime) {
+        oldestTime = this._pool[i].lastUsed;
+        oldestIdx = i;
+      }
+    }
+    return oldestIdx;
+  }
+}
+
+/** 全局共享的 Canvas 池实例 */
+export const globalCanvasPool = new CanvasPool();

package/src/core/utils/canvas.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Canvas Utilities
+ * @description Canvas-related utility functions
+ * @module core/utils/canvas
+ */
+
+export {};

package/src/core/utils/image.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Image Utilities
+ * @description Image processing utility functions
+ * @module core/utils/image
+ */
+
+export {};

package/src/core/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Core Utils 入口
+ * @description 导出所有核心工具模块
+ * @module core/utils
+ */
+
+export { CanvasPool, PooledCanvas, globalCanvasPool } from './canvas-pool';
+export { WorkerBridge, WorkerMessage, WorkerResponse } from './worker';
+export { ModelCacheManager, ModelShard, ModelCacheInfo, modelCache } from './resource-manager';

package/src/core/utils/resource-manager.ts

@@ -0,0 +1,155 @@
+/**
+ * @file 模型分片缓存管理器
+ * @description 提供分片模型的 IndexedDB 持久化缓存功能（idb-keyval 风格实现）
+ * @module core/utils/resource-manager
+ */
+
+/**
+ * 模型分片信息
+ */
+export interface ModelShard {
+  name: string;        // e.g. 'face-detector'
+  version: string;     // e.g. '1.0.0'
+  url: string;         // 完整 URL
+  size: number;        // bytes
+  hash?: string;       // 完整性校验
+}
+
+/**
+ * 模型缓存信息
+ */
+export interface ModelCacheInfo {
+  name: string;
+  version: string;
+  cachedAt: number;
+  size: number;
+}
+
+/**
+ * IndexedDB 模型缓存管理器
+ * 提供分片模型的持久化缓存功能
+ */
+export class ModelCacheManager {
+  private _dbName = 'id-scanner-lib-models';
+  private _storeName = 'model-cache';
+  private _db: IDBDatabase | null = null;
+
+  /**
+   * 初始化缓存管理器（打开 IndexedDB）
+   */
+  async init(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this._dbName, 1);
+      request.onerror = () => reject(new Error('Failed to open IndexedDB'));
+      request.onsuccess = () => {
+        this._db = request.result;
+        resolve();
+      };
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(this._storeName)) {
+          const store = db.createObjectStore(this._storeName, { keyPath: 'key' });
+          store.createIndex('name', 'name', { unique: false });
+          store.createIndex('version', 'version', { unique: false });
+        }
+      };
+    });
+  }
+
+  /**
+   * 生成缓存键
+   */
+  private _makeKey(model: ModelShard): string {
+    return `${model.name}@${model.version}`;
+  }
+
+  /**
+   * 检查模型是否已缓存
+   */
+  async has(model: ModelShard): Promise<boolean> {
+    if (!this._db) return false;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(!!req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 存储模型数据
+   */
+  async store(model: ModelShard, data: ArrayBuffer): Promise<void> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const record = {
+        key: this._makeKey(model),
+        name: model.name,
+        version: model.version,
+        url: model.url,
+        size: model.size,
+        data,
+        cachedAt: Date.now(),
+      };
+      const req = store.put(record);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 加载模型数据
+   */
+  async load(model: ModelShard): Promise<ArrayBuffer | null> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(req.result ? req.result.data : null);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  async clear(): Promise<void> {
+    if (!this._db) return;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const req = store.clear();
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 列出已缓存模型
+   */
+  async listCached(): Promise<ModelCacheInfo[]> {
+    if (!this._db) return [];
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.getAll();
+      req.onsuccess = () => {
+        const results: ModelCacheInfo[] = req.result.map((r: any) => ({
+          name: r.name,
+          version: r.version,
+          cachedAt: r.cachedAt,
+          size: r.size,
+        }));
+        resolve(results);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+}
+
+/** 全局模型缓存管理器实例 */
+export const modelCache = new ModelCacheManager();

package/src/core/utils/validate.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Validation Utilities
+ * @description Input validation utility functions
+ * @module core/utils/validate
+ */
+
+export {};

package/src/core/utils/worker.ts

@@ -0,0 +1,130 @@
+/**
+ * @file WorkerBridge - Web Worker 并行处理框架
+ * @description 提供基于 Promise 的 Worker 通信接口，支持超时和错误处理
+ * @module core/utils/worker
+ */
+
+/**
+ * Worker 消息格式
+ */
+export type WorkerMessage<T = any> = {
+  type: string;
+  payload: T;
+  id: string;
+};
+
+/**
+ * Worker 响应格式
+ */
+export type WorkerResponse<T = any> = {
+  type: string;
+  payload: T;
+  error?: string;
+  id: string;
+};
+
+/**
+ * WorkerBridge - 基于 Promise 的 Worker 通信桥接器
+ *
+ * 提供简洁的 Worker 消息发送接口，自动处理请求-响应匹配、超时和错误
+ *
+ * @example
+ * ```typescript
+ * const bridge = new WorkerBridge('/workers/face-detect.worker.ts');
+ * await bridge.load();
+ * const result = await bridge.post('detect', { imageData });
+ * bridge.terminate();
+ * ```
+ */
+export class WorkerBridge<TReq = any, TRes = any> {
+  private _worker: Worker | null = null;
+  private _pending: Map<string, { resolve: Function; reject: Function }> = new Map();
+  private _url: string;
+
+  /**
+   * 创建 WorkerBridge
+   * @param workerUrl Worker 文件 URL
+   */
+  constructor(workerUrl: string) {
+    this._url = workerUrl;
+  }
+
+  /**
+   * 加载 Worker
+   */
+  async load(): Promise<void> {
+    this._worker = new Worker(this._url);
+    this._worker.onmessage = (e: MessageEvent<WorkerResponse<TRes>>) => {
+      const { id, payload, error } = e.data;
+      const handlers = this._pending.get(id);
+      if (handlers) {
+        if (error) {
+          handlers.reject(new Error(error));
+        } else {
+          handlers.resolve(payload);
+        }
+        this._pending.delete(id);
+      }
+    };
+    this._worker.onerror = (e) => {
+      // 将 Worker 错误广播给所有 pending 的 Promise
+      for (const [id, handlers] of this._pending) {
+        handlers.reject(new Error(`Worker error: ${e.message}`));
+        this._pending.delete(id);
+      }
+    };
+  }
+
+  /**
+   * 发送消息到 Worker 并等待响应
+   *
+   * @param type 消息类型
+   * @param payload 消息载荷
+   * @returns 响应 Promise
+   * @throws 如果 Worker 未加载则抛出错误
+   */
+  async post(type: string, payload: TReq): Promise<TRes> {
+    if (!this._worker) {
+      throw new Error('Worker not loaded');
+    }
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._worker!.postMessage({ type, payload, id } as WorkerMessage<TReq>);
+      // 超时 30s
+      setTimeout(() => {
+        if (this._pending.has(id)) {
+          this._pending.delete(id);
+          reject(new Error('Worker timeout'));
+        }
+      }, 30000);
+    });
+  }
+
+  /**
+   * 终止 Worker
+   */
+  terminate(): void {
+    this._worker?.terminate();
+    this._worker = null;
+    // 拒绝所有 pending 的 Promise
+    for (const [, handlers] of this._pending) {
+      handlers.reject(new Error('Worker terminated'));
+    }
+    this._pending.clear();
+  }
+
+  /**
+   * 检查 Worker 是否已加载
+   */
+  get isLoaded(): boolean {
+    return this._worker !== null;
+  }
+
+  /**
+   * 获取当前 pending 请求数
+   */
+  get pendingCount(): number {
+    return this._pending.size;
+  }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * @file Face Comparator
+ * @description Face comparison using cosine similarity
+ * @module modules/face/comparator
+ */
+
+import { FaceCompareResult, FaceDetectionResult } from '../detector/types';
+
+export class FaceComparator {
+  private _threshold: number = 0.6;
+
+  constructor(threshold: number = 0.6) {
+    this._threshold = threshold;
+  }
+
+  async compare(
+    face1: FaceDetectionResult | number[],
+    face2: FaceDetectionResult | number[]
+  ): Promise<FaceCompareResult> {
+    // Extract embedding
+    const emb1 = Array.isArray(face1) ? face1 : face1.embedding ?? [];
+    const emb2 = Array.isArray(face2) ? face2 : face2.embedding ?? [];
+
+    // Compute cosine similarity
+    const similarity = this._cosineSimilarity(emb1, emb2);
+
+    return {
+      similarity,
+      isMatch: similarity >= this._threshold,
+      threshold: this._threshold,
+      algorithm: 'cosine-similarity',
+    };
+  }
+
+  private _cosineSimilarity(a: number[], b: number[]): number {
+    if (a.length !== b.length || a.length === 0) return 0;
+    let dot = 0, magA = 0, magB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  }
+}

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

@@ -0,0 +1 @@
+export { FaceComparator } from './comparator';

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

@@ -0,0 +1,83 @@
+/**
+ * @file Face Detector
+ * @description Face detection module with canvas pooling
+ * @module modules/face/detector
+ */
+
+import { FaceDetectionOptions, FaceDetectionResult } from './types';
+import { CanvasPool } from '../../../core/utils/canvas-pool';
+import { ImageSource } from '../../../core/config';
+
+export class FaceDetector {
+  private _options: Required<FaceDetectionOptions>;
+  private _pool: CanvasPool;
+  private _initialized: boolean = false;
+  private _modelLoaded: boolean = false;
+
+  constructor(options: FaceDetectionOptions = {}) {
+    this._options = {
+      maxFaces: options.maxFaces ?? 10,
+      minFaceSize: options.minFaceSize ?? 0.1,
+      confidenceThreshold: options.confidenceThreshold ?? 0.5,
+      landmarks: options.landmarks ?? true,
+      inputWidth: options.inputWidth ?? 640,
+      inputHeight: options.inputHeight ?? 480,
+    };
+    this._pool = new CanvasPool();
+  }
+
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  async initialize(): Promise<void> {
+    // Load model (lazy loading on demand)
+    this._modelLoaded = true;
+    this._initialized = true;
+  }
+
+  async detect(input: ImageSource): Promise<FaceDetectionResult[]> {
+    if (!this._initialized) {
+      throw new Error('FaceDetector not initialized');
+    }
+
+    // 1. Acquire canvas from pool
+    const pooled = this._pool.acquire(this._options.inputWidth, this._options.inputHeight);
+
+    try {
+      // 2. Draw input to canvas
+      const ctx = pooled.canvas.getContext('2d');
+      if (!ctx) {
+        throw new Error('Failed to get 2d context');
+      }
+
+      // Handle different input types
+      if (input instanceof HTMLCanvasElement) {
+        ctx.drawImage(input, 0, 0);
+      } else if (input instanceof HTMLImageElement || input instanceof HTMLVideoElement) {
+        ctx.drawImage(input, 0, 0, this._options.inputWidth, this._options.inputHeight);
+      } else if (input instanceof ImageData) {
+        ctx.putImageData(input, 0, 0);
+      }
+      // string input (URL) would need async loading — not implemented in stub
+
+      // 3. Run detection (stub returns empty)
+      // TODO: Integrate real model
+
+      // 4. Convert results and return
+      const results: FaceDetectionResult[] = [];
+      // stub: no faces detected
+
+      return results;
+    } finally {
+      // 5. Release canvas back to pool
+      this._pool.release(pooled);
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this._pool.clear();
+    this._initialized = false;
+    this._modelLoaded = false;
+  }
+}

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

@@ -0,0 +1,2 @@
+export { FaceDetector } from './detector';
+export { FaceDetectionOptions, FaceDetectionResult, FaceCompareResult, BoundingBox, FaceLandmarks, Point } from './types';

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

@@ -0,0 +1,80 @@
+/**
+ * Face detection options
+ */
+export interface FaceDetectionOptions {
+  /** Maximum number of faces to detect */
+  maxFaces?: number;
+  /** Minimum face size (0-1, relative to image) */
+  minFaceSize?: number;
+  /** Confidence threshold (0-1) */
+  confidenceThreshold?: number;
+  /** Whether to return facial landmarks */
+  landmarks?: boolean;
+  /** Input image/frame width (for normalization) */
+  inputWidth?: number;
+  /** Input image/frame height (for normalization) */
+  inputHeight?: number;
+}
+
+/**
+ * Detected face result
+ */
+export interface FaceDetectionResult {
+  /** Unique face ID (for tracking) */
+  faceId: string;
+  /** Bounding box */
+  box: BoundingBox;
+  /** Detection confidence (0-1) */
+  confidence: number;
+  /** Facial landmarks (optional) */
+  landmarks?: FaceLandmarks;
+  /** Face embedding vector (optional, for comparison) */
+  embedding?: number[];
+  /** Detection timestamp */
+  timestamp: number;
+}
+
+/**
+ * Bounding box
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Face landmarks
+ */
+export interface FaceLandmarks {
+  leftEye?: Point;
+  rightEye?: Point;
+  nose?: Point;
+  leftMouth?: Point;
+  rightMouth?: Point;
+  leftEar?: Point;
+  rightEar?: Point;
+}
+
+/**
+ * 2D point
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Face comparison result
+ */
+export interface FaceCompareResult {
+  /** Similarity score (0-1) */
+  similarity: number;
+  /** Whether faces match (threshold-based) */
+  isMatch: boolean;
+  /** Threshold used */
+  threshold: number;
+  /** Comparison algorithm used */
+  algorithm: string;
+}