id-scanner-lib 1.0.0 → 1.1.1

package/src/ocr-module.ts

@@ -0,0 +1,139 @@
+/**
+ * @file OCR模块入口文件
+ * @description 包含身份证OCR识别相关功能
+ * @module IDScannerOCR
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { Camera, CameraOptions } from './utils/camera';
+import { ImageProcessor } from './utils/image-processing';
+import { IDCardInfo, DetectionResult } from './utils/types';
+import { IDCardDetector, IDCardDetectorOptions } from './id-recognition/id-detector';
+import { OCRProcessor } from './id-recognition/ocr-processor';
+import { DataExtractor } from './id-recognition/data-extractor';
+
+/**
+ * OCR模块配置选项
+ */
+export interface OCRModuleOptions {
+  cameraOptions?: CameraOptions;
+  onIDCardScanned?: (info: IDCardInfo) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * OCR模块类
+ * 
+ * 提供身份证检测和OCR文字识别功能
+ */
+export class OCRModule {
+  private idDetector: IDCardDetector;
+  private ocrProcessor: OCRProcessor;
+  private dataExtractor: DataExtractor;
+  private camera: Camera;
+  private isRunning: boolean = false;
+  private videoElement: HTMLVideoElement | null = null;
+  
+  /**
+   * 构造函数
+   * @param options 配置选项
+   */
+  constructor(private options: OCRModuleOptions = {}) {
+    this.camera = new Camera(options.cameraOptions);
+    this.idDetector = new IDCardDetector({
+      onDetection: this.handleIDDetection.bind(this),
+      onError: this.handleError.bind(this)
+    } as IDCardDetectorOptions);
+    this.ocrProcessor = new OCRProcessor();
+    this.dataExtractor = new DataExtractor();
+  }
+  
+  /**
+   * 初始化OCR引擎
+   * 
+   * @returns Promise<void>
+   */
+  async initialize(): Promise<void> {
+    try {
+      await this.ocrProcessor.initialize();
+      console.log('OCR engine initialized');
+    } catch (error) {
+      this.handleError(error as Error);
+      throw error;
+    }
+  }
+  
+  /**
+   * 启动身份证扫描
+   * @param videoElement HTML视频元素
+   */
+  async startIDCardScanner(videoElement: HTMLVideoElement): Promise<void> {
+    if (!this.ocrProcessor) {
+      throw new Error('OCR engine not initialized. Call initialize() first.');
+    }
+    
+    this.videoElement = videoElement;
+    this.isRunning = true;
+    await this.camera.start(videoElement);
+    this.idDetector.start(videoElement);
+  }
+  
+  /**
+   * 停止扫描
+   */
+  stop(): void {
+    this.isRunning = false;
+    this.idDetector.stop();
+    this.camera.stop();
+  }
+  
+  /**
+   * 处理身份证检测结果
+   */
+  private async handleIDDetection(result: DetectionResult): Promise<void> {
+    if (!this.isRunning) return;
+    
+    try {
+      // 检查 imageData 是否存在
+      if (!result.imageData) {
+        this.handleError(new Error('无效的图像数据'));
+        return;
+      }
+      
+      const idCardInfo = await this.ocrProcessor.processIDCard(result.imageData);
+      const extractedInfo = this.dataExtractor.extractAndValidate(idCardInfo);
+      
+      if (this.options.onIDCardScanned) {
+        this.options.onIDCardScanned(extractedInfo);
+      }
+    } catch (error) {
+      this.handleError(error as Error);
+    }
+  }
+  
+  /**
+   * 处理错误
+   */
+  private handleError(error: Error): void {
+    if (this.options.onError) {
+      this.options.onError(error);
+    } else {
+      console.error('OCRModule error:', error);
+    }
+  }
+  
+  /**
+   * 释放资源
+   */
+  async terminate(): Promise<void> {
+    this.stop();
+    await this.ocrProcessor.terminate();
+  }
+}
+
+// 导出相关类型和工具
+export { IDCardDetector } from './id-recognition/id-detector';
+export { OCRProcessor } from './id-recognition/ocr-processor';
+export { DataExtractor } from './id-recognition/data-extractor';
+export { IDCardInfo } from './utils/types'; 

package/src/qr-module.ts

@@ -0,0 +1,129 @@
+/**
+ * @file 二维码和条形码扫描模块
+ * @description 包含二维码和条形码扫描功能
+ * @module IDScannerQR
+ * @version 1.0.0
+ * @license MIT
+ */
+
+import { QRScanner, QRScannerOptions } from './scanner/qr-scanner';
+import { BarcodeScanner, BarcodeScannerOptions } from './scanner/barcode-scanner';
+import { Camera, CameraOptions } from './utils/camera';
+
+/**
+ * 扫描模块配置选项
+ */
+export interface ScannerModuleOptions {
+  cameraOptions?: CameraOptions;
+  qrScannerOptions?: QRScannerOptions;
+  barcodeScannerOptions?: BarcodeScannerOptions;
+  onQRCodeScanned?: (result: string) => void;
+  onBarcodeScanned?: (result: string) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 扫描模块类
+ * 
+ * 提供独立的二维码和条形码扫描功能
+ */
+export class ScannerModule {
+  private qrScanner: QRScanner;
+  private barcodeScanner: BarcodeScanner;
+  private camera: Camera;
+  private scanMode: 'qr' | 'barcode' | null = null;
+  private videoElement: HTMLVideoElement | null = null;
+  
+  /**
+   * 构造函数
+   * @param options 配置选项
+   */
+  constructor(private options: ScannerModuleOptions = {}) {
+    this.camera = new Camera(options.cameraOptions);
+    this.qrScanner = new QRScanner({
+      ...options.qrScannerOptions,
+      onScan: this.handleQRScan.bind(this)
+    });
+    this.barcodeScanner = new BarcodeScanner({
+      ...options.barcodeScannerOptions,
+      onScan: this.handleBarcodeScan.bind(this)
+    });
+  }
+  
+  /**
+   * 启动二维码扫描
+   * @param videoElement HTML视频元素
+   */
+  async startQRScanner(videoElement: HTMLVideoElement): Promise<void> {
+    this.stop(); // 确保先停止可能正在运行的扫描
+    
+    this.videoElement = videoElement;
+    this.scanMode = 'qr';
+    await this.camera.start(videoElement);
+    this.qrScanner.start(videoElement);
+  }
+  
+  /**
+   * 启动条形码扫描
+   * @param videoElement HTML视频元素
+   */
+  async startBarcodeScanner(videoElement: HTMLVideoElement): Promise<void> {
+    this.stop(); // 确保先停止可能正在运行的扫描
+    
+    this.videoElement = videoElement;
+    this.scanMode = 'barcode';
+    await this.camera.start(videoElement);
+    this.barcodeScanner.start(videoElement);
+  }
+  
+  /**
+   * 停止扫描
+   */
+  stop(): void {
+    if (this.scanMode === 'qr') {
+      this.qrScanner.stop();
+    } else if (this.scanMode === 'barcode') {
+      this.barcodeScanner.stop();
+    }
+    
+    if (this.videoElement) {
+      this.camera.stop();
+    }
+    
+    this.scanMode = null;
+  }
+  
+  /**
+   * 处理二维码扫描结果
+   */
+  private handleQRScan(result: string): void {
+    if (this.options.onQRCodeScanned) {
+      this.options.onQRCodeScanned(result);
+    }
+  }
+  
+  /**
+   * 处理条形码扫描结果
+   */
+  private handleBarcodeScan(result: string): void {
+    if (this.options.onBarcodeScanned) {
+      this.options.onBarcodeScanned(result);
+    }
+  }
+  
+  /**
+   * 处理错误
+   */
+  private handleError(error: Error): void {
+    if (this.options.onError) {
+      this.options.onError(error);
+    } else {
+      console.error('ScannerModule error:', error);
+    }
+  }
+}
+
+// 导出相关类型和工具
+export { QRScanner, QRScannerOptions } from './scanner/qr-scanner';
+export { BarcodeScanner, BarcodeScannerOptions } from './scanner/barcode-scanner';
+export { Camera, CameraOptions } from './utils/camera'; 

package/src/utils/camera.ts

@@ -34,13 +34,13 @@ export interface CameraOptions {
  * 
  * // 初始化相机
  * const videoElement = document.getElementById('video') as HTMLVideoElement;
- * await camera.initialize(videoElement);
+ * await camera.start(videoElement);
  * 
  * // 捕获当前视频帧
  * const imageData = camera.captureFrame();
  * 
  * // 使用结束后释放资源
- * camera.release();
+ * camera.stop();
  * ```
  */
 export class Camera {
@@ -49,7 +49,6 @@ export class Camera {
   
   /**
    * 创建相机实例
-   * 
    * @param {CameraOptions} [options] - 相机配置选项
    */
   constructor(private options: CameraOptions = {}) {
@@ -62,75 +61,101 @@ export class Camera {
   }
   
   /**
-   * 初始化相机，请求摄像头权限并设置视频流
+   * 启动摄像头并将视频流绑定到视频元素
+   * @param videoElement HTML视频元素
+   * @returns Promise<void>
+   */
+  async start(videoElement: HTMLVideoElement): Promise<void> {
+    return this.initialize(videoElement);
+  }
+  
+  /**
+   * 停止摄像头并释放资源
+   */
+  stop(): void {
+    this.release();
+  }
+  
+  /**
+   * 初始化相机，获取视频流并绑定到视频元素
    * 
-   * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+   * @param {HTMLVideoElement} videoElement - 用于显示视频流的视频元素
    * @returns {Promise<void>} 初始化完成的Promise
-   * @throws 如果无法访问相机，将抛出错误
+   * @throws 如果无法访问摄像头，将抛出错误
    */
   async initialize(videoElement: HTMLVideoElement): Promise<void> {
+    this.videoElement = videoElement;
+    
     try {
-      this.videoElement = videoElement;
-      
+      // 构建媒体约束
       const constraints: MediaStreamConstraints = {
         video: {
-          width: this.options.width,
-          height: this.options.height,
+          width: { ideal: this.options.width },
+          height: { ideal: 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();
-            }
-          };
-        }
-      });
+      // 绑定到视频元素
+      if (this.videoElement) {
+        this.videoElement.srcObject = this.stream;
+        await new Promise<void>((resolve) => {
+          if (this.videoElement) {
+            this.videoElement.onloadedmetadata = () => {
+              if (this.videoElement) {
+                this.videoElement.play().then(() => resolve());
+              }
+            };
+          }
+        });
+      }
     } catch (error) {
-      console.error('相机初始化失败:', error);
-      throw new Error('无法访问相机');
+      console.error('无法访问摄像头:', error);
+      throw new Error('无法访问摄像头。请确保已授予摄像头访问权限，并且摄像头未被其他应用程序占用。');
     }
   }
   
   /**
-   * 获取当前视频帧
-   * 
-   * 捕获当前视频画面并转换为ImageData对象，可用于图像处理和分析
+   * 捕获当前视频帧
    * 
-   * @returns {ImageData|null} 当前视频帧的ImageData对象，如果未初始化视频则返回null
+   * @returns {ImageData|null} 视频帧的ImageData对象，如果未初始化则返回null
    */
   captureFrame(): ImageData | null {
-    if (!this.videoElement) return null;
+    if (!this.videoElement) {
+      return null;
+    }
     
+    // 创建Canvas元素用于捕获视频帧
     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);
+    const context = canvas.getContext('2d');
+    if (!context) {
+      return null;
+    }
+    
+    // 将视频内容绘制到Canvas中
+    context.drawImage(this.videoElement, 0, 0, canvas.width, canvas.height);
+    
+    // 获取ImageData对象
+    return context.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;

package/src/utils/types.ts

@@ -1,6 +1,6 @@
 /**
  * @file 类型定义文件
- * @description 定义库中使用的公共类型和接口
+ * @description 定义全局类型
  * @module Types
  */
 
@@ -15,11 +15,28 @@
  * @property {number} corners[].x - 角点X坐标
  * @property {number} corners[].y - 角点Y坐标
  * @property {ImageData} [croppedImage] - 裁剪后的身份证图像
+ * @property {ImageData} [imageData] - 原始图像数据
+ * @property {Object} [boundingBox] - 检测到的身份证边界框
+ * @property {number} boundingBox.x - 边界框左上角X坐标
+ * @property {number} boundingBox.y - 边界框左上角Y坐标
+ * @property {number} boundingBox.width - 边界框宽度
+ * @property {number} boundingBox.height - 边界框高度
+ * @property {number} [confidence] - 检测结果的置信度
+ * @property {string} [message] - 检测结果的消息
  */
 export interface DetectionResult {
   success: boolean;
   corners?: { x: number; y: number }[];
   croppedImage?: ImageData;
+  imageData?: ImageData;
+  boundingBox?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  confidence?: number;
+  message?: string;
 }
 
 /**
@@ -29,11 +46,11 @@ export interface DetectionResult {
  * 
  * @interface IDCardInfo
  * @property {string} [name] - 姓名
- * @property {string} [gender] - 性别，通常为"男"或"女"
- * @property {string} [nationality] - 民族，如"汉族"、"满族"等
- * @property {string} [birthDate] - 出生日期，格式为"YYYY-MM-DD"
- * @property {string} [address] - 住址
- * @property {string} [idNumber] - 身份证号码，18位
+ * @property {string} [gender] - 性别
+ * @property {string} [nationality] - 民族
+ * @property {string} [birthDate] - 出生日期
+ * @property {string} [address] - 地址
+ * @property {string} [idNumber] - 身份证号码
  * @property {string} [issuingAuthority] - 签发机关
  * @property {string} [validPeriod] - 有效期限
  *