id-scanner-lib 1.5.0 → 1.6.3

package/README.md

@@ -1,100 +1,419 @@
-# ID-Scanner-Lib
+# ID Scanner Lib
 
-一个强大的浏览器端身份证识别、二维码扫描和人脸识别库，具有活体检测功能。
+[English](./README_EN.md) | [中文](./README.md)
 
-## 功能特点
+一个功能强大的浏览器端身份验证和人脸识别库，支持人脸检测、人脸比对、活体检测和二维码扫描。
 
-- **身份证识别**: 支持中国居民身份证识别，提取身份信息和照片
-- **二维码扫描**: 支持多种二维码和条形码格式，实时视频扫描
-- **人脸识别**: 人脸检测、特征点定位、属性分析和活体检测
-- **轻量级**: 优化的代码结构，支持按需加载
-- **易于集成**: 简洁的API，适用于各种Web应用
-- **跨平台**: 支持PC和移动设备，多种浏览器兼容
+![Version](https://img.shields.io/npm/v/id-scanner-lib)
+![License](https://img.shields.io/npm/l/id-scanner-lib)
+![Size](https://img.shields.io/bundlephobia/min/id-scanner-lib)
+
+## 特性
+
+- 🚀 **模块化架构** - 核心组件独立封装，便于扩展和维护
+- 👤 **人脸检测** - 快速准确的人脸定位和属性分析
+- 🔍 **人脸比对** - 高精度的人脸相似度比对
+- 🛡️ **活体检测** - 支持被动式和主动式活体验证，防止照片、视频欺骗
+- 📱 **二维码扫描** - 支持QR码和多种条形码格式
+- ⚡ **轻量级** - 优化的模型加载策略，按需加载
+- 🌐 **跨平台** - 支持所有主流浏览器和设备
 
 ## 安装
 
+### NPM
+
 ```bash
 npm install id-scanner-lib
 ```
 
+### CDN
+
+```html
+<!-- UMD -->
+<script src="https://cdn.jsdelivr.net/npm/id-scanner-lib/dist/id-scanner-lib.min.js"></script>
+
+<!-- ESM -->
+<script type="module">
+  import IDScannerLib from 'https://cdn.jsdelivr.net/npm/id-scanner-lib/dist/id-scanner-lib.esm.js';
+</script>
+```
+
 ## 快速开始
 
-### 身份证识别
+### 基础使用
+
+```typescript
+import { IDScanner, FaceModule } from 'id-scanner-lib';
+
+// 初始化库
+await IDScanner.initialize({
+  debug: true
+});
+
+// 创建人脸模块
+const faceModule = new FaceModule({
+  onFaceDetected: (faces) => console.log('检测到人脸:', faces),
+  onError: (error) => console.error('错误:', error)
+});
+
+// 初始化人脸模块
+await faceModule.initialize();
 
-```javascript
-import { IDScanner } from 'id-scanner-lib';
+// 启动摄像头并开始人脸检测
+const videoElement = document.getElementById('video');
+await faceModule.startFaceRecognition(videoElement);
+```
+
+### 人脸比对
+
+```typescript
+// 比对两张人脸图片
+const result = await faceModule.compareFaces(image1, image2);
 
-// 创建并初始化扫描器
-const scanner = new IDScanner();
-await scanner.initialize();
+console.log(`相似度: ${result.similarity}`);
+console.log(`是否匹配: ${result.isMatch}`);
+```
 
-// 获取身份证模块
-const idCardModule = scanner.getIDCardModule();
+### 活体检测
 
-// 识别身份证
-const imageElement = document.getElementById('id-card-image');
-const result = await idCardModule.recognize(imageElement);
+```typescript
+// 被动式活体检测
+const result = await faceModule.detectLiveness(image, {
+  type: LivenessDetectionType.PASSIVE,
+  onlyLive: true,
+  minConfidence: 0.7
+});
 
-console.log('姓名:', result.name);
-console.log('身份证号:', result.idNumber);
-console.log('地址:', result.address);
+console.log(`是否为真人: ${result.isLive}`);
+console.log(`置信度: ${result.score}`);
 ```
 
 ### 二维码扫描
 
-```javascript
-// 获取二维码模块
-const qrCodeModule = scanner.getQRCodeModule();
+```typescript
+// 创建二维码扫描器
+const qrScanner = IDScanner.createQRScanner({
+  scanFrequency: 200,
+  formats: ['qrcode', 'code_128', 'code_39', 'ean_13']
+});
+
+// 初始化扫描器
+await qrScanner.init();
+
+// 启动实时扫描
+await qrScanner.startRealtime(videoElement);
+
+// 处理扫描结果
+qrScanner.on('module:realtime:result', (event) => {
+  console.log('扫描结果:', event.result.content);
+});
+```
+
+## API 文档
+
+### 核心类
+
+| 类 | 说明 |
+|---|---|
+| `IDScanner` | 主入口类，管理所有模块 |
+| `FaceModule` | 人脸检测、比对、活体检测模块 |
+| `IDCardModule` | 身份证识别模块 |
+| `QRCodeModule` | 二维码扫描模块 |
+
+### 工具函数
+
+| 函数 | 说明 |
+|---|---|
+| `withRetry()` | 带重试的异步函数包装器 |
+| `AsyncCache` | 异步缓存类 |
+| `Semaphore` | 信号量，并发控制 |
+| `ErrorHandler` | 统一错误处理 |
+| `LoadingStateManager` | 加载状态管理 |
+
+### 类型定义
+
+```typescript
+import type {
+  ImageSource,
+  Rectangle,
+  Point,
+  ModuleState,
+  BaseResult
+} from 'id-scanner-lib';
+```
+
+## 性能优化
+
+### 模型懒加载
+
+默认只加载必要的模型，按需加载其他模型：
+
+```typescript
+const faceModule = new FaceModule({
+  // 只加载检测模型，不加载表情、年龄等模型
+  extractEmbeddings: false,
+  detectExpressions: false,
+  detectAgeGender: false
+});
+```
+
+### 内存管理
+
+使用完成后务必释放资源：
+
+```typescript
+// 释放模块
+await faceModule.dispose();
+
+// 释放整个库
+await scanner.dispose();
+```
+
+## 浏览器兼容性
+
+| 浏览器 | 最低版本 |
+|--------|---------|
+| Chrome | 80+ |
+| Firefox | 75+ |
+| Safari | 14+ |
+| Edge | 80+ |
+
+## 项目结构
+
+```
+src/
+├── core/              # 核心功能
+│   ├── camera-manager.ts    # 摄像头管理
+│   ├── config.ts           # 配置管理
+│   ├── logger.ts           # 日志系统
+│   └── loading-state.ts    # 加载状态
+├── modules/           # 功能模块
+│   ├── face/         # 人脸模块
+│   ├── id-card/      # 身份证模块
+│   └── qrcode/       # 二维码模块
+├── utils/            # 工具函数
+│   ├── retry.ts      # 重试机制
+│   └── error-handler.ts # 错误处理
+└── types/            # 类型定义
+```
+
+## 常见问题
+
+### Q: 模型加载失败怎么办？
+
+A: 检查网络连接，或使用本地模型：
+
+```typescript
+const faceModule = new FaceModule({
+  modelPath: '/local/models'
+});
+```
+
+### Q: 如何处理权限问题？
+
+A: 确保页面在 HTTPS 环境下运行，并获取用户授权：
+
+```typescript
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: { facingMode: 'user' }
+});
+```
+
+### Q: 如何处理内存泄漏？
+
+A: 确保在使用完毕后释放资源：
+
+```typescript
+// 组件卸载时
+useEffect(() => {
+  return () => {
+    faceModule?.dispose();
+  };
+}, []);
+```
+
+### Q: 支持哪些图片格式？
+
+A: 支持 JPEG、PNG、WebP 等浏览器常见的图片格式。
+
+## TypeScript 类型
+
+完整类型定义请参考 [types](./src/types/) 目录。
+
+### 核心类型
+
+```typescript
+// 图像源
+type ImageSource = HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageData;
+
+// 矩形区域
+interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+// 点坐标
+interface Point {
+  x: number;
+  y: number;
+}
+
+// 模块状态
+type ModuleState = 'idle' | 'loading' | 'ready' | 'error' | 'disposed';
 
-// 从图像中扫描二维码
-const qrImage = document.getElementById('qr-image');
-const qrResult = await qrCodeModule.scan(qrImage);
+// 人脸检测结果
+interface FaceDetectionResult {
+  faces: Face[];
+  image: ImageData;
+}
 
-console.log('二维码内容:', qrResult.data);
+// 人脸详情
+interface Face {
+  box: Rectangle;
+  landmarks: Point[];
+  expressions?: Record<string, number>;
+  age?: number;
+  gender?: string;
+  embedding?: number[];
+}
 ```
 
-### 人脸识别
+## 错误处理
 
-```javascript
-// 获取人脸模块
-const faceModule = scanner.getFaceModule();
+### 错误类型
 
-// 检测人脸
-const faceImage = document.getElementById('face-image');
-const faceResult = await faceModule.detectFace(faceImage);
+```typescript
+import { ScannerError, ErrorCode } from 'id-scanner-lib';
 
-console.log('检测到人脸:', faceResult.boundingBox);
-console.log('置信度:', faceResult.confidence);
+try {
+  await faceModule.initialize();
+} catch (error) {
+  if (error instanceof ScannerError) {
+    switch (error.code) {
+      case ErrorCode.CAMERA_NOT_FOUND:
+        // 处理摄像头未找到
+        break;
+      case ErrorCode.PERMISSION_DENIED:
+        // 处理权限被拒绝
+        break;
+      case ErrorCode.MODEL_LOAD_FAILED:
+        // 处理模型加载失败
+        break;
+    }
+  }
+}
+```
+
+### 错误代码
+
+| 代码 | 说明 |
+|------|------|
+| `CAMERA_NOT_FOUND` | 摄像头未找到 |
+| `PERMISSION_DENIED` | 权限被拒绝 |
+| `MODEL_LOAD_FAILED` | 模型加载失败 |
+| `INITIALIZATION_FAILED` | 初始化失败 |
+| `PROCESSING_FAILED` | 处理失败 |
+| `DISPOSED` | 模块已释放 |
 
-// 人脸比对
-const face1 = document.getElementById('face1');
-const face2 = document.getElementById('face2');
-const comparison = await faceModule.compareFaces(face1, face2);
+## 性能调优
 
-console.log('相似度:', comparison.similarity);
-console.log('是否匹配:', comparison.isMatch);
+### 1. 调整检测频率
+
+```typescript
+const faceModule = new FaceModule({
+  // 降低检测频率以提升性能
+  detectionFrequency: 100, // ms
+});
 ```
 
-## 文档
+### 2. 缩小检测区域
 
-完整文档请访问我们的[官方文档网站](https://agions.github.io/id-scanner-lib/)
+```typescript
+const faceModule = new FaceModule({
+  // 只检测画面中心区域
+  detectionRegion: {
+    x: 0.25,
+    y: 0.25,
+    width: 0.5,
+    height: 0.5
+  }
+});
+```
 
-## 演示
+### 3. 使用 Web Worker
 
-- [身份证识别演示](https://agions.github.io/id-scanner-lib/demos/idcard.html)
-- [二维码扫描演示](https://agions.github.io/id-scanner-lib/demos/qrcode.html)
-- [人脸识别演示](https://agions.github.io/id-scanner-lib/demos/face.html)
+```typescript
+// 身份证识别使用 Web Worker，不阻塞主线程
+const idCardModule = new IDCardModule({
+  useWorker: true
+});
+```
+
+### 4. 模型选择
+
+```typescript
+const faceModule = new FaceModule({
+  // 使用轻量级模型
+  modelType: 'tiny',
+  // 或者使用完整模型（更准确但更慢）
+  // modelType: 'full'
+});
+```
 
 ## 浏览器兼容性
 
-- Chrome 60+
-- Firefox 55+
-- Safari 11+
-- Edge 79+
-- Opera 47+
-- iOS Safari 11+
-- Android Chrome 60+
+| 浏览器 | 最低版本 | 支持情况 |
+|--------|---------|---------|
+| Chrome | 80+ | ✅ 完全支持 |
+| Firefox | 75+ | ✅ 完全支持 |
+| Safari | 14+ | ✅ 完全支持 |
+| Edge | 80+ | ✅ 完全支持 |
+| iOS Safari | 14+ | ✅ 完全支持 |
+| Android Chrome | 80+ | ✅ 完全支持 |
+
+### Polyfill
+
+如需支持旧版浏览器，请添加以下 polyfill：
+
+```html
+<script src="https://polyfill.io/v3/polyfill.min.js"></script>
+```
+
+## 项目结构
+
+```
+src/
+├── core/              # 核心功能
+│   ├── camera-manager.ts    # 摄像头管理
+│   ├── config.ts           # 配置管理
+│   ├── logger.ts           # 日志系统
+│   └── loading-state.ts    # 加载状态
+├── modules/           # 功能模块
+│   ├── face/         # 人脸模块
+│   ├── id-card/      # 身份证模块
+│   └── qrcode/       # 二维码模块
+├── utils/            # 工具函数
+│   ├── retry.ts      # 重试机制
+│   └── error-handler.ts # 错误处理
+└── types/            # 类型定义
+```
+
+## 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/xxx`)
+3. 提交更改 (`git commit -m 'Add xxx'`)
+4. 推送分支 (`git push origin feature/xxx`)
+5. 创建 Pull Request
 
 ## 许可证
 
-[MIT](LICENSE)
+MIT License
+
+## 更新日志
+
+See [CHANGELOG](./CHANGELOG.md)