id-scanner-lib 1.6.6 → 1.7.0

package/src/utils/image-processing.ts

@@ -2,11 +2,13 @@
  * @file 图像处理工具类
  * @description 提供图像预处理功能，用于提高OCR识别率
  * @module ImageProcessor
- * @version 1.3.2
+ * @version 1.4.0
  */
 
 import imageCompression from "browser-image-compression"
 import { Point, Rect, ImageProcessingOptions } from './types';
+import { CanvasPool } from './canvas-pool';
+import { EdgeDetector } from './edge-detector';
 
 /**
  * 图像处理器配置选项
@@ -18,6 +20,8 @@ export interface ImageProcessorOptions {
   invert?: boolean // 是否反转颜色
   blur?: number // 模糊程度 (0-10)
   sharpen?: boolean // 是否锐化
+  /** 是否使用 Canvas 对象池（减少内存分配） */
+  usePool?: boolean;
 }
 
 /**
@@ -44,17 +48,27 @@ export class ImageProcessor {
    * @param {ImageData} imageData - 要转换的图像数据
    * @returns {HTMLCanvasElement} 包含图像的Canvas元素
    */
-  static imageDataToCanvas(imageData: ImageData): HTMLCanvasElement {
-    const canvas = document.createElement("canvas")
-    canvas.width = imageData.width
-    canvas.height = imageData.height
-    const ctx = canvas.getContext("2d")
+  static imageDataToCanvas(imageData: ImageData, usePool: boolean = true): HTMLCanvasElement {
+    let canvas: HTMLCanvasElement;
+    let context: CanvasRenderingContext2D;
+
+    if (usePool) {
+      ({ canvas, context } = CanvasPool.getInstance().acquire(imageData.width, imageData.height));
+    } else {
+      canvas = document.createElement("canvas");
+      canvas.width = imageData.width;
+      canvas.height = imageData.height;
+      context = canvas.getContext("2d")!;
+    }
 
-    if (ctx) {
-      ctx.putImageData(imageData, 0, 0)
+    context.putImageData(imageData, 0, 0);
+
+    if (usePool) {
+      // 立即释放回池中，用户保留 canvas 引用即可
+      CanvasPool.getInstance().release(canvas);
     }
 
-    return canvas
+    return canvas;
   }
 
   /**
@@ -106,22 +120,26 @@ export class ImageProcessor {
   }
 
   /**
-   * 将图像转换为灰度图
+   * 将图像转换为灰度图（返回新 ImageData，不修改原图）
    *
    * @param imageData 原始图像数据
-   * @returns 灰度图像数据
+   * @returns 灰度图像数据（新对象）
    */
   static toGrayscale(imageData: ImageData): ImageData {
-    const data = imageData.data
-    const length = data.length
+    const srcData = imageData.data
+    const length = srcData.length
+    // 创建新数组，避免修改原图
+    const destData = new Uint8ClampedArray(srcData)
 
     for (let i = 0; i < length; i += 4) {
       // 使用加权平均法将 RGB 转换为灰度值
-      const gray = data[i] * 0.3 + data[i + 1] * 0.59 + data[i + 2] * 0.11
-      data[i] = data[i + 1] = data[i + 2] = gray
+      const gray = srcData[i] * 0.3 + srcData[i + 1] * 0.59 + srcData[i + 2] * 0.11
+      destData[i] = destData[i + 1] = destData[i + 2] = gray
+      // Alpha 通道保持不变
+      destData[i + 3] = srcData[i + 3]
     }
 
-    return imageData
+    return new ImageData(destData, imageData.width, imageData.height)
   }
 
   /**
@@ -174,17 +192,20 @@ export class ImageProcessor {
       }
     }
 
-    // 处理边缘像素
-    for (let y = 0; y < height; y++) {
-      for (let x = 0; x < width; x++) {
-        if (y === 0 || y === height - 1 || x === 0 || x === width - 1) {
-          const pos = (y * width + x) * 4
-          outputData[pos] = data[pos]
-          outputData[pos + 1] = data[pos + 1]
-          outputData[pos + 2] = data[pos + 2]
-          outputData[pos + 3] = data[pos + 3]
-        }
-      }
+    // 处理边缘像素（仅遍历四条边，而非全图 O(width×height) → O(width+height)）
+    // 上边 + 下边
+    for (let x = 0; x < width; x++) {
+      const topPos = x * 4
+      const bottomPos = ((height - 1) * width + x) * 4
+      outputData[topPos] = data[topPos]; outputData[topPos + 1] = data[topPos + 1]; outputData[topPos + 2] = data[topPos + 2]; outputData[topPos + 3] = data[topPos + 3]
+      outputData[bottomPos] = data[bottomPos]; outputData[bottomPos + 1] = data[bottomPos + 1]; outputData[bottomPos + 2] = data[bottomPos + 2]; outputData[bottomPos + 3] = data[bottomPos + 3]
+    }
+    // 左边 + 右边（排除四角，它们已在上下一行处理）
+    for (let y = 1; y < height - 1; y++) {
+      const leftPos = y * width * 4
+      const rightPos = (y * width + width - 1) * 4
+      outputData[leftPos] = data[leftPos]; outputData[leftPos + 1] = data[leftPos + 1]; outputData[leftPos + 2] = data[leftPos + 2]; outputData[leftPos + 3] = data[leftPos + 3]
+      outputData[rightPos] = data[rightPos]; outputData[rightPos + 1] = data[rightPos + 1]; outputData[rightPos + 2] = data[rightPos + 2]; outputData[rightPos + 3] = data[rightPos + 3]
     }
 
     // 创建新的ImageData对象
@@ -192,54 +213,55 @@ export class ImageProcessor {
   }
 
   /**
-   * 对图像应用阈值操作，增强对比度
+   * 对图像应用阈值操作，增强对比度（二值化）
    *
    * @param imageData 原始图像数据
    * @param threshold 阈值 (0-255)
-   * @returns 处理后的图像数据
+   * @returns 处理后的图像数据（新对象，不修改原图）
    */
   static threshold(imageData: ImageData, threshold: number = 128): ImageData {
-    // 先转换为灰度图
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    )
-
-    const data = grayscaleImage.data
-    const length = data.length
+    // 先转换为灰度图（返回新 ImageData，不修改原图）
+    const grayscaleImage = this.toGrayscale(imageData)
+    const srcData = grayscaleImage.data
+    const length = srcData.length
+    // 创建新数组存储二值化结果
+    const destData = new Uint8ClampedArray(length)
 
     for (let i = 0; i < length; i += 4) {
       // 二值化处理
-      const value = data[i] < threshold ? 0 : 255
-      data[i] = data[i + 1] = data[i + 2] = value
+      const value = srcData[i] < threshold ? 0 : 255
+      destData[i] = destData[i + 1] = destData[i + 2] = value
+      destData[i + 3] = srcData[i + 3] // 保持透明度
     }
 
-    return grayscaleImage
+    return new ImageData(destData, grayscaleImage.width, grayscaleImage.height)
   }
 
   /**
-   * 将图像转换为黑白图像（二值化）
+   * 将图像转换为黑白图像（二值化，使用OTSU自动阈值）
    *
    * @param imageData 原始图像数据
-   * @returns 二值化后的图像数据
+   * @returns 二值化后的图像数据（新对象，不修改原图）
    */
   static toBinaryImage(imageData: ImageData): ImageData {
-    // 先转换为灰度图
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    )
+    // 先转换为灰度图（返回新 ImageData，不修改原图）
+    const grayscaleImage = this.toGrayscale(imageData)
 
     // 使用OTSU算法自动确定阈值
     const threshold = this.getOtsuThreshold(grayscaleImage)
 
-    return this.threshold(grayscaleImage, threshold)
+    // 直接对灰度图进行二值化，避免再次调用 toGrayscale
+    const srcData = grayscaleImage.data
+    const length = srcData.length
+    const destData = new Uint8ClampedArray(length)
+
+    for (let i = 0; i < length; i += 4) {
+      const value = srcData[i] < threshold ? 0 : 255
+      destData[i] = destData[i + 1] = destData[i + 2] = value
+      destData[i + 3] = srcData[i + 3] // 保持透明度
+    }
+
+    return new ImageData(destData, grayscaleImage.width, grayscaleImage.height)
   }
 
   /**
@@ -250,9 +272,10 @@ export class ImageProcessor {
    */
   private static getOtsuThreshold(imageData: ImageData): number {
     const data = imageData.data
-    const histogram = new Array(256).fill(0)
+    // 使用 Uint8Array 替代 Array<number>，避免 boxing 开销，提升直方图统计性能
+    const histogram = new Uint32Array(256)
 
-    // 统计灰度直方图
+    // 统计灰度直方图（每4字节取R通道，即灰度值）
     for (let i = 0; i < data.length; i += 4) {
       histogram[data[i]]++
     }
@@ -390,48 +413,38 @@ export class ImageProcessor {
 
         img.onload = () => {
           try {
-            // 创建canvas元素
-            const canvas = document.createElement("canvas")
-            const ctx = canvas.getContext("2d")
-
-            if (!ctx) {
-              reject(new Error("无法创建2D上下文"))
-              return
-            }
-
-            canvas.width = img.width
-            canvas.height = img.height
+            // 使用 Canvas 池获取 canvas
+            const { canvas, context } = CanvasPool.getInstance().acquire(img.width, img.height);
 
             // 绘制图片到canvas
-            ctx.drawImage(img, 0, 0)
+            context.drawImage(img, 0, 0);
 
             // 获取图像数据
-            const imageData = ctx.getImageData(
-              0,
-              0,
-              canvas.width,
-              canvas.height
-            )
+            const imageData = context.getImageData(0, 0, canvas.width, canvas.height);
+
+            // 释放回池
+            CanvasPool.getInstance().release(canvas);
 
             // 释放资源
-            URL.revokeObjectURL(url)
+            URL.revokeObjectURL(url);
 
-            resolve(imageData)
+            resolve(imageData);
           } catch (e) {
-            reject(e)
+            URL.revokeObjectURL(url);
+            reject(e);
           }
-        }
+        };
 
         img.onerror = () => {
-          URL.revokeObjectURL(url)
-          reject(new Error("图片加载失败"))
-        }
+          URL.revokeObjectURL(url);
+          reject(new Error("图片加载失败"));
+        };
 
-        img.src = url
+        img.src = url;
       } catch (error) {
-        reject(error)
+        reject(error);
       }
-    })
+    });
   }
 
   /**
@@ -451,25 +464,21 @@ export class ImageProcessor {
   ): Promise<File> {
     return new Promise((resolve, reject) => {
       try {
-        const canvas = document.createElement("canvas")
-        canvas.width = imageData.width
-        canvas.height = imageData.height
-
-        const ctx = canvas.getContext("2d")
-        if (!ctx) {
-          reject(new Error("无法创建2D上下文"))
-          return
-        }
+        // 使用 Canvas 池
+        const { canvas, context } = CanvasPool.getInstance().acquire(imageData.width, imageData.height);
 
-        ctx.putImageData(imageData, 0, 0)
+        context.putImageData(imageData, 0, 0);
 
         canvas.toBlob(
           (blob) => {
+            // 释放回池
+            CanvasPool.getInstance().release(canvas);
+
             if (!blob) {
-              reject(new Error("无法创建图片Blob"))
-              return
+              reject(new Error("无法创建图片Blob"));
+              return;
             }
-            const file = new File([blob], fileName, { type: fileType })
+            const file = new File([blob], fileName, { type: fileType });
             resolve(file)
           },
           fileType,
@@ -565,365 +574,20 @@ export class ImageProcessor {
   }
   
   /**
-   * 边缘检测算法，用于识别图像中的边缘
-   * 基于Sobel算子实现
-   * 
-   * @param imageData 原始图像数据，应已转为灰度图
-   * @param threshold 边缘阈值，默认为30
-   * @returns 检测到边缘的图像数据
+   * @deprecated 请使用 EdgeDetector.detectEdges()
    */
   static detectEdges(imageData: ImageData, threshold: number = 30): ImageData {
-    // 确保输入图像是灰度图
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    );
-    
-    const width = grayscaleImage.width;
-    const height = grayscaleImage.height;
-    const inputData = grayscaleImage.data;
-    const outputData = new Uint8ClampedArray(inputData.length);
-    
-    // Sobel算子 - 水平和垂直方向
-    const sobelX = [-1, 0, 1, -2, 0, 2, -1, 0, 1];
-    const sobelY = [-1, -2, -1, 0, 0, 0, 1, 2, 1];
-    
-    // 对每个像素应用Sobel算子
-    for (let y = 1; y < height - 1; y++) {
-      for (let x = 1; x < width - 1; x++) {
-        let gx = 0;
-        let gy = 0;
-        
-        // 应用卷积
-        for (let ky = -1; ky <= 1; ky++) {
-          for (let kx = -1; kx <= 1; kx++) {
-            const pixelPos = ((y + ky) * width + (x + kx)) * 4;
-            const pixelVal = inputData[pixelPos]; // 灰度值
-            
-            const kernelIdx = (ky + 1) * 3 + (kx + 1);
-            gx += pixelVal * sobelX[kernelIdx];
-            gy += pixelVal * sobelY[kernelIdx];
-          }
-        }
-        
-        // 计算梯度强度
-        let magnitude = Math.sqrt(gx * gx + gy * gy);
-        
-        // 应用阈值
-        magnitude = magnitude > threshold ? 255 : 0;
-        
-        // 设置输出像素
-        const pos = (y * width + x) * 4;
-        outputData[pos] = outputData[pos + 1] = outputData[pos + 2] = magnitude;
-        outputData[pos + 3] = 255; // 透明度保持完全不透明
-      }
-    }
-    
-    // 处理边缘像素
-    for (let i = 0; i < width * 4; i++) {
-      // 顶部和底部行
-      outputData[i] = 0;
-      outputData[(height - 1) * width * 4 + i] = 0;
-    }
-    
-    for (let i = 0; i < height; i++) {
-      // 左右两侧列
-      const leftPos = i * width * 4;
-      const rightPos = (i * width + width - 1) * 4;
-      
-      for (let j = 0; j < 4; j++) {
-        outputData[leftPos + j] = 0;
-        outputData[rightPos + j] = 0;
-      }
-    }
-    
-    return new ImageData(outputData, width, height);
+    return EdgeDetector.detectEdges(imageData, threshold);
   }
   
   /**
-   * 卡尼-德里奇边缘检测
-   * 相比Sobel更精确的边缘检测算法
-   * 
-   * @param imageData 灰度图像数据
-   * @param lowThreshold 低阈值
-   * @param highThreshold 高阈值
-   * @returns 边缘检测结果
+   * @deprecated 请使用 EdgeDetector.cannyEdgeDetection()
    */
   static cannyEdgeDetection(
     imageData: ImageData, 
     lowThreshold: number = 20, 
     highThreshold: number = 50
   ): ImageData {
-    const grayscaleImage = this.toGrayscale(
-      new ImageData(
-        new Uint8ClampedArray(imageData.data),
-        imageData.width,
-        imageData.height
-      )
-    );
-    
-    // 1. 高斯模糊
-    const blurredImage = this.gaussianBlur(grayscaleImage, 1.5);
-    
-    // 2. 使用Sobel算子计算梯度
-    const { gradientMagnitude, gradientDirection } = this.computeGradients(blurredImage);
-    
-    // 3. 非极大值抛弃
-    const nonMaxSuppressed = this.nonMaxSuppression(gradientMagnitude, gradientDirection, blurredImage.width, blurredImage.height);
-    
-    // 4. 双阈值处理
-    const thresholdResult = this.hysteresisThresholding(
-      nonMaxSuppressed, 
-      blurredImage.width, 
-      blurredImage.height, 
-      lowThreshold, 
-      highThreshold
-    );
-    
-    // 创建输出图像
-    const outputData = new Uint8ClampedArray(imageData.data.length);
-    
-    // 将结果转换为ImageData
-    for (let i = 0; i < thresholdResult.length; i++) {
-      const pos = i * 4;
-      const value = thresholdResult[i] ? 255 : 0;
-      outputData[pos] = outputData[pos + 1] = outputData[pos + 2] = value;
-      outputData[pos + 3] = 255;
-    }
-    
-    return new ImageData(outputData, blurredImage.width, blurredImage.height);
-  }
-  
-  /**
-   * 高斯模糊
-   */
-  private static gaussianBlur(imageData: ImageData, sigma: number = 1.5): ImageData {
-    const width = imageData.width;
-    const height = imageData.height;
-    const inputData = imageData.data;
-    const outputData = new Uint8ClampedArray(inputData.length);
-    
-    // 生成高斯核
-    const kernelSize = Math.max(3, Math.floor(sigma * 3) * 2 + 1);
-    const halfKernel = Math.floor(kernelSize / 2);
-    const kernel = this.generateGaussianKernel(kernelSize, sigma);
-    
-    // 应用高斯核
-    for (let y = 0; y < height; y++) {
-      for (let x = 0; x < width; x++) {
-        let sum = 0;
-        let weightSum = 0;
-        
-        for (let ky = -halfKernel; ky <= halfKernel; ky++) {
-          for (let kx = -halfKernel; kx <= halfKernel; kx++) {
-            const pixelY = Math.min(Math.max(y + ky, 0), height - 1);
-            const pixelX = Math.min(Math.max(x + kx, 0), width - 1);
-            const pixelPos = (pixelY * width + pixelX) * 4;
-            
-            const kernelY = ky + halfKernel;
-            const kernelX = kx + halfKernel;
-            const weight = kernel[kernelY * kernelSize + kernelX];
-            
-            sum += inputData[pixelPos] * weight;
-            weightSum += weight;
-          }
-        }
-        
-        const pos = (y * width + x) * 4;
-        const value = Math.round(sum / weightSum);
-        outputData[pos] = outputData[pos + 1] = outputData[pos + 2] = value;
-        outputData[pos + 3] = 255;
-      }
-    }
-    
-    return new ImageData(outputData, width, height);
-  }
-  
-  /**
-   * 生成高斯核
-   */
-  private static generateGaussianKernel(size: number, sigma: number): number[] {
-    const kernel = new Array(size * size);
-    const center = Math.floor(size / 2);
-    let sum = 0;
-    
-    for (let y = 0; y < size; y++) {
-      for (let x = 0; x < size; x++) {
-        const distance = Math.sqrt((x - center) ** 2 + (y - center) ** 2);
-        const value = Math.exp(-(distance ** 2) / (2 * sigma ** 2));
-        
-        kernel[y * size + x] = value;
-        sum += value;
-      }
-    }
-    
-    // 归一化
-    for (let i = 0; i < kernel.length; i++) {
-      kernel[i] /= sum;
-    }
-    
-    return kernel;
-  }
-  
-  /**
-   * 计算梯度强度和方向
-   */
-  private static computeGradients(imageData: ImageData): { 
-    gradientMagnitude: number[], 
-    gradientDirection: number[] 
-  } {
-    const width = imageData.width;
-    const height = imageData.height;
-    const inputData = imageData.data;
-    
-    const gradientMagnitude = new Array(width * height);
-    const gradientDirection = new Array(width * height);
-    
-    // Sobel算子
-    const sobelX = [-1, 0, 1, -2, 0, 2, -1, 0, 1];
-    const sobelY = [-1, -2, -1, 0, 0, 0, 1, 2, 1];
-    
-    for (let y = 1; y < height - 1; y++) {
-      for (let x = 1; x < width - 1; x++) {
-        let gx = 0;
-        let gy = 0;
-        
-        for (let ky = -1; ky <= 1; ky++) {
-          for (let kx = -1; kx <= 1; kx++) {
-            const pixelPos = ((y + ky) * width + (x + kx)) * 4;
-            const pixelVal = inputData[pixelPos];
-            
-            const kernelIdx = (ky + 1) * 3 + (kx + 1);
-            gx += pixelVal * sobelX[kernelIdx];
-            gy += pixelVal * sobelY[kernelIdx];
-          }
-        }
-        
-        const idx = y * width + x;
-        gradientMagnitude[idx] = Math.sqrt(gx * gx + gy * gy);
-        gradientDirection[idx] = Math.atan2(gy, gx);
-      }
-    }
-    
-    // 处理边界
-    for (let y = 0; y < height; y++) {
-      for (let x = 0; x < width; x++) {
-        if (y === 0 || y === height - 1 || x === 0 || x === width - 1) {
-          const idx = y * width + x;
-          gradientMagnitude[idx] = 0;
-          gradientDirection[idx] = 0;
-        }
-      }
-    }
-    
-    return { gradientMagnitude, gradientDirection };
-  }
-  
-  /**
-   * 非极大值抛弃
-   */
-  private static nonMaxSuppression(
-    gradientMagnitude: number[], 
-    gradientDirection: number[], 
-    width: number, 
-    height: number
-  ): number[] {
-    const result = new Array(width * height).fill(0);
-    
-    for (let y = 1; y < height - 1; y++) {
-      for (let x = 1; x < width - 1; x++) {
-        const idx = y * width + x;
-        const magnitude = gradientMagnitude[idx];
-        const direction = gradientDirection[idx];
-        
-        // 将方向转化为角度
-        const degrees = (direction * 180 / Math.PI + 180) % 180;
-        
-        // 获取相邻像素索引
-        let neighbor1Idx, neighbor2Idx;
-        
-        // 将方向量化为四个方向: 0°, 45°, 90°, 135°
-        if ((degrees >= 0 && degrees < 22.5) || (degrees >= 157.5 && degrees <= 180)) {
-          // 水平方向
-          neighbor1Idx = idx - 1;
-          neighbor2Idx = idx + 1;
-        } else if (degrees >= 22.5 && degrees < 67.5) {
-          // 45度方向
-          neighbor1Idx = (y - 1) * width + (x + 1);
-          neighbor2Idx = (y + 1) * width + (x - 1);
-        } else if (degrees >= 67.5 && degrees < 112.5) {
-          // 垂直方向
-          neighbor1Idx = (y - 1) * width + x;
-          neighbor2Idx = (y + 1) * width + x;
-        } else {
-          // 135度方向
-          neighbor1Idx = (y - 1) * width + (x - 1);
-          neighbor2Idx = (y + 1) * width + (x + 1);
-        }
-        
-        // 检查当前像素是否是最大值
-        if (magnitude >= gradientMagnitude[neighbor1Idx] && 
-            magnitude >= gradientMagnitude[neighbor2Idx]) {
-          result[idx] = magnitude;
-        }
-      }
-    }
-    
-    return result;
-  }
-  
-  /**
-   * 双阈值处理
-   */
-  private static hysteresisThresholding(
-    nonMaxSuppressed: number[], 
-    width: number, 
-    height: number, 
-    lowThreshold: number, 
-    highThreshold: number
-  ): boolean[] {
-    const result = new Array(width * height).fill(false);
-    const visited = new Array(width * height).fill(false);
-    const stack = [];
-    
-    // 标记强边缘点
-    for (let i = 0; i < nonMaxSuppressed.length; i++) {
-      if (nonMaxSuppressed[i] >= highThreshold) {
-        result[i] = true;
-        stack.push(i);
-        visited[i] = true;
-      }
-    }
-    
-    // 使用深度优先搜索连接弱边缘
-    const dx = [-1, 0, 1, -1, 1, -1, 0, 1];
-    const dy = [-1, -1, -1, 0, 0, 1, 1, 1];
-    
-    while (stack.length > 0) {
-      const currentIdx: number = stack.pop()!;
-      const currentX: number = currentIdx % width;
-      const currentY: number = Math.floor(currentIdx / width);
-      
-      // 检查88个相邻方向
-      for (let i = 0; i < 8; i++) {
-        const newX: number = currentX + dx[i];
-        const newY: number = currentY + dy[i];
-        
-        if (newX >= 0 && newX < width && newY >= 0 && newY < height) {
-          const newIdx: number = newY * width + newX;
-          
-          if (!visited[newIdx] && nonMaxSuppressed[newIdx] >= lowThreshold) {
-            result[newIdx] = true;
-            stack.push(newIdx);
-            visited[newIdx] = true;
-          }
-        }
-      }
-    }
-    
-    return result;
+    return EdgeDetector.cannyEdgeDetection(imageData, lowThreshold, highThreshold);
   }
 }

package/src/utils/index.ts

@@ -6,6 +6,7 @@
 
 export * from './error-handler';
 export * from './retry';
+export * from './canvas-pool';
 
 /**
  * 创建延迟Promise