id-scanner-lib 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @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 declare class IDScanner {
+    private options;
+    private qrScanner;
+    private barcodeScanner;
+    private idDetector;
+    private ocrProcessor;
+    private scanMode;
+    /**
+     * 创建IDScanner实例
+     * @param {IDScannerOptions} [options] - 配置选项
+     */
+    constructor(options?: IDScannerOptions);
+    /**
+     * 初始化OCR引擎和相关资源
+     *
+     * @returns {Promise<void>} 初始化完成的Promise
+     * @throws 如果初始化失败，将抛出错误
+     */
+    initialize(): Promise<void>;
+    /**
+     * 启动二维码扫描
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     */
+    startQRScanner(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 启动条形码扫描
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     */
+    startBarcodeScanner(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 启动身份证扫描识别
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     */
+    startIDCardScanner(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 停止当前扫描
+     */
+    stop(): void;
+    /**
+     * 处理二维码扫描结果
+     * @private
+     * @param {string} result - 扫描到的二维码内容
+     */
+    private handleQRScan;
+    /**
+     * 处理条形码扫描结果
+     * @private
+     * @param {string} result - 扫描到的条形码内容
+     */
+    private handleBarcodeScan;
+    /**
+     * 处理身份证检测结果
+     * @private
+     * @param {DetectionResult} result - 身份证检测结果
+     */
+    private handleIDDetection;
+    /**
+     * 处理错误
+     * @private
+     * @param {Error} error - 错误对象
+     */
+    private handleError;
+    /**
+     * 终止所有扫描并释放资源
+     *
+     * @returns {Promise<void>} 资源释放完成的Promise
+     */
+    terminate(): Promise<void>;
+}
+export { Camera, QRScanner, BarcodeScanner, IDCardDetector, OCRProcessor, DataExtractor, ImageProcessor };
+export type { CameraOptions, QRScannerOptions, BarcodeScannerOptions, IDCardInfo, DetectionResult };

package/dist/scanner/barcode-scanner.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file 条形码扫描模块
+ * @description 提供实时条形码扫描和识别功能
+ * @module BarcodeScanner
+ */
+/**
+ * 条形码扫描器配置选项
+ *
+ * @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 declare class BarcodeScanner {
+    private options;
+    private camera;
+    private scanning;
+    private scanTimer;
+    /**
+     * 创建条形码扫描器实例
+     *
+     * @param {BarcodeScannerOptions} [options] - 扫描器配置选项
+     */
+    constructor(options?: BarcodeScannerOptions);
+    /**
+     * 启动条形码扫描
+     *
+     * 初始化相机并开始连续扫描视频帧中的条形码
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     * @throws 如果无法访问相机，将通过onError回调报告错误
+     */
+    start(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 执行一次条形码扫描
+     *
+     * 内部方法，捕获当前视频帧并尝试识别其中的条形码
+     *
+     * @private
+     */
+    private scan;
+    /**
+     * 条形码检测方法
+     *
+     * 注意：这是一个简化实现，实际需要集成专门的条形码识别库
+     *
+     * @private
+     * @param {ImageData} imageData - 要检测条形码的图像数据
+     */
+    private detectBarcode;
+    /**
+     * 停止条形码扫描
+     *
+     * 停止扫描循环并释放相机资源
+     */
+    stop(): void;
+}

package/dist/scanner/qr-scanner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file 二维码扫描模块
+ * @description 提供实时二维码扫描和识别功能
+ * @module QRScanner
+ */
+/**
+ * 二维码扫描器配置选项
+ *
+ * @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 declare class QRScanner {
+    private options;
+    private camera;
+    private scanning;
+    private scanTimer;
+    /**
+     * 创建二维码扫描器实例
+     *
+     * @param {QRScannerOptions} [options] - 扫描器配置选项
+     */
+    constructor(options?: QRScannerOptions);
+    /**
+     * 启动二维码扫描
+     *
+     * 初始化相机并开始连续扫描视频帧中的二维码
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 启动完成的Promise
+     * @throws 如果无法访问相机，将通过onError回调报告错误
+     */
+    start(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 执行一次二维码扫描
+     *
+     * 内部方法，捕获当前视频帧并尝试识别其中的二维码
+     *
+     * @private
+     */
+    private scan;
+    /**
+     * 停止二维码扫描
+     *
+     * 停止扫描循环并释放相机资源
+     */
+    stop(): void;
+}

package/dist/utils/camera.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 declare class Camera {
+    private options;
+    private stream;
+    private videoElement;
+    /**
+     * 创建相机实例
+     *
+     * @param {CameraOptions} [options] - 相机配置选项
+     */
+    constructor(options?: CameraOptions);
+    /**
+     * 初始化相机，请求摄像头权限并设置视频流
+     *
+     * @param {HTMLVideoElement} videoElement - 用于显示相机画面的video元素
+     * @returns {Promise<void>} 初始化完成的Promise
+     * @throws 如果无法访问相机，将抛出错误
+     */
+    initialize(videoElement: HTMLVideoElement): Promise<void>;
+    /**
+     * 获取当前视频帧
+     *
+     * 捕获当前视频画面并转换为ImageData对象，可用于图像处理和分析
+     *
+     * @returns {ImageData|null} 当前视频帧的ImageData对象，如果未初始化视频则返回null
+     */
+    captureFrame(): ImageData | null;
+    /**
+     * 释放相机资源
+     *
+     * 停止所有视频流轨道并清理资源。在不再需要相机时应调用此方法。
+     */
+    release(): void;
+}

package/dist/utils/image-processing.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @file 图像处理工具类
+ * @description 提供图像处理相关的辅助功能
+ * @module ImageProcessor
+ */
+/**
+ * 图像处理工具类
+ *
+ * 提供常用的图像处理功能，如亮度和对比度调整、灰度转换、图像大小调整等。
+ * 这些功能可用于增强图像质量，提高OCR和扫描的识别率。
+ *
+ * @example
+ * ```typescript
+ * // 使用图像处理功能增强图像
+ * const enhancedImage = ImageProcessor.adjustBrightnessContrast(
+ *   originalImageData,
+ *   15,  // 增加亮度
+ *   25   // 增加对比度
+ * );
+ *
+ * // 转换为灰度图像
+ * const grayImage = ImageProcessor.toGrayscale(originalImageData);
+ * ```
+ */
+export declare class ImageProcessor {
+    /**
+     * 将ImageData转换为Canvas元素
+     *
+     * @param {ImageData} imageData - 要转换的图像数据
+     * @returns {HTMLCanvasElement} 包含图像的Canvas元素
+     */
+    static imageDataToCanvas(imageData: ImageData): HTMLCanvasElement;
+    /**
+     * 将Canvas转换为ImageData
+     *
+     * @param {HTMLCanvasElement} canvas - 要转换的Canvas元素
+     * @returns {ImageData|null} Canvas的图像数据，如果获取失败则返回null
+     */
+    static canvasToImageData(canvas: HTMLCanvasElement): ImageData | null;
+    /**
+     * 调整图像亮度和对比度
+     *
+     * @param {ImageData} imageData - 要处理的图像数据
+     * @param {number} [brightness=0] - 亮度调整值，正值增加亮度，负值降低亮度，范围建议为-100到100
+     * @param {number} [contrast=0] - 对比度调整值，正值增加对比度，负值降低对比度，范围建议为-100到100
+     * @returns {ImageData} 处理后的图像数据
+     */
+    static adjustBrightnessContrast(imageData: ImageData, brightness?: number, contrast?: number): ImageData;
+    /**
+     * 确保值在0-255范围内
+     *
+     * @private
+     * @param {number} value - 要截断的值
+     * @returns {number} 截断后的值，范围为0-255
+     */
+    private static truncate;
+    /**
+     * 将彩色图像转换为灰度图像
+     *
+     * 灰度转换可以简化图像，提高OCR和条形码识别的准确率
+     *
+     * @param {ImageData} imageData - 要转换的彩色图像
+     * @returns {ImageData} 转换后的灰度图像
+     */
+    static toGrayscale(imageData: ImageData): ImageData;
+    /**
+     * 调整图像大小
+     *
+     * @param {ImageData} imageData - 原图像数据
+     * @param {number} newWidth - 新宽度
+     * @param {number} newHeight - 新高度
+     * @returns {ImageData} 调整大小后的图像数据
+     */
+    static resize(imageData: ImageData, newWidth: number, newHeight: number): ImageData;
+}

package/dist/utils/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file 类型定义文件
+ * @description 定义库中使用的公共类型和接口
+ * @module Types
+ */
+/**
+ * 身份证检测结果接口
+ *
+ * 包含身份证检测的结果信息，如是否成功检测到身份证、身份证的四个角点坐标以及裁剪后的身份证图像
+ *
+ * @interface DetectionResult
+ * @property {boolean} success - 是否成功检测到身份证
+ * @property {Object[]} [corners] - 检测到的身份证四个角点坐标
+ * @property {number} corners[].x - 角点X坐标
+ * @property {number} corners[].y - 角点Y坐标
+ * @property {ImageData} [croppedImage] - 裁剪后的身份证图像
+ */
+export interface DetectionResult {
+    success: boolean;
+    corners?: {
+        x: number;
+        y: number;
+    }[];
+    croppedImage?: ImageData;
+}
+/**
+ * 身份证信息接口
+ *
+ * 包含从身份证中提取的各项个人信息
+ *
+ * @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} [issuingAuthority] - 签发机关
+ * @property {string} [validPeriod] - 有效期限
+ *
+ * @example
+ * ```typescript
+ * // 身份证信息示例
+ * const idInfo: IDCardInfo = {
+ *   name: '张三',
+ *   gender: '男',
+ *   nationality: '汉族',
+ *   birthDate: '1990-01-01',
+ *   address: '北京市海淀区xxxxx',
+ *   idNumber: '110101199001011234',
+ *   issuingAuthority: '北京市公安局海淀分局',
+ *   validPeriod: '2020.01.01-2040.01.01'
+ * };
+ * ```
+ */
+export interface IDCardInfo {
+    name?: string;
+    gender?: string;
+    nationality?: string;
+    birthDate?: string;
+    address?: string;
+    idNumber?: string;
+    issuingAuthority?: string;
+    validPeriod?: string;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "id-scanner-lib",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/id-scanner.js",
+  "module": "dist/id-scanner.esm.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "id-card",
+    "qr-code",
+    "scanner",
+    "ocr"
+  ],
+  "author": "agions",
+  "license": "MIT",
+  "description": "一款纯前端实现的TypeScript身份证&二维码识别库，无需后端支持，所有处理在浏览器端完成",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agions/id-scanner-lib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agions/id-scanner-lib/issues"
+  },
+  "homepage": "https://github.com/agions/id-scanner-lib#readme",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^22.13.10",
+    "rollup": "^4.35.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "jsqr": "^1.4.0",
+    "lodash-es": "^4.17.21",
+    "tesseract.js": "^6.0.0"
+  }
+}

package/src/demo/demo.ts

@@ -0,0 +1,88 @@
+import { IDScanner, IDCardInfo } from '../index';
+
+export class IDScannerDemo {
+  private scanner: IDScanner;
+  private videoElement: HTMLVideoElement;
+  private resultContainer: HTMLElement;
+  private switchButton: HTMLButtonElement;
+  
+  constructor(videoElementId: string, resultContainerId: string, switchButtonId: string) {
+    this.videoElement = document.getElementById(videoElementId) as HTMLVideoElement;
+    this.resultContainer = document.getElementById(resultContainerId) as HTMLElement;
+    this.switchButton = document.getElementById(switchButtonId) as HTMLButtonElement;
+    
+    this.scanner = new IDScanner({
+      onQRCodeScanned: this.handleQRCodeResult.bind(this),
+      onBarcodeScanned: this.handleQRCodeResult.bind(this), // 复用QR码结果处理
+      onIDCardScanned: this.handleIDCardResult.bind(this),
+      onError: this.handleError.bind(this)
+    });
+    
+    this.switchButton.addEventListener('click', this.toggleScanMode.bind(this));
+  }
+  
+  async initialize(): Promise<void> {
+    await this.scanner.initialize();
+    await this.scanner.startQRScanner(this.videoElement);
+    this.switchButton.textContent = '切换到身份证模式';
+    this.currentMode = 'qr';
+  }
+  
+  private currentMode: 'qr' | 'barcode' | 'idcard' = 'qr';
+  
+  private async toggleScanMode(): Promise<void> {
+    this.scanner.stop();
+    
+    if (this.currentMode === 'qr') {
+      this.currentMode = 'barcode';
+      await this.scanner.startBarcodeScanner(this.videoElement);
+      this.switchButton.textContent = '切换到身份证模式';
+    } else if (this.currentMode === 'barcode') {
+      this.currentMode = 'idcard';
+      await this.scanner.startIDCardScanner(this.videoElement);
+      this.switchButton.textContent = '切换到二维码模式';
+    } else {
+      this.currentMode = 'qr';
+      await this.scanner.startQRScanner(this.videoElement);
+      this.switchButton.textContent = '切换到条形码模式';
+    }
+    
+    this.resultContainer.innerHTML = '';
+  }
+  
+  private handleQRCodeResult(result: string): void {
+    this.resultContainer.innerHTML = `
+      <h3>扫描结果:</h3>
+      <p>${result}</p>
+    `;
+  }
+  
+  private handleIDCardResult(info: IDCardInfo): void {
+    this.resultContainer.innerHTML = `
+      <h3>身份证信息:</h3>
+      <p>姓名: ${info.name || '未识别'}</p>
+      <p>性别: ${info.gender || '未识别'}</p>
+      <p>民族: ${info.nationality || '未识别'}</p>
+      <p>出生日期: ${info.birthDate || '未识别'}</p>
+      <p>地址: ${info.address || '未识别'}</p>
+      <p>身份证号: ${info.idNumber || '未识别'}</p>
+      <p>签发机关: ${info.issuingAuthority || '未识别'}</p>
+      <p>有效期限: ${info.validPeriod || '未识别'}</p>
+    `;
+  }
+  
+  private handleError(error: Error): void {
+    console.error('扫描错误:', error);
+    this.resultContainer.innerHTML = `
+      <div class="error">
+        <h3>错误:</h3>
+        <p>${error.message}</p>
+      </div>
+    `;
+  }
+  
+  stop(): void {
+    this.scanner.stop();
+    this.scanner.terminate();
+  }
+}