id-scanner-lib 1.0.0

package/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * @file ID扫描识别库主入口文件
+ * @description 提供身份证识别与二维码、条形码扫描功能的纯前端TypeScript库
+ * @module IDScannerLib
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { QRScanner, QRScannerOptions } from './scanner/qr-scanner';
+import { BarcodeScanner, BarcodeScannerOptions } from './scanner/barcode-scanner';
+import { IDCardDetector } from './id-recognition/id-detector';
+import { OCRProcessor } from './id-recognition/ocr-processor';
+import { DataExtractor } from './id-recognition/data-extractor';
+import { Camera, CameraOptions } from './utils/camera';
+import { ImageProcessor } from './utils/image-processing';
+import { IDCardInfo, DetectionResult } from './utils/types';
+
+/**
+ * IDScanner配置选项接口
+ * @interface IDScannerOptions
+ * @property {CameraOptions} [cameraOptions] - 相机配置选项
+ * @property {QRScannerOptions} [qrScannerOptions] - 二维码扫描配置选项
+ * @property {BarcodeScannerOptions} [barcodeScannerOptions] - 条形码扫描配置选项
+ * @property {Function} [onQRCodeScanned] - 二维码识别成功回调
+ * @property {Function} [onBarcodeScanned] - 条形码识别成功回调
+ * @property {Function} [onIDCardScanned] - 身份证识别成功回调
+ * @property {Function} [onError] - 错误处理回调
+ */
+export interface IDScannerOptions {
+  cameraOptions?: CameraOptions;
+  qrScannerOptions?: QRScannerOptions;
+  barcodeScannerOptions?: BarcodeScannerOptions;
+  onQRCodeScanned?: (result: string) => void;
+  onBarcodeScanned?: (result: string) => void;
+  onIDCardScanned?: (info: IDCardInfo) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * IDScanner 主类
+ * 
+ * 整合二维码、条形码扫描和身份证识别功能，提供统一的接口
+ * 
+ * @example
+ * ```typescript
+ * // 创建扫描器实例
+ * const scanner = new IDScanner({
+ *   onQRCodeScanned: (result) => {
+ *     console.log('扫描到二维码:', result);
+ *   },
+ *   onIDCardScanned: (info) => {
+ *     console.log('识别到身份证信息:', info);
+ *   }
+ * });
+ * 
+ * // 初始化OCR引擎和相关资源
+ * await scanner.initialize();
+ * 
+ * // 启动二维码扫描
+ * const videoElement = document.getElementById('video');
+ * await scanner.startQRScanner(videoElement);
+ * 
+ * // 停止扫描
+ * scanner.stop();
+ * 
+ * // 使用结束后释放资源
+ * scanner.terminate();
+ * ```
+ */
+export class IDScanner {
+  private qrScanner: QRScanner;
+  private barcodeScanner: BarcodeScanner;
+  private idDetector: IDCardDetector;
+  private ocrProcessor: OCRProcessor;
+  private scanMode: 'qr' | 'barcode' | 'idcard' = 'qr';
+  
+  /**
+   * 创建IDScanner实例
+   * @param {IDScannerOptions} [options] - 配置选项
+   */
+  constructor(private options: IDScannerOptions = {}) {
+    this.qrScanner = new QRScanner({
+      ...options.qrScannerOptions,
+      onScan: this.handleQRScan.bind(this),
+      onError: this.handleError.bind(this)
+    });
+    
+    this.barcodeScanner = new BarcodeScanner({
+      ...options.barcodeScannerOptions,
+      onScan: this.handleBarcodeScan.bind(this),
+      onError: this.handleError.bind(this)
+    });
+    
+    this.idDetector = new IDCardDetector(this.handleIDDetection.bind(this));
+    this.ocrProcessor = new OCRProcessor();
+  }
+  
+  /**
+   * 初始化OCR引擎和相关资源
+   * 
+   * @returns {Promise<void>} 初始化完成的Promise
+   * @throws 如果初始化失败，将抛出错误
+   */
+  async initialize(): Promise<void> {
+    try {
+      await this.ocrProcessor.initialize();
+    } catch (error) {
+      this.handleError(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  
+  /**
+   * 启动二维码扫描
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 启动完成的Promise
+   */
+  async startQRScanner(videoElement: HTMLVideoElement): Promise<void> {
+    this.scanMode = 'qr';
+    await this.qrScanner.start(videoElement);
+  }
+  
+  /**
+   * 启动条形码扫描
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 启动完成的Promise
+   */
+  async startBarcodeScanner(videoElement: HTMLVideoElement): Promise<void> {
+    this.scanMode = 'barcode';
+    await this.barcodeScanner.start(videoElement);
+  }
+  
+  /**
+   * 启动身份证扫描识别
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 启动完成的Promise
+   */
+  async startIDCardScanner(videoElement: HTMLVideoElement): Promise<void> {
+    this.scanMode = 'idcard';
+    await this.idDetector.start(videoElement);
+  }
+  
+  /**
+   * 停止当前扫描
+   */
+  stop(): void {
+    if (this.scanMode === 'qr') {
+      this.qrScanner.stop();
+    } else if (this.scanMode === 'barcode') {
+      this.barcodeScanner.stop();
+    } else {
+      this.idDetector.stop();
+    }
+  }
+  
+  /**
+   * 处理二维码扫描结果
+   * @private
+   * @param {string} result - 扫描到的二维码内容
+   */
+  private handleQRScan(result: string): void {
+    if (this.options.onQRCodeScanned) {
+      this.options.onQRCodeScanned(result);
+    }
+  }
+  
+  /**
+   * 处理条形码扫描结果
+   * @private
+   * @param {string} result - 扫描到的条形码内容
+   */
+  private handleBarcodeScan(result: string): void {
+    if (this.options.onBarcodeScanned) {
+      this.options.onBarcodeScanned(result);
+    }
+  }
+  
+  /**
+   * 处理身份证检测结果
+   * @private
+   * @param {DetectionResult} result - 身份证检测结果
+   */
+  private async handleIDDetection(result: DetectionResult): Promise<void> {
+    if (result.success && result.croppedImage) {
+      try {
+        const idInfo = await this.ocrProcessor.processIDCard(result.croppedImage);
+        
+        // 使用数据提取工具增强身份证信息
+        const enhancedInfo = DataExtractor.enhanceIDCardInfo(idInfo);
+        
+        if (this.options.onIDCardScanned) {
+          this.options.onIDCardScanned(enhancedInfo);
+        }
+      } catch (error) {
+        this.handleError(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  
+  /**
+   * 处理错误
+   * @private
+   * @param {Error} error - 错误对象
+   */
+  private handleError(error: Error): void {
+    if (this.options.onError) {
+      this.options.onError(error);
+    } else {
+      console.error('ID扫描器错误:', error);
+    }
+  }
+  
+  /**
+   * 终止所有扫描并释放资源
+   * 
+   * @returns {Promise<void>} 资源释放完成的Promise
+   */
+  async terminate(): Promise<void> {
+    this.stop();
+    await this.ocrProcessor.terminate();
+  }
+}
+
+// 导出公共API
+export { Camera, QRScanner, BarcodeScanner, IDCardDetector, OCRProcessor, DataExtractor, ImageProcessor };
+export type { CameraOptions, QRScannerOptions, BarcodeScannerOptions, IDCardInfo, DetectionResult }; 

package/src/scanner/barcode-scanner.ts

@@ -0,0 +1,164 @@
+/**
+ * @file 条形码扫描模块
+ * @description 提供实时条形码扫描和识别功能
+ * @module BarcodeScanner
+ */
+
+import { Camera } from '../utils/camera';
+import { ImageProcessor } from '../utils/image-processing';
+
+/**
+ * 条形码扫描器配置选项
+ * 
+ * @interface BarcodeScannerOptions
+ * @property {number} [scanInterval] - 扫描间隔时间(毫秒)，默认为200ms
+ * @property {Function} [onScan] - 扫描成功回调函数
+ * @property {Function} [onError] - 错误处理回调函数
+ */
+export interface BarcodeScannerOptions {
+  scanInterval?: number;
+  onScan?: (result: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 条形码扫描器类
+ * 
+ * 提供实时扫描和识别摄像头中的条形码的功能
+ * 注意：当前实现是简化版，实际项目中建议集成专门的条形码识别库如ZXing或Quagga.js
+ * 
+ * @example
+ * ```typescript
+ * // 创建条形码扫描器
+ * const barcodeScanner = new BarcodeScanner({
+ *   scanInterval: 100, // 每100ms扫描一次
+ *   onScan: (result) => {
+ *     console.log('扫描到条形码:', result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('扫描错误:', error);
+ *   }
+ * });
+ * 
+ * // 启动扫描
+ * const videoElement = document.getElementById('video') as HTMLVideoElement;
+ * await barcodeScanner.start(videoElement);
+ * 
+ * // 停止扫描
+ * barcodeScanner.stop();
+ * ```
+ */
+export class BarcodeScanner {
+  private camera: Camera;
+  private scanning = false;
+  private scanTimer: number | null = null;
+  
+  /**
+   * 创建条形码扫描器实例
+   * 
+   * @param {BarcodeScannerOptions} [options] - 扫描器配置选项
+   */
+  constructor(private options: BarcodeScannerOptions = {}) {
+    this.options = {
+      scanInterval: 200,
+      ...options
+    };
+    
+    this.camera = new Camera();
+  }
+  
+  /**
+   * 启动条形码扫描
+   * 
+   * 初始化相机并开始连续扫描视频帧中的条形码
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 启动完成的Promise
+   * @throws 如果无法访问相机，将通过onError回调报告错误
+   */
+  async start(videoElement: HTMLVideoElement): Promise<void> {
+    try {
+      await this.camera.initialize(videoElement);
+      this.scanning = true;
+      this.scan();
+    } catch (error) {
+      if (this.options.onError) {
+        this.options.onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  
+  /**
+   * 执行一次条形码扫描
+   * 
+   * 内部方法，捕获当前视频帧并尝试识别其中的条形码
+   * 
+   * @private
+   */
+  private scan(): void {
+    if (!this.scanning) return;
+    
+    const imageData = this.camera.captureFrame();
+    
+    if (imageData) {
+      try {
+        // 图像预处理，提高识别率
+        const enhancedImage = ImageProcessor.adjustBrightnessContrast(
+          ImageProcessor.toGrayscale(imageData),
+          10, // 亮度
+          20  // 对比度
+        );
+        
+        // 这里实际项目中可以集成第三方条形码扫描库
+        // 如 ZXing 或 QuaggaJS
+        // 简化实现，这里仅为示例
+        this.detectBarcode(enhancedImage);
+      } catch (error) {
+        console.error('条形码扫描错误:', error);
+      }
+    }
+    
+    this.scanTimer = window.setTimeout(() => this.scan(), this.options.scanInterval);
+  }
+  
+  /**
+   * 条形码检测方法
+   * 
+   * 注意：这是一个简化实现，实际需要集成专门的条形码识别库
+   * 
+   * @private
+   * @param {ImageData} imageData - 要检测条形码的图像数据
+   */
+  private detectBarcode(imageData: ImageData): void {
+    // 这里应集成条形码识别库
+    // 如 ZXing 或 QuaggaJS
+    
+    // 简化示例，实际项目中请替换为真实实现
+    console.log('正在扫描条形码...');
+    
+    // 模拟找到条形码
+    if (Math.random() > 0.95) {
+      const mockResult = '6901234567890'; // 模拟条形码结果
+      
+      if (this.options.onScan) {
+        this.options.onScan(mockResult);
+      }
+    }
+  }
+  
+  /**
+   * 停止条形码扫描
+   * 
+   * 停止扫描循环并释放相机资源
+   */
+  stop(): void {
+    this.scanning = false;
+    
+    if (this.scanTimer) {
+      clearTimeout(this.scanTimer);
+      this.scanTimer = null;
+    }
+    
+    this.camera.release();
+  }
+} 

package/src/scanner/qr-scanner.ts

@@ -0,0 +1,128 @@
+/**
+ * @file 二维码扫描模块
+ * @description 提供实时二维码扫描和识别功能
+ * @module QRScanner
+ */
+
+import jsQR from 'jsqr';
+import { Camera } from '../utils/camera';
+
+/**
+ * 二维码扫描器配置选项
+ * 
+ * @interface QRScannerOptions
+ * @property {number} [scanInterval] - 扫描间隔时间(毫秒)，默认为200ms
+ * @property {Function} [onScan] - 扫描成功回调函数
+ * @property {Function} [onError] - 错误处理回调函数
+ */
+export interface QRScannerOptions {
+  scanInterval?: number;
+  onScan?: (result: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 二维码扫描器类
+ * 
+ * 提供实时扫描和识别摄像头中的二维码的功能
+ * 
+ * @example
+ * ```typescript
+ * // 创建二维码扫描器
+ * const qrScanner = new QRScanner({
+ *   scanInterval: 100, // 每100ms扫描一次
+ *   onScan: (result) => {
+ *     console.log('扫描到二维码:', result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('扫描错误:', error);
+ *   }
+ * });
+ * 
+ * // 启动扫描
+ * const videoElement = document.getElementById('video') as HTMLVideoElement;
+ * await qrScanner.start(videoElement);
+ * 
+ * // 停止扫描
+ * qrScanner.stop();
+ * ```
+ */
+export class QRScanner {
+  private camera: Camera;
+  private scanning = false;
+  private scanTimer: number | null = null;
+  
+  /**
+   * 创建二维码扫描器实例
+   * 
+   * @param {QRScannerOptions} [options] - 扫描器配置选项
+   */
+  constructor(private options: QRScannerOptions = {}) {
+    this.options = {
+      scanInterval: 200,
+      ...options
+    };
+    
+    this.camera = new Camera();
+  }
+  
+  /**
+   * 启动二维码扫描
+   * 
+   * 初始化相机并开始连续扫描视频帧中的二维码
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 启动完成的Promise
+   * @throws 如果无法访问相机，将通过onError回调报告错误
+   */
+  async start(videoElement: HTMLVideoElement): Promise<void> {
+    try {
+      await this.camera.initialize(videoElement);
+      this.scanning = true;
+      this.scan();
+    } catch (error) {
+      if (this.options.onError) {
+        this.options.onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  
+  /**
+   * 执行一次二维码扫描
+   * 
+   * 内部方法，捕获当前视频帧并尝试识别其中的二维码
+   * 
+   * @private
+   */
+  private scan(): void {
+    if (!this.scanning) return;
+    
+    const imageData = this.camera.captureFrame();
+    
+    if (imageData) {
+      const code = jsQR(imageData.data, imageData.width, imageData.height);
+      
+      if (code && this.options.onScan) {
+        this.options.onScan(code.data);
+      }
+    }
+    
+    this.scanTimer = window.setTimeout(() => this.scan(), this.options.scanInterval);
+  }
+  
+  /**
+   * 停止二维码扫描
+   * 
+   * 停止扫描循环并释放相机资源
+   */
+  stop(): void {
+    this.scanning = false;
+    
+    if (this.scanTimer) {
+      clearTimeout(this.scanTimer);
+      this.scanTimer = null;
+    }
+    
+    this.camera.release();
+  }
+} 

package/src/utils/camera.ts

@@ -0,0 +1,139 @@
+/**
+ * @file 相机工具类
+ * @description 提供访问和控制设备摄像头的功能
+ * @module Camera
+ */
+
+/**
+ * 相机配置选项接口
+ * 
+ * @interface CameraOptions
+ * @property {number} [width] - 视频宽度，默认为640
+ * @property {number} [height] - 视频高度，默认为480
+ * @property {string} [facingMode] - 摄像头朝向，'user'为前置摄像头，'environment'为后置摄像头，默认为'environment'
+ */
+export interface CameraOptions {
+  width?: number;
+  height?: number;
+  facingMode?: 'user' | 'environment';
+}
+
+/**
+ * 相机工具类
+ * 
+ * 提供访问设备摄像头、获取视频流以及捕获图像帧的功能
+ * 
+ * @example
+ * ```typescript
+ * // 创建相机实例
+ * const camera = new Camera({
+ *   width: 1280,
+ *   height: 720,
+ *   facingMode: 'environment' // 使用后置摄像头
+ * });
+ * 
+ * // 初始化相机
+ * const videoElement = document.getElementById('video') as HTMLVideoElement;
+ * await camera.initialize(videoElement);
+ * 
+ * // 捕获当前视频帧
+ * const imageData = camera.captureFrame();
+ * 
+ * // 使用结束后释放资源
+ * camera.release();
+ * ```
+ */
+export class Camera {
+  private stream: MediaStream | null = null;
+  private videoElement: HTMLVideoElement | null = null;
+  
+  /**
+   * 创建相机实例
+   * 
+   * @param {CameraOptions} [options] - 相机配置选项
+   */
+  constructor(private options: CameraOptions = {}) {
+    this.options = {
+      width: 640,
+      height: 480,
+      facingMode: 'environment',
+      ...options
+    };
+  }
+  
+  /**
+   * 初始化相机，请求摄像头权限并设置视频流
+   * 
+   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @returns {Promise<void>} 初始化完成的Promise
+   * @throws 如果无法访问相机，将抛出错误
+   */
+  async initialize(videoElement: HTMLVideoElement): Promise<void> {
+    try {
+      this.videoElement = videoElement;
+      
+      const constraints: MediaStreamConstraints = {
+        video: {
+          width: this.options.width,
+          height: this.options.height,
+          facingMode: this.options.facingMode
+        }
+      };
+      
+      this.stream = await navigator.mediaDevices.getUserMedia(constraints);
+      this.videoElement.srcObject = this.stream;
+      
+      return new Promise((resolve) => {
+        if (this.videoElement) {
+          this.videoElement.onloadedmetadata = () => {
+            if (this.videoElement) {
+              this.videoElement.play();
+              resolve();
+            }
+          };
+        }
+      });
+    } catch (error) {
+      console.error('相机初始化失败:', error);
+      throw new Error('无法访问相机');
+    }
+  }
+  
+  /**
+   * 获取当前视频帧
+   * 
+   * 捕获当前视频画面并转换为ImageData对象，可用于图像处理和分析
+   * 
+   * @returns {ImageData|null} 当前视频帧的ImageData对象，如果未初始化视频则返回null
+   */
+  captureFrame(): ImageData | null {
+    if (!this.videoElement) return null;
+    
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+    
+    canvas.width = this.videoElement.videoWidth;
+    canvas.height = this.videoElement.videoHeight;
+    ctx.drawImage(this.videoElement, 0, 0);
+    
+    return ctx.getImageData(0, 0, canvas.width, canvas.height);
+  }
+  
+  /**
+   * 释放相机资源
+   * 
+   * 停止所有视频流轨道并清理资源。在不再需要相机时应调用此方法。
+   */
+  release(): void {
+    if (this.stream) {
+      this.stream.getTracks().forEach(track => track.stop());
+      this.stream = null;
+    }
+    
+    if (this.videoElement) {
+      this.videoElement.srcObject = null;
+      this.videoElement = null;
+    }
+  }
+}