id-scanner-lib 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 agions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,317 @@
+# ID-Scanner-Lib
+
+纯前端实现的TypeScript身份证&二维码识别库，无需后端支持，所有处理在浏览器端完成。
+
+## 主要功能
+
+- **二维码扫描识别**：实时识别摄像头中的二维码
+- **条形码扫描识别**：支持常见一维条形码格式识别
+- **身份证检测**：自动检测和定位摄像头中的身份证
+- **OCR信息提取**：从身份证图像中提取文字信息
+- **数据验证与增强**：验证身份证号码格式，并通过多种方式补充缺失信息
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       IDScanner 主类                        │
+├─────────────┬─────────────────┬────────────────────────────┤
+│  QRScanner  │  BarcodeScanner │        IDCardDetector      │
+├─────────────┴─────────────────┴────────────────────────────┤
+│                 Camera (视频流捕获与处理)                    │
+└─────────────────────────────────────────────────────────────┘
+                           ▲
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   数据处理与识别模块                         │
+├─────────────────┬─────────────────┬────────────────────────┤
+│  OCRProcessor   │  DataExtractor  │     ImageProcessor     │
+│  (文字识别)      │  (数据提取验证)  │     (图像预处理)       │
+└─────────────────┴─────────────────┴────────────────────────┘
+```
+
+## 安装
+
+```bash
+npm install id-scanner-lib
+```
+
+## 快速开始
+
+### 基本用法
+
+```javascript
+import { IDScanner } from 'id-scanner-lib';
+
+// 创建扫描器实例
+const scanner = new IDScanner({
+  // 二维码识别回调
+  onQRCodeScanned: (result) => {
+    console.log('扫描到二维码:', result);
+  },
+  
+  // 条形码识别回调
+  onBarcodeScanned: (result) => {
+    console.log('扫描到条形码:', result);
+  },
+  
+  // 身份证识别回调
+  onIDCardScanned: (info) => {
+    console.log('识别到身份证信息:', info);
+  },
+  
+  // 错误处理
+  onError: (error) => {
+    console.error('扫描出错:', error);
+  }
+});
+
+// 初始化
+await scanner.initialize();
+
+// 启动二维码扫描
+const videoElement = document.getElementById('video');
+await scanner.startQRScanner(videoElement);
+
+// 切换到身份证识别
+scanner.stop();
+await scanner.startIDCardScanner(videoElement);
+
+// 使用结束后释放资源
+scanner.terminate();
+```
+
+### 演示代码
+
+查看 `examples/index.html` 获取完整的演示代码。
+
+## 详细API文档
+
+### IDScanner 主类
+
+```typescript
+class IDScanner {
+  // 构造函数
+  constructor(options?: IDScannerOptions);
+  
+  // 初始化OCR引擎和资源
+  async initialize(): Promise<void>;
+  
+  // 启动二维码扫描
+  async startQRScanner(videoElement: HTMLVideoElement): Promise<void>;
+  
+  // 启动条形码扫描
+  async startBarcodeScanner(videoElement: HTMLVideoElement): Promise<void>;
+  
+  // 启动身份证扫描
+  async startIDCardScanner(videoElement: HTMLVideoElement): Promise<void>;
+  
+  // 停止当前扫描
+  stop(): void;
+  
+  // 释放所有资源
+  async terminate(): Promise<void>;
+}
+```
+
+### 类型定义
+
+```typescript
+// IDScanner配置选项
+interface IDScannerOptions {
+  // 相机配置
+  cameraOptions?: CameraOptions;
+  // 二维码扫描配置
+  qrScannerOptions?: QRScannerOptions;
+  // 条形码扫描配置
+  barcodeScannerOptions?: BarcodeScannerOptions;
+  // 二维码识别回调
+  onQRCodeScanned?: (result: string) => void;
+  // 条形码识别回调
+  onBarcodeScanned?: (result: string) => void;
+  // 身份证识别回调
+  onIDCardScanned?: (info: IDCardInfo) => void;
+  // 错误处理回调
+  onError?: (error: Error) => void;
+}
+
+// 相机配置选项
+interface CameraOptions {
+  width?: number;      // 视频宽度
+  height?: number;     // 视频高度
+  facingMode?: 'user' | 'environment';  // 前置或后置摄像头
+}
+
+// 识别结果的身份证信息
+interface IDCardInfo {
+  name?: string;         // 姓名
+  gender?: string;       // 性别
+  nationality?: string;  // 民族
+  birthDate?: string;    // 出生日期，如"1990-01-01"
+  address?: string;      // 地址
+  idNumber?: string;     // 身份证号码 
+  issuingAuthority?: string; // 签发机关
+  validPeriod?: string;  // 有效期限
+}
+```
+
+## 高级用法
+
+### 自定义相机配置
+
+```javascript
+const scanner = new IDScanner({
+  cameraOptions: {
+    width: 1280,
+    height: 720,
+    facingMode: 'environment' // 使用后置摄像头，更适合扫描
+  },
+  onIDCardScanned: (info) => {
+    console.log('识别到身份证信息:', info);
+  }
+});
+```
+
+### 调整扫描频率
+
+```javascript
+const scanner = new IDScanner({
+  qrScannerOptions: {
+    scanInterval: 100 // 每100ms扫描一次，默认为200ms
+  },
+  onQRCodeScanned: (result) => {
+    console.log('扫描到二维码:', result);
+  }
+});
+```
+
+### 直接使用子模块
+
+```javascript
+import { QRScanner, ImageProcessor } from 'id-scanner-lib';
+
+// 单独使用二维码扫描功能
+const qrScanner = new QRScanner({
+  onScan: (result) => {
+    console.log('扫描到二维码:', result);
+  }
+});
+
+// 使用图像处理工具
+const enhancedImage = ImageProcessor.adjustBrightnessContrast(
+  originalImageData,
+  10,  // 亮度调整
+  20   // 对比度调整
+);
+```
+
+## 性能优化建议
+
+1. **预加载OCR引擎**：在用户可能需要识别身份证前就初始化`OCRProcessor`，避免用户等待。
+
+```javascript
+// 页面加载后即初始化，而不是等到用户点击按钮才初始化
+document.addEventListener('DOMContentLoaded', async () => {
+  const scanner = new IDScanner();
+  await scanner.initialize(); // 预先加载OCR引擎
+  
+  // 保存scanner实例供后续使用
+  window.idScanner = scanner;
+});
+```
+
+2. **减小分辨率**：如果识别速度太慢，可以尝试降低相机分辨率。
+
+```javascript
+const scanner = new IDScanner({
+  cameraOptions: {
+    width: 640,
+    height: 480 // 降低分辨率提高处理速度
+  }
+});
+```
+
+3. **关闭不必要的扫描**：不使用时及时停止扫描，节省资源。
+
+## 常见问题解答
+
+**Q: 为什么我在移动设备上无法访问摄像头？**
+
+A: 确保你的网站使用HTTPS协议，现代浏览器要求在安全上下文中才能访问摄像头。
+
+**Q: 身份证识别准确率不高怎么办？**
+
+A: 
+- 确保光线充足，避免反光和阴影
+- 调整相机对准身份证，使其占据画面大部分区域
+- 保持身份证平整，避免弯曲
+- 尝试增强图像对比度：`ImageProcessor.adjustBrightnessContrast()`
+
+**Q: 库的大小会不会影响页面加载速度？**
+
+A: 库的大小约为1MB，主要是因为包含OCR引擎。可以考虑按需加载，只在用户需要识别身份证时才加载OCR相关模块。
+
+## 浏览器兼容性
+
+| 浏览器        | 版本要求              | 备注                      |
+|--------------|---------------------|--------------------------|
+| Chrome       | 60+                 | 全功能支持                 |
+| Firefox      | 55+                 | 全功能支持                 |
+| Edge         | 79+ (Chromium)      | 全功能支持                 |
+| Safari       | 11+                 | iOS需要用户主动点击激活相机  |
+| 安卓WebView   | 60+                 | 需要应用授予相机权限        |
+| iOS WebView  | 11+                 | 需要用户主动点击激活相机     |
+
+## 开发与贡献
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/agions/id-scanner-lib.git
+
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 构建生产版本
+npm run build
+```
+
+### 目录结构
+
+```
+src/
+├── index.ts                # 主入口
+├── scanner/                # 扫描模块
+│   ├── qr-scanner.ts       # 二维码扫描
+│   └── barcode-scanner.ts  # 条形码扫描
+├── id-recognition/         # 身份证识别模块
+│   ├── id-detector.ts      # 身份证检测
+│   ├── ocr-processor.ts    # OCR文字识别
+│   └── data-extractor.ts   # 数据提取和验证
+└── utils/                  # 工具类
+    ├── camera.ts           # 相机访问
+    ├── image-processing.ts # 图像处理
+    └── types.ts            # 类型定义
+```
+
+## 技术实现
+
+- 使用 WebRTC 获取摄像头视频流
+- 使用 jsQR 进行二维码识别
+- 使用 Tesseract.js 进行OCR文字识别
+- 基于 Canvas API 进行图像处理
+
+## 许可证
+
+本项目基于MIT许可证开源。
+
+## 致谢
+
+本项目使用了以下开源库：
+- [jsQR](https://github.com/cozmo/jsQR) - 二维码扫描
+- [Tesseract.js](https://github.com/naptha/tesseract.js) - OCR文字识别 

package/dist/demo/demo.d.ts

@@ -0,0 +1,14 @@
+export declare class IDScannerDemo {
+    private scanner;
+    private videoElement;
+    private resultContainer;
+    private switchButton;
+    constructor(videoElementId: string, resultContainerId: string, switchButtonId: string);
+    initialize(): Promise<void>;
+    private currentMode;
+    private toggleScanMode;
+    private handleQRCodeResult;
+    private handleIDCardResult;
+    private handleError;
+    stop(): void;
+}

package/dist/id-recognition/data-extractor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file 数据提取工具类
+ * @description 提供身份证信息的验证和格式化功能
+ * @module DataExtractor
+ */
+import { IDCardInfo } from '../utils/types';
+/**
+ * 数据提取工具类
+ *
+ * 提供身份证信息的验证、提取和增强功能，可以从身份证号码中提取出生日期、性别等信息，
+ * 并对OCR识别结果进行补充和验证
+ *
+ * @example
+ * ```typescript
+ * // 验证身份证号码
+ * const isValid = DataExtractor.validateIDNumber('110101199001011234');
+ *
+ * // 从身份证号码提取出生日期
+ * const birthDate = DataExtractor.extractBirthDateFromID('110101199001011234');
+ * // 结果: '1990-01-01'
+ *
+ * // 增强OCR识别结果
+ * const enhancedInfo = DataExtractor.enhanceIDCardInfo({
+ *   name: '张三',
+ *   idNumber: '110101199001011234'
+ * });
+ * // 结果会自动补充性别和出生日期
+ * ```
+ */
+export declare class DataExtractor {
+    /**
+     * 验证身份证号码格式
+     *
+     * 检查身份证号码的长度、格式和出生日期部分是否有效
+     *
+     * @param {string} idNumber - 要验证的身份证号码
+     * @returns {boolean} 是否是有效的身份证号码
+     */
+    static validateIDNumber(idNumber: string): boolean;
+    /**
+     * 从身份证号码提取出生日期
+     *
+     * @param {string} idNumber - 身份证号码
+     * @returns {string|null} 格式化的出生日期（YYYY-MM-DD），如果身份证号码无效则返回null
+     */
+    static extractBirthDateFromID(idNumber: string): string | null;
+    /**
+     * 从身份证号码提取性别
+     *
+     * 根据身份证号码第17位判断性别，奇数为男，偶数为女
+     *
+     * @param {string} idNumber - 身份证号码
+     * @returns {string|null} '男'或'女'，如果身份证号码无效则返回null
+     */
+    static extractGenderFromID(idNumber: string): string | null;
+    /**
+     * 从身份证号码提取地区编码
+     *
+     * @param {string} idNumber - 身份证号码
+     * @returns {string|null} 地区编码（前6位），如果身份证号码无效则返回null
+     */
+    static extractRegionFromID(idNumber: string): string | null;
+    /**
+     * 合并并优化身份证信息
+     *
+     * 使用多个来源的数据进行交叉验证和补充，如果OCR识别结果缺少某些信息，
+     * 但有身份证号码，则可以从号码中提取出生日期和性别等信息
+     *
+     * @param {IDCardInfo} ocrInfo - OCR识别到的身份证信息
+     * @param {string} [idNumber] - 可选的外部提供的身份证号码，优先级高于OCR识别结果
+     * @returns {IDCardInfo} 增强后的身份证信息
+     */
+    static enhanceIDCardInfo(ocrInfo: IDCardInfo, idNumber?: string): IDCardInfo;
+}

package/dist/id-recognition/id-detector.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file 身份证检测模块
+ * @description 提供自动检测和定位图像中的身份证功能
+ * @module IDCardDetector
+ */
+import { DetectionResult } from '../utils/types';
+/**
+ * 身份证检测器类
+ *
+ * 通过图像处理和计算机视觉技术，实时检测视频流中的身份证，并提取身份证区域
+ * 注意：当前实现是简化版，实际项目中建议使用OpenCV.js进行更精确的检测
+ *
+ * @example
+ * ```typescript
+ * // 创建身份证检测器
+ * const detector = new IDCardDetector((result) => {
+ *   if (result.success && result.croppedImage) {
+ *     console.log('检测到身份证!');
+ *     // 对裁剪出的身份证图像进行处理
+ *     processIDCardImage(result.croppedImage);
+ *   }
+ * });
+ *
+ * // 启动检测
+ * const videoElement = document.getElementById('video') as HTMLVideoElement;
+ * await detector.start(videoElement);
+ *
+ * // 停止检测
+ * detector.stop();
+ * ```
+ */
+export declare class IDCardDetector {
+    private onDetected?;
+    private camera;
+    private detecting;
+    private detectTimer;
+    /**
+     * 创建身份证检测器实例
+     *
+     * @param {Function} [onDetected] - 身份证检测成功回调函数，接收检测结果对象
+     */
+    constructor(onDetected?: ((result: DetectionResult) => void) | undefined);
+    /**
+     * 启动身份证检测
+     *
+     * 初始化相机并开始连续检测视频帧中的身份证
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     */
+    start(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 执行一次身份证检测
+     *
+     * 内部方法，捕获当前视频帧并尝试检测其中的身份证
+     *
+     * @private
+     */
+    private detect;
+    /**
+     * 身份证检测核心算法
+     *
+     * 通过图像处理技术检测和提取图像中的身份证区域
+     *
+     * @private
+     * @param {ImageData} imageData - 需要检测身份证的图像数据
+     * @returns {Promise<DetectionResult>} 检测结果，包含成功标志和裁剪后的身份证图像
+     */
+    private detectIDCard;
+    /**
+     * 停止身份证检测
+     *
+     * 停止检测循环并释放相机资源
+     */
+    stop(): void;
+}

package/dist/id-recognition/ocr-processor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file OCR处理模块
+ * @description 提供身份证文字识别和信息提取功能
+ * @module OCRProcessor
+ */
+import { IDCardInfo } from '../utils/types';
+/**
+ * OCR处理器类
+ *
+ * 使用Tesseract.js实现对身份证图像的OCR文字识别和信息提取功能
+ *
+ * @example
+ * ```typescript
+ * // 创建OCR处理器
+ * const ocrProcessor = new OCRProcessor();
+ *
+ * // 初始化OCR引擎
+ * await ocrProcessor.initialize();
+ *
+ * // 处理身份证图像
+ * const idInfo = await ocrProcessor.processIDCard(idCardImageData);
+ * console.log('识别到的身份证信息:', idInfo);
+ *
+ * // 使用结束后释放资源
+ * await ocrProcessor.terminate();
+ * ```
+ */
+export declare class OCRProcessor {
+    private worker;
+    constructor();
+    /**
+     * 初始化OCR引擎
+     *
+     * 加载Tesseract OCR引擎和中文简体语言包，并设置适合身份证识别的参数
+     *
+     * @returns {Promise<void>} 初始化完成的Promise
+     */
+    initialize(): Promise<void>;
+    /**
+     * 处理身份证图像并提取信息
+     *
+     * 对身份证图像进行OCR识别，并从识别结果中提取结构化信息
+     *
+     * @param {ImageData} imageData - 身份证图像数据
+     * @returns {Promise<IDCardInfo>} 提取到的身份证信息
+     */
+    processIDCard(imageData: ImageData): Promise<IDCardInfo>;
+    /**
+     * 解析身份证文本信息
+     *
+     * 从OCR识别到的文本中提取结构化的身份证信息
+     *
+     * @private
+     * @param {string} text - OCR识别到的文本
+     * @returns {IDCardInfo} 提取到的身份证信息对象
+     */
+    private parseIDCardText;
+    /**
+     * 终止OCR引擎并释放资源
+     *
+     * @returns {Promise<void>} 终止完成的Promise
+     */
+    terminate(): Promise<void>;
+}