# id-scanner-lib

**Repository Path**: Agions/id-scanner-lib

## Basic Information

- **Project Name**: id-scanner-lib
- **Description**: 一款纯前端实现的TypeScript身份证&二维码识别库，无需后端支持，所有处理在浏览器端完成
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-17
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ID Scanner Lib

[English](./README_EN.md) | [中文](./README.md)

一个功能强大的浏览器端身份验证和人脸识别库，支持人脸检测、人脸比对、活体检测和二维码扫描。

![Version](https://img.shields.io/npm/v/id-scanner-lib?style=for-the-badge)
![License](https://img.shields.io/npm/l/id-scanner-lib?style=for-the-badge)
![Size](https://img.shields.io/bundlephobia/min/id-scanner-lib?style=for-the-badge)
![v2.0](https://img.shields.io/badge/v2.0-Scanner%20Facade-blue?style=for-the-badge)

## 特性

- 🚀 **Scanner Facade** — v2.0 统一入口，一个类管所有模块
- 📦 **模块化 ESM** — 按需引入，tree-shaking 极致优化
- 🔄 **Canvas 池化** — 复用 Canvas 对象，减少 GC 压力
- ⚡ **Worker 并行** — 检测推理不阻塞主线程
- 💾 **IndexedDB 缓存** — 模型本地缓存，二次加载零延迟
- 🔧 **v1 兼容层** — 旧 API 平滑升级，无痛迁移
- 👤 **人脸检测** — 快速准确的人脸定位和属性分析
- 🔍 **人脸比对** — 高精度余弦相似度比对
- 🛡️ **活体检测** — 被动式/主动式活体验证
- 📱 **二维码扫描** — 支持 QR 码和多种条形码格式

## 安装

```bash
npm install id-scanner-lib
```

## 快速开始

### v2.0 推荐用法（Scanner Facade）

```typescript
import { Scanner } from 'id-scanner-lib';

// 初始化
const scanner = new Scanner({
  modules: {
    face: true,        // 立即加载人脸检测
    faceComparator: false,  // 懒加载
    faceLiveness: false,     // 懒加载
    idCard: false,
    qr: false,
  },
});

await scanner.initialize();

// 检测人脸
const faces = await scanner.detectFace(videoElement);

// 释放资源
await scanner.destroy();
```

### v1.x 兼容用法（compat 层）

```typescript
// 旧代码无需改动，compat 层自动桥接
import { IDScanner } from 'id-scanner-lib/compat';

const scanner = new IDScanner({ debug: true });
await scanner.initialize();
await scanner.startFaceRecognition(video);
```

### 按模块引入（极致 tree-shaking）

```typescript
// 只需人脸检测？只引入这一个
import { FaceDetector } from 'id-scanner-lib/modules/face/detector';

// 需要比对
import { FaceDetector, FaceComparator } from 'id-scanner-lib/modules/face';

// 全功能（自动按需加载）
import { Scanner } from 'id-scanner-lib';
```

## 核心 API

### Scanner（v2.0 主入口）

| 方法 | 说明 |
|------|------|
| `new Scanner(config)` | 创建 Scanner 实例 |
| `scanner.initialize()` | 初始化所有启用的模块 |
| `scanner.detectFace(input)` | 检测人脸 |
| `scanner.destroy()` | 释放所有资源 |

### FaceDetector

```typescript
const detector = new FaceDetector({
  maxFaces: 10,
  confidenceThreshold: 0.5,
  landmarks: true,
});

await detector.initialize();
const faces = await detector.detect(imageElement);
await detector.destroy();
```

### FaceComparator

```typescript
const comparator = new FaceComparator(0.6);  // threshold = 0.6

const result = await comparator.compare(embedding1, embedding2);
console.log(result.similarity);  // 0.0 ~ 1.0
console.log(result.isMatch);    // true / false
```

## 性能优化

### Canvas 池化

`CanvasPool` 复用 Canvas 对象，避免频繁创建/销毁导致的 GC 停顿：

```typescript
const pool = new CanvasPool(4);  // 最多 4 个 canvas
const { canvas, width, height } = pool.acquire(640, 480);
// 使用 canvas 进行绘制...
pool.release({ canvas, width, height, inUse: false });
```

### Worker 并行

`WorkerBridge` 将计算密集任务放到 Worker 线程：

```typescript
const bridge = new WorkerBridge('/face-detect.worker.js');
await bridge.load();
const result = await bridge.post('detect', { imageData });
bridge.terminate();
```

### IndexedDB 模型缓存

模型文件缓存到 IndexedDB，二次加载无需网络：

```typescript
const cache = new ModelCacheManager();
await cache.init();
await cache.store(modelShard, arrayBuffer);
const data = await cache.load(modelShard);
```

## 浏览器兼容性

| 浏览器 | 最低版本 |
|--------|---------|
| Chrome | 80+ |
| Firefox | 75+ |
| Safari | 14+ |
| Edge | 80+ |

## 项目结构（v2.0）

```
src/
├── core/
│   ├── scanner.ts           # Scanner Facade（v2.0 主入口）
│   ├── config.ts           # ScannerConfig + ConfigManager
│   ├── errors.ts           # ScannerError + ErrorCodes
│   └── utils/
│       ├── canvas-pool.ts   # Canvas 池化
│       ├── worker.ts        # WorkerBridge
│       └── resource-manager.ts  # 模型缓存
├── modules/
│   └── face/
│       ├── detector/        # 人脸检测（核心）
│       │   ├── detector.ts  # FaceDetector 类
│       │   └── types.ts    # 统一类型定义
│       ├── comparator/       # 人脸比对
│       └── liveness/        # 活体检测
├── compat/
│   └── v1-adapter.ts       # v1.x API 兼容
└── index.ts                  # 统一导出
```

## 常见问题

### v1.x 如何升级到 v2.0？

**零改动即可迁移。** v1.x 代码通过 `id-scanner-lib/compat` 导入，API 完全兼容：

```typescript
// v1.x 写法（无需任何改动）
import { IDScanner } from 'id-scanner-lib';  // ❌ 旧导入
import { IDScanner } from 'id-scanner-lib/compat';  // ✅ 兼容导入
```

### 如何按需加载模块？

```typescript
// 懒加载人脸比对模块
if (needsComparison) {
  const { FaceComparator } = await import('id-scanner-lib/modules/face/comparator');
  const comparator = new FaceComparator();
}
```

### 模型加载失败怎么办？

检查网络连接，或使用本地模型路径：

```typescript
const scanner = new Scanner({
  modelPath: '/local/models',
});
```

### 如何处理内存泄漏？

务必在使用完毕后调用 `destroy()`：

```typescript
scanner.destroy();  // 释放所有资源
```

## TypeScript 类型

v2.0 统一类型定义（位于 `src/modules/face/detector/types.ts`）：

```typescript
interface FaceDetectionOptions {
  maxFaces?: number;
  minFaceSize?: number;
  confidenceThreshold?: number;
  landmarks?: boolean;
}

interface FaceDetectionResult {
  faceId: string;
  box: BoundingBox;
  confidence: number;
  landmarks?: FaceLandmarks;
  embedding?: number[];
  timestamp: number;
}

interface FaceCompareResult {
  similarity: number;
  isMatch: boolean;
  threshold: number;
  algorithm: string;
}
```

## 许可证

[MIT License](./LICENSE)

## 更新日志

See [CHANGELOG](./CHANGELOG.md)