ID Scanner Lib

English | 中文

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

特性

• 🚀 模块化架构 - 核心组件独立封装，便于扩展和维护
• 👤 人脸检测 - 快速准确的人脸定位和属性分析
• 🔍 人脸比对 - 高精度的人脸相似度比对
• 🛡️ 活体检测 - 支持被动式和主动式活体验证，防止照片、视频欺骗
• 📱 二维码扫描 - 支持QR码和多种条形码格式
• ⚡ 轻量级 - 优化的模型加载策略，按需加载
• 🌐 跨平台 - 支持所有主流浏览器和设备

安装

NPM

npm install id-scanner-lib

CDN

<!-- 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>

快速开始

基础使用

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();

// 启动摄像头并开始人脸检测
const videoElement = document.getElementById('video');
await faceModule.startFaceRecognition(videoElement);

人脸比对

// 比对两张人脸图片
const result = await faceModule.compareFaces(image1, image2);

console.log(`相似度: ${result.similarity}`);
console.log(`是否匹配: ${result.isMatch}`);

活体检测

// 被动式活体检测
const result = await faceModule.detectLiveness(image, {
  type: LivenessDetectionType.PASSIVE,
  onlyLive: true,
  minConfidence: 0.7
});

console.log(`是否为真人: ${result.isLive}`);
console.log(`置信度: ${result.score}`);

二维码扫描

// 创建二维码扫描器
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 | 加载状态管理 |

类型定义

import type {
  ImageSource,
  Rectangle,
  Point,
  ModuleState,
  BaseResult
} from 'id-scanner-lib';

性能优化

模型懒加载

默认只加载必要的模型，按需加载其他模型：

const faceModule = new FaceModule({
  // 只加载检测模型，不加载表情、年龄等模型
  extractEmbeddings: false,
  detectExpressions: false,
  detectAgeGender: false
});

内存管理

使用完成后务必释放资源：

// 释放模块
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: 检查网络连接，或使用本地模型：

const faceModule = new FaceModule({
  modelPath: '/local/models'
});

Q: 如何处理权限问题？

A: 确保页面在 HTTPS 环境下运行，并获取用户授权：

const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: 'user' }
});

Q: 如何处理内存泄漏？

A: 确保在使用完毕后释放资源：

// 组件卸载时
useEffect(() => {
  return () => {
    faceModule?.dispose();
  };
}, []);

Q: 支持哪些图片格式？

A: 支持 JPEG、PNG、WebP 等浏览器常见的图片格式。

TypeScript 类型

完整类型定义请参考 types 目录。

核心类型

// 图像源
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';

// 人脸检测结果
interface FaceDetectionResult {
  faces: Face[];
  image: ImageData;
}

// 人脸详情
interface Face {
  box: Rectangle;
  landmarks: Point[];
  expressions?: Record<string, number>;
  age?: number;
  gender?: string;
  embedding?: number[];
}

错误处理

错误类型

import { ScannerError, ErrorCode } from 'id-scanner-lib';

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 | 模块已释放 |

性能调优

1. 调整检测频率

const faceModule = new FaceModule({
  // 降低检测频率以提升性能
  detectionFrequency: 100, // ms
});

2. 缩小检测区域

const faceModule = new FaceModule({
  // 只检测画面中心区域
  detectionRegion: {
    x: 0.25,
    y: 0.25,
    width: 0.5,
    height: 0.5
  }
});

3. 使用 Web Worker

// 身份证识别使用 Web Worker，不阻塞主线程
const idCardModule = new IDCardModule({
  useWorker: true
});

4. 模型选择

const faceModule = new FaceModule({
  // 使用轻量级模型
  modelType: 'tiny',
  // 或者使用完整模型（更准确但更慢）
  // modelType: 'full'
});

浏览器兼容性

| 浏览器 | 最低版本 | 支持情况 | |--------|---------|---------| | Chrome | 80+ | ✅ 完全支持 | | Firefox | 75+ | ✅ 完全支持 | | Safari | 14+ | ✅ 完全支持 | | Edge | 80+ | ✅ 完全支持 | | iOS Safari | 14+ | ✅ 完全支持 | | Android Chrome | 80+ | ✅ 完全支持 |

Polyfill

如需支持旧版浏览器，请添加以下 polyfill：

<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

更新日志

See CHANGELOG