ppu-ocv 2.0.0 → 3.0.0

package/README.md

@@ -32,6 +32,8 @@ OpenCV is powerful but can be cumbersome to use directly. This library provides:
 3. **Development Speed**: Add image processing to your app in minutes, not hours
 4. **Extensibility**: Custom operations for your specific needs without library modifications
 5. **TypeScript Integration**: Full IntelliSense support with parameter validation
+6. **Web Support**: Supports running directly in the browser
+7. **Loosely Coupled**: Canvas utilities are fully decoupled from OpenCV. Usable in Browser Extensions, Service Workers, and other constrained environments where OpenCV cannot be initialised
 
 ## Installation
 
@@ -45,40 +47,43 @@ bun add ppu-ocv
 
 ## Usage (Node.js / Bun)
 
-Note that Operation order is matter, you should atleast know some basic in using OpenCV. See the operations table below this.
+Note that operation order matters — you should have at least basic familiarity with OpenCV. See the operations table below.
 
 ```ts
-import { ImageProcessor } from "ppu-ocv";
+import { CanvasProcessor, ImageProcessor } from "ppu-ocv";
 
 const file = Bun.file("./assets/receipt.jpg");
 const image = await file.arrayBuffer();
 
-const canvas = await ImageProcessor.prepareCanvas(image);
-await ImageProcessor.initRuntime();
+await ImageProcessor.initRuntime(); // init opencv
+const canvas = await CanvasProcessor.prepareCanvas(image);
 
 const processor = new ImageProcessor(canvas);
-processor.grayscale().blur({ size: [5, 5] }).threshold();
+processor
+  .grayscale()
+  .blur({ size: [5, 5] })
+  .threshold();
 
 const resultCanvas = processor.toCanvas();
 processor.destroy();
 ```
 
-Or you can do directly via execute api:
+Or use the `execute` API directly:
 
 ```ts
-import { CanvasToolkit, ImageProcessor, cv } from "ppu-ocv";
+import { CanvasProcessor, CanvasToolkit, ImageProcessor, cv } from "ppu-ocv";
 
 const file = Bun.file("./assets/receipt.jpg");
 const image = await file.arrayBuffer();
 
 const canvasToolkit = CanvasToolkit.getInstance();
-const canvas = await ImageProcessor.prepareCanvas(image);
 await ImageProcessor.initRuntime();
+const canvas = await CanvasProcessor.prepareCanvas(image);
 
 const processor = new ImageProcessor(canvas);
 const grayscaleImg = processor.execute("grayscale").toCanvas();
 
-// the pipeline operation continued from grayscaled image
+// The pipeline continues from the grayscaled image
 const thresholdImg = processor
   .execute("blur")
   .execute("threshold", {
@@ -95,25 +100,57 @@ await canvasToolkit.saveImage({
 
 For more advanced usage, see: [Example usage of ppu-ocv](./examples)
 
+## Canvas-only usage (no OpenCV)
+
+Starting from v3.0.0, canvas utilities are fully decoupled from OpenCV. If you only need canvas I/O (e.g. loading/saving images, cropping, drawing) without any image processing, import from `ppu-ocv/canvas` (Node) or `ppu-ocv/canvas-web` (browser). OpenCV is **never imported or initialised** by these entry points, making them safe for use in Browser Extensions, Service Workers, and edge runtimes.
+
+```ts
+// Node.js — zero OpenCV dependency
+import { CanvasProcessor, CanvasToolkit } from "ppu-ocv/canvas";
+
+const file = Bun.file("./assets/image.jpg");
+const canvas = await CanvasProcessor.prepareCanvas(await file.arrayBuffer());
+
+const toolkit = CanvasToolkit.getInstance();
+const cropped = toolkit.crop({
+  canvas,
+  bbox: { x0: 0, y0: 0, x1: 100, y1: 100 },
+});
+
+const buffer = await CanvasProcessor.prepareBuffer(cropped);
+```
+
+```ts
+// Browser Extension background script — zero OpenCV dependency
+import { CanvasProcessor, CanvasToolkit } from "ppu-ocv/canvas-web";
+
+const response = await fetch("/image.jpg");
+const canvas = await CanvasProcessor.prepareCanvas(
+  await response.arrayBuffer(),
+);
+```
+
 ## Web / Browser Support
 
-Starting from v2.0.0, ppu-ocv supports running in the browser. Import from `ppu-ocv/web` instead of `ppu-ocv` to use the browser-native canvas APIs (`HTMLCanvasElement` / `OffscreenCanvas`) instead of `@napi-rs/canvas`.
+Import from `ppu-ocv/web` to use the browser-native canvas APIs (`HTMLCanvasElement` / `OffscreenCanvas`) instead of `@napi-rs/canvas`.
 
 ### With a bundler (Vite, webpack, etc.)
 
 ```ts
-import { ImageProcessor, cv } from "ppu-ocv/web";
+import { CanvasProcessor, ImageProcessor, cv } from "ppu-ocv/web";
 
 await ImageProcessor.initRuntime();
 
-// From a file input or fetch
 const response = await fetch("/my-image.jpg");
 const buffer = await response.arrayBuffer();
 
-const canvas = await ImageProcessor.prepareCanvas(buffer);
+const canvas = await CanvasProcessor.prepareCanvas(buffer);
 const processor = new ImageProcessor(canvas);
 
-processor.grayscale().blur({ size: [5, 5] }).threshold();
+processor
+  .grayscale()
+  .blur({ size: [5, 5] })
+  .threshold();
 
 const result = processor.toCanvas(); // returns HTMLCanvasElement
 document.body.appendChild(result);
@@ -127,11 +164,22 @@ processor.destroy();
 
 ```html
 <script type="module">
-  import { ImageProcessor } from "https://cdn.jsdelivr.net/npm/ppu-ocv@2/index.web.js";
+  import {
+    CanvasProcessor,
+    ImageProcessor,
+  } from "https://cdn.jsdelivr.net/npm/ppu-ocv@3/index.web.js";
   await ImageProcessor.initRuntime();
 
+  const response = await fetch("/my-image.jpg");
+  const canvas = await CanvasProcessor.prepareCanvas(
+    await response.arrayBuffer(),
+  );
+
   const processor = new ImageProcessor(canvas);
-  processor.grayscale().blur({ size: [5, 5] }).threshold();
+  processor
+    .grayscale()
+    .blur({ size: [5, 5] })
+    .threshold();
 
   const result = processor.toCanvas();
   processor.destroy();
@@ -142,28 +190,32 @@ processor.destroy();
 
 See the [interactive demo](./index.html) for a full working example.
 
-### Node vs Web differences
+### Entry point reference
 
-| Feature | `ppu-ocv` (Node) | `ppu-ocv/web` (Browser) |
-| --- | --- | --- |
-| Canvas backend | `@napi-rs/canvas` | `HTMLCanvasElement` / `OffscreenCanvas` |
-| `CanvasToolkit` | Full (includes `saveImage`, `clearOutput`) | Base only (`crop`, `isDirty`, `drawLine`, `drawContour`) |
-| File I/O | ✅ `saveImage`, `clearOutput` | ❌ Not available (use download links or `toDataURL`) |
-| `ImageProcessor` | ✅ | ✅ Same API |
-| `Contours` | ✅ | ✅ Same API |
-| Image analysis | ✅ | ✅ Same API |
+| Import path          | OpenCV | Canvas backend                        | `CanvasToolkit`      | Use case                                   |
+| -------------------- | ------ | ------------------------------------- | -------------------- | ------------------------------------------ |
+| `ppu-ocv`            | ✅     | `@napi-rs/canvas`                     | Full (with file I/O) | Full pipeline, Node.js / Bun               |
+| `ppu-ocv/web`        | ✅     | `HTMLCanvasElement`/`OffscreenCanvas` | Base only            | Full pipeline, browser                     |
+| `ppu-ocv/canvas`     | ❌     | `@napi-rs/canvas`                     | Full (with file I/O) | Canvas-only, Node (extensions, edge, etc.) |
+| `ppu-ocv/canvas-web` | ❌     | `HTMLCanvasElement`/`OffscreenCanvas` | Base only            | Canvas-only, browser extensions / SW       |
 
 ### Platform abstraction
 
-Under the hood, ppu-ocv uses a platform abstraction layer. The `ppu-ocv` entry point auto-registers the Node platform, and `ppu-ocv/web` auto-registers the browser platform. You can also set a custom platform:
+Under the hood, ppu-ocv uses a platform abstraction layer. Each entry point auto-registers its platform. You can also register a custom platform:
 
 ```ts
 import { setPlatform, type CanvasPlatform } from "ppu-ocv/web";
 
 const myPlatform: CanvasPlatform = {
-  createCanvas(width, height) { /* ... */ },
-  loadImage(source) { /* ... */ },
-  isCanvas(value) { /* ... */ },
+  createCanvas(width, height) {
+    /* ... */
+  },
+  loadImage(source) {
+    /* ... */
+  },
+  isCanvas(value) {
+    /* ... */
+  },
 };
 
 setPlatform(myPlatform);
@@ -191,23 +243,34 @@ To avoid bloat, we only ship essential operations for chaining. Currently shippe
 
 ## Extending operations
 
-You can easily add your own by creating a prototype method or extend the class of `ImageProcessor`.
+You can easily add your own by creating a prototype method or extending the `ImageProcessor` class.
 
 See: [How to extend ppu-ocv operations](./docs/how-to-extend-ppu-ocv-operations.md)
 
 ## Class documentation
 
+#### `CanvasProcessor`
+
+Canvas I/O utilities with **no OpenCV dependency**. Available from all entry points including `ppu-ocv/canvas` and `ppu-ocv/canvas-web`.
+
+| Method                 | Args        | Description                                           |
+| ---------------------- | ----------- | ----------------------------------------------------- |
+| static `prepareCanvas` | ArrayBuffer | Load image bytes into a `CanvasLike`                  |
+| static `prepareBuffer` | CanvasLike  | Export a `CanvasLike` to an `ArrayBuffer` (PNG bytes) |
+
 #### `ImageProcessor`
 
-| Method                 | Args             | Description                                                                 |
-| ---------------------- | ---------------- | --------------------------------------------------------------------------- |
-| constructor            | cv.Mat or Canvas | Instantiate processor with initial image                                    |
-| static `prepareCanvas` | ArrayBuffer      | Utility to load image from file buffer to canvas                            |
-| static `initRuntime`   |                  | Important open-cv runtime initialization, required to call once per runtime |
-| operations             | depends          | Chainable operations like `blur`, `grayscale`, `resize` and so on           |
-| `execute`              | name, options    | Chainable operations directly via `execute` api                             |
-| outputs                |                  | Non-chainable & non-interupting method for output like `toMat`, `toCanvas`  |
-| `destroy`              |                  | Non-chainable clean-up memory to destroy the object and the state           |
+Requires OpenCV. Available from `ppu-ocv` and `ppu-ocv/web`.
+
+| Method               | Args             | Description                                                        |
+| -------------------- | ---------------- | ------------------------------------------------------------------ |
+| constructor          | cv.Mat or Canvas | Instantiate processor with initial image                           |
+| static `initRuntime` |                  | OpenCV runtime initialization — required once per runtime          |
+| operations           | depends          | Chainable operations like `blur`, `grayscale`, `resize`, and so on |
+| `execute`            | name, options    | Chainable operations via the `execute` API                         |
+| `toMat`              |                  | Return the current image as a `cv.Mat`                             |
+| `toCanvas`           |                  | Return the current image as a `CanvasLike`                         |
+| `destroy`            |                  | Clean up `cv.Mat` memory                                           |
 
 #### `CanvasToolkit`
 
@@ -215,31 +278,41 @@ See: [How to extend ppu-ocv operations](./docs/how-to-extend-ppu-ocv-operations.
 | ------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
 | `crop`        | BoundingBox, Canvas    | Crop a part of source canvas and return a new canvas of the cropped part                  |
 | `isDirty`     | Canvas, threshold      | Check whether a binary canvas is dirty (full of major color either black or white) or not |
-| `saveImage`   | Canvas, filename, path | Save a canvas to an image file                                                            |
-| `clearOutput` | path                   | Clear the output folder                                                                   |
+| `saveImage`   | Canvas, filename, path | Save a canvas to an image file _(Node only)_                                              |
+| `clearOutput` | path                   | Clear the output folder _(Node only)_                                                     |
 | `drawLine`    | ctx, coordinate, style | Draw a non-filled rectangle outline on the canvas                                         |
-| `drawContour` | ctx, contour, style    | Draw a contour on the canvas                                                              |
+| `drawContour` | ctx, contour, style    | Draw a contour on the canvas — accepts any `ContourLike` (`{ data32S }`)                  |
+
+#### `DeskewService`
+
+Detects and corrects text skew in document images using a multi-method consensus approach (minAreaRect, baseline analysis, Hough transform). Requires OpenCV. Available from `ppu-ocv` and `ppu-ocv/web`.
+
+| Method               | Args          | Description                          |
+| -------------------- | ------------- | ------------------------------------ |
+| constructor          | DeskewOptions | `verbose`, `minimumAreaThreshold`    |
+| `calculateSkewAngle` | CanvasLike    | Detect skew angle in degrees         |
+| `deskewImage`        | CanvasLike    | Return a deskewed copy of the canvas |
 
 #### `Contours`
 
-| Method                  | Args            | Description                                                                               |
-| ----------------------- | --------------- | ----------------------------------------------------------------------------------------- |
-| constructor             | cv.Mat, options | Instantiate Contours and automatically find & store contour list from args                |
-| `getAll`                |                 | Crop a part of source canvas and return a new canvas of the cropped part                  |
-| `getFromIndex`          | index           | Get contour at a specific index                                                           |
-| `getRect`               |                 | Get the rectangle that bounds the contour                                                 |
-| `iterate`               | callback        | Iterate over all contours and call the callback function for each contour                 |
-| `getLargestContourArea` |                 | Get the largest contour area                                                              |
-| `getCornerPoints`       | Canvas, contour | Get four corner points for a given contour. Useful for perspective transformation (warp). |
-| `destroy`               |                 | Destroy & clean-up the memory from the contours                                           |
+| Method                           | Args            | Description                                                      |
+| -------------------------------- | --------------- | ---------------------------------------------------------------- |
+| constructor                      | cv.Mat, options | Instantiate Contours and automatically find & store contour list |
+| `getAll`                         |                 | Return the full `cv.MatVector` of contours                       |
+| `getFromIndex`                   | index           | Get contour at a specific index                                  |
+| `getRect`                        | contour         | Get the bounding rectangle of a contour                          |
+| `iterate`                        | callback        | Iterate over all contours                                        |
+| `getLargestContourArea`          |                 | Return the contour with the largest area                         |
+| `getCornerPoints`                | options         | Get four corner points for perspective transformation (warp)     |
+| `getApproximateRectangleContour` | options         | Simplify a contour to an approximate rectangle                   |
+| `destroy`                        |                 | Destroy and clean up contour memory                              |
 
 #### `ImageAnalysis`
 
-Just a collection of utility functions for analyzing image properties.
-
-- `calculateMeanNormalizedLabLightness`: Calculates the mean normalized lightness of an image using the L channel of the Lab color space. Lightness is normalized based on the image's own maximum lightness value before averaging.
+A collection of utility functions for analyzing image properties (requires OpenCV).
 
-- `calculateMeanGrayscaleValue`: Calculates the mean pixel value of the image after converting it to grayscale.
+- `calculateMeanNormalizedLabLightness`: Calculates the mean normalized lightness of an image using the L channel of the Lab color space.
+- `calculateMeanGrayscaleValue`: Calculates the mean pixel value after converting to grayscale.
 
 ## Contributing
 
@@ -262,12 +335,10 @@ Ensure that all tests pass before submitting your pull request.
 
 ## Scripts
 
-Recommended development environment is in linux-based environment.
+Recommended development environment is in a Linux-based environment.
 
 Library template: https://github.com/aquapi/lib-template
 
-All script sources and usage.
-
 ### [Build](./scripts/build.ts)
 
 Emit `.js` and `.d.ts` files to [`lib`](./lib).
@@ -276,6 +347,20 @@ Emit `.js` and `.d.ts` files to [`lib`](./lib).
 
 Move [`package.json`](./package.json), [`README.md`](./README.md) to [`lib`](./lib) and publish the package.
 
+## Migrating from v2
+
+See [MIGRATION.md](./MIGRATION.md) for a full guide. The short version:
+
+```diff
+- import { ImageProcessor } from "ppu-ocv";
+- const canvas = await ImageProcessor.prepareCanvas(buffer);
+- const buf    = await ImageProcessor.prepareBuffer(canvas);
+
++ import { CanvasProcessor } from "ppu-ocv";
++ const canvas = await CanvasProcessor.prepareCanvas(buffer);
++ const buf    = await CanvasProcessor.prepareBuffer(canvas);
+```
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/canvas-factory.js

@@ -1 +1 @@
-let _platform=null;export function setPlatform(platform){_platform=platform}export function getPlatform(){if(!_platform){throw new Error("No canvas platform registered. "+'Import "ppu-ocv" (Node) or "ppu-ocv/web" (browser) to auto-register.')}return _platform}
+let _platform=null;export function setPlatform(platform){_platform=platform}export function getPlatform(){if(!_platform){throw new Error("No canvas platform registered. "+'Import "ppu-ocv" (Node), "ppu-ocv/web" (browser), '+'"ppu-ocv/canvas" (Node canvas-only), or "ppu-ocv/canvas-web" (browser canvas-only) to auto-register.')}return _platform}

package/canvas-processor.d.ts

@@ -0,0 +1,18 @@
+import type { CanvasLike } from "./canvas-factory.js";
+/**
+ * Canvas I/O utilities that work without OpenCV.
+ * Safe to use in constrained environments (e.g. Browser Extensions)
+ * where OpenCV cannot be initialized.
+ */
+export declare class CanvasProcessor {
+    /**
+     * Convert an ArrayBuffer (image file bytes) to a CanvasLike.
+     * If the value is already a CanvasLike it is returned as-is.
+     */
+    static prepareCanvas(file: ArrayBuffer): Promise<CanvasLike>;
+    /**
+     * Convert a CanvasLike to an ArrayBuffer (PNG bytes).
+     * If the value is already an ArrayBuffer it is returned as-is.
+     */
+    static prepareBuffer(canvas: CanvasLike): Promise<ArrayBuffer>;
+}

package/canvas-processor.js

@@ -0,0 +1 @@
+export class CanvasProcessor{static async prepareCanvas(file){if(getPlatform().isCanvas(file))return file;return getPlatform().loadImage(file)}static async prepareBuffer(canvas){if(canvas instanceof ArrayBuffer)return canvas;if(typeof canvas.toBuffer==="function"){let buffer=canvas.toBuffer("image/png");let arrayBuffer=new ArrayBuffer(buffer.byteLength);new Uint8Array(arrayBuffer).set(new Uint8Array(buffer));return arrayBuffer}if(typeof canvas.toDataURL==="function"){let dataURL=canvas.toDataURL("image/png");let base64Data=dataURL.replace(/^data:image\/png;base64,/,"");let binaryString=atob(base64Data);let arrayBuffer=new ArrayBuffer(binaryString.length);let bytes=new Uint8Array(arrayBuffer);for(let i=0;i<binaryString.length;i++){bytes[i]=binaryString.charCodeAt(i)}return arrayBuffer}let ctx=canvas.getContext("2d");let imageData=ctx.getImageData(0,0,canvas.width,canvas.height);let canvasBuffer=new ArrayBuffer(imageData.data.byteLength);new Uint8Array(canvasBuffer).set(new Uint8Array(imageData.data.buffer,imageData.data.byteOffset,imageData.data.byteLength));return canvasBuffer}}import{getPlatform}from"./canvas-factory.js";

package/canvas-toolkit.base.d.ts

@@ -1,6 +1,9 @@
 import type { BoundingBox } from "./index.interface.js";
 import type { CanvasLike, Context2DLike } from "./canvas-factory.js";
-import { cv } from "./cv-provider.js";
+/** Structural interface for contour-like objects with 32-bit signed integer point data */
+export interface ContourLike {
+    data32S: Int32Array | number[];
+}
 /**
  * Cross-platform base class for canvas manipulation utilities.
  * Contains only methods that work in both Node and browser environments.
@@ -42,7 +45,7 @@ export declare class CanvasToolkitBase {
      */
     drawContour(options: {
         ctx: Context2DLike;
-        contour: cv.Mat;
+        contour: ContourLike;
         strokeStyle?: string;
         lineWidth?: number;
     }): void;

package/deskew.d.ts

@@ -0,0 +1,68 @@
+import type { CanvasLike } from "./canvas-factory.js";
+/**
+ * Options for configuring the deskew service
+ */
+export interface DeskewOptions {
+    /**
+     * Enable detailed logging of each processing step.
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Remove detected boxes with area below this threshold, in pixels.
+     * Used to filter out noise when detecting text regions.
+     * @default 20
+     */
+    minimumAreaThreshold?: number;
+}
+/**
+ * Service for calculating the skew angle of an image containing text.
+ *
+ * This service analyzes text regions in an image to determine its skew angle
+ * using multiple methods (minAreaRect, baseline analysis, and Hough transform)
+ * to robustly calculate the average text orientation.
+ *
+ * @example
+ * ```ts
+ * import { DeskewService } from 'ppu-ocv';
+ *
+ * const service = new DeskewService({ verbose: true });
+ * const canvas = ...; // your canvas with text
+ * const angle = await service.calculateSkewAngle(canvas);
+ * console.log(`Skew angle: ${angle}°`);
+ *
+ * // Or deskew the image directly
+ * const deskewed = await service.deskewImage(canvas);
+ * ```
+ */
+export declare class DeskewService {
+    private readonly verbose;
+    private readonly minimumAreaThreshold;
+    constructor(options?: DeskewOptions);
+    private log;
+    /**
+     * Calculate the skew angle of text in a probability map or binary image.
+     *
+     * This method processes the input image to detect text regions and calculates
+     * the average skew angle using multiple robust methods.
+     *
+     * @param canvas - Canvas containing a probability map or binary image of text regions
+     * @returns The calculated skew angle in degrees (positive = clockwise, negative = counter-clockwise)
+     */
+    calculateSkewAngle(canvas: CanvasLike): Promise<number>;
+    /**
+     * Deskew an image by detecting its skew angle and rotating it.
+     *
+     * This is a convenience method that combines `calculateSkewAngle()`
+     * with rotation to produce a straightened image.
+     *
+     * @param canvas - Canvas containing the image to deskew
+     * @returns A new canvas with the deskewed image
+     */
+    deskewImage(canvas: CanvasLike): Promise<CanvasLike>;
+    private calculateMinRectAngles;
+    private calculateBaselineAngles;
+    private calculateHoughAngles;
+    private calculateLineAngle;
+    private calculateConsensusAngle;
+}

package/deskew.js

@@ -0,0 +1 @@
+export class DeskewService{verbose;minimumAreaThreshold;constructor(options={}){this.verbose=options.verbose??false;this.minimumAreaThreshold=options.minimumAreaThreshold??20}log(message){if(this.verbose){console.log(`[DeskewService] ${message}`)}}async calculateSkewAngle(canvas){let processor=new ImageProcessor(canvas);let mat=processor.grayscale().threshold({lower:0,upper:255,type:cv.THRESH_BINARY+cv.THRESH_OTSU}).toMat();let contours=new Contours(mat,{mode:cv.RETR_LIST,method:cv.CHAIN_APPROX_SIMPLE});processor.destroy();let minAngle=-20;let maxAngle=20;let minArea=this.minimumAreaThreshold;let textRegions=[];contours.iterate((contour)=>{let rect=contours.getRect(contour);let area=rect.width*rect.height;if(area<minArea)return;let aspectRatio=rect.width/rect.height;if(aspectRatio>0.2&&aspectRatio<10){textRegions.push({rect,contour,area,aspectRatio})}});if(textRegions.length===0){this.log("No valid text regions found for skew calculation.");contours.destroy();return 0}let averageHeight=textRegions.reduce((sum,region)=>sum+region.rect.height,0)/textRegions.length;let filteredRegions=textRegions.filter((region)=>{return region.rect.height<=averageHeight*1.5});this.log(`Found ${filteredRegions.length} text regions for skew analysis.`);let minRectAngles=this.calculateMinRectAngles(filteredRegions,contours);let baselineAngles=this.calculateBaselineAngles(filteredRegions);let houghAngles=this.calculateHoughAngles(mat,minAngle,maxAngle);contours.destroy();let allAngles=[...minRectAngles.map((a)=>({...a,method:"minRect"})),...baselineAngles.map((a)=>({...a,method:"baseline"})),...houghAngles.map((a)=>({...a,method:"hough"}))];if(allAngles.length===0){this.log("No angles detected from any method.");return 0}let consensusAngle=this.calculateConsensusAngle(allAngles,minAngle,maxAngle);this.log(`Calculated skew angle: ${consensusAngle.toFixed(3)}° (from ${allAngles.length} measurements)`);return consensusAngle}async deskewImage(canvas){this.log("Starting image deskewing process");let angle=await this.calculateSkewAngle(canvas);this.log(`Detected skew angle: ${angle.toFixed(2)}°. Rotating image by ${-angle.toFixed(2)}°...`);let processor=new ImageProcessor(canvas);try{let rotatedCanvas=processor.rotate({angle}).toCanvas();return rotatedCanvas}finally{processor.destroy()}}calculateMinRectAngles(textRegions,contours){let angles=[];for(let region of textRegions){try{let minRect=cv.minAreaRect(region.contour);if(!minRect)continue;let angle=minRect.angle;if(angle>45){angle-=90}else if(angle<-45){angle+=90}let areaWeight=Math.log(region.area+1);let aspectWeight=Math.min(region.aspectRatio,1/region.aspectRatio)*2;let weight=areaWeight*aspectWeight;angles.push({angle,weight})}catch(error){continue}}return angles}calculateBaselineAngles(textRegions){let angles=[];for(let region of textRegions){try{let points=region.contour.data32S;if(!points||points.length<8)continue;let bottomPoints=[];for(let i=0;i<points.length;i+=2){let x=points[i];let y=points[i+1];if(x!==undefined&&y!==undefined){bottomPoints.push({x,y})}}if(bottomPoints.length<3)continue;bottomPoints.sort((a,b)=>a.x-b.x);let segments=3;let segmentSize=Math.floor(bottomPoints.length/segments);let baselinePoints=[];for(let seg=0;seg<segments;seg++){let start=seg*segmentSize;let end=seg===segments-1?bottomPoints.length:(seg+1)*segmentSize;let segmentPoints=bottomPoints.slice(start,end);if(segmentPoints.length>0){let maxYPoint=segmentPoints.reduce((max,point)=>point.y>max.y?point:max);baselinePoints.push(maxYPoint)}}if(baselinePoints.length>=2){let angle=this.calculateLineAngle(baselinePoints);let weight=region.area*Math.min(region.aspectRatio,1/region.aspectRatio);angles.push({angle,weight})}}catch(error){continue}}return angles}calculateHoughAngles(mat,minAngle,maxAngle){let angles=[];try{let kernel=cv.getStructuringElement(cv.MORPH_RECT,new cv.Size(3,1));let morphed=new cv.Mat;cv.morphologyEx(mat,morphed,cv.MORPH_CLOSE,kernel);let lines=new cv.Mat;cv.HoughLinesP(morphed,lines,1,Math.PI/180,30,50,10);for(let i=0;i<lines.rows;i++){let line=lines.data32S.subarray(i*4,(i+1)*4);const[x1,y1,x2,y2]=line;if(x1!==undefined&&y1!==undefined&&x2!==undefined&&y2!==undefined){let dx=x2-x1;let dy=y2-y1;if(Math.abs(dx)>1){let angle=Math.atan2(dy,dx)*180/Math.PI;if(angle>45)angle-=90;if(angle<-45)angle+=90;if(angle>=minAngle&&angle<=maxAngle){let lineLength=Math.sqrt(dx*dx+dy*dy);angles.push({angle,weight:lineLength})}}}}morphed.delete();lines.delete();kernel.delete()}catch(error){this.log("Hough transform failed, skipping this method.")}return angles}calculateLineAngle(points){if(points.length<2)return 0;let n=points.length;let sumX=points.reduce((sum,p)=>sum+p.x,0);let sumY=points.reduce((sum,p)=>sum+p.y,0);let sumXY=points.reduce((sum,p)=>sum+p.x*p.y,0);let sumXX=points.reduce((sum,p)=>sum+p.x*p.x,0);let denominator=n*sumXX-sumX*sumX;if(Math.abs(denominator)<0.0000000001)return 0;let slope=(n*sumXY-sumX*sumY)/denominator;let angle=Math.atan(slope)*180/Math.PI;if(angle>45)angle-=90;if(angle<-45)angle+=90;return angle}calculateConsensusAngle(angles,minAngle,maxAngle){if(angles.length===0)return 0;let sortedAngles=[...angles].sort((a,b)=>a.angle-b.angle);let q1Index=Math.floor(sortedAngles.length*0.25);let q3Index=Math.floor(sortedAngles.length*0.75);let q1=sortedAngles[q1Index]?.angle||0;let q3=sortedAngles[q3Index]?.angle||0;let iqr=q3-q1;let lowerBound=q1-1.5*iqr;let upperBound=q3+1.5*iqr;let filteredAngles=angles.filter((a)=>a.angle>=lowerBound&&a.angle<=upperBound&&a.angle>=minAngle&&a.angle<=maxAngle);if(filteredAngles.length===0){this.log("All angles filtered out as outliers, using median of original set.");let medianIndex=Math.floor(sortedAngles.length/2);return sortedAngles[medianIndex]?.angle||0}let totalWeight=filteredAngles.reduce((sum,a)=>sum+a.weight,0);if(totalWeight===0){let average=filteredAngles.reduce((sum,a)=>sum+a.angle,0)/filteredAngles.length;return average}let weightedSum=filteredAngles.reduce((sum,a)=>sum+a.angle*a.weight,0);let weightedAverage=weightedSum/totalWeight;let methodCounts=filteredAngles.reduce((counts,a)=>{counts[a.method]=(counts[a.method]||0)+1;return counts},{});this.log(`Angle methods used: ${Object.entries(methodCounts).map(([method,count])=>`${method}:${count}`).join(", ")}`);return Math.max(minAngle,Math.min(maxAngle,weightedAverage))}}import{Contours}from"./contours.js";import{cv}from"./cv-provider.js";import{ImageProcessor}from"./image-processor.js";

package/image-processor.d.ts

@@ -14,14 +14,6 @@ export declare class ImageProcessor {
      * @param source Source image as CanvasLike or cv.Mat
      */
     constructor(source: CanvasLike | cv.Mat);
-    /**
-     * Convert array buffer to canvas
-     */
-    static prepareCanvas(file: ArrayBuffer): Promise<CanvasLike>;
-    /**
-     * Convert canvas to array buffer
-     */
-    static prepareBuffer(canvas: CanvasLike): Promise<ArrayBuffer>;
     /**
      * Initialize OpenCV runtime. Must be called before any image processing.
      *

package/image-processor.js

@@ -1 +1 @@
-export class ImageProcessor{img;width;height;constructor(source){if(getPlatform().isCanvas(source)){let ctx=source.getContext("2d");let imageData=ctx.getImageData(0,0,source.width,source.height);this.img=cv.matFromImageData(imageData);this.width=source.width;this.height=source.height}else if(source instanceof cv.Mat){this.img=source;this.width=source.cols;this.height=source.rows}else{throw new Error("Invalid source type. Must be either Canvas or cv.Mat.")}}static async prepareCanvas(file){if(getPlatform().isCanvas(file))return file;return getPlatform().loadImage(file)}static async prepareBuffer(canvas){if(canvas instanceof ArrayBuffer)return canvas;if(typeof canvas.toBuffer==="function"){let buffer=canvas.toBuffer("image/png");let arrayBuffer=new ArrayBuffer(buffer.byteLength);new Uint8Array(arrayBuffer).set(new Uint8Array(buffer));return arrayBuffer}if(typeof canvas.toDataURL==="function"){let dataURL=canvas.toDataURL("image/png");let base64Data=dataURL.replace(/^data:image\/png;base64,/,"");let binaryString=atob(base64Data);let arrayBuffer=new ArrayBuffer(binaryString.length);let bytes=new Uint8Array(arrayBuffer);for(let i=0;i<binaryString.length;i++){bytes[i]=binaryString.charCodeAt(i)}return arrayBuffer}let ctx=canvas.getContext("2d");let imageData=ctx.getImageData(0,0,canvas.width,canvas.height);let canvasBuffer=new ArrayBuffer(imageData.data.byteLength);new Uint8Array(canvasBuffer).set(new Uint8Array(imageData.data.buffer,imageData.data.byteOffset,imageData.data.byteLength));return canvasBuffer}static async initRuntime(){if(globalThis.cv?.Mat){setCv(globalThis.cv);return}try{let mod=await import("@techstark/opencv-js");let _cv=mod.default||mod;setCv(_cv);if(!_cv.Mat){await new Promise((res)=>{_cv["onRuntimeInitialized"]=()=>res()})}return}catch{}if(typeof document!=="undefined"){await new Promise((resolve,reject)=>{let script=document.createElement("script");script.src="https://cdn.jsdelivr.net/npm/@techstark/opencv-js@4.10.0-release.1/dist/opencv.js";script.async=true;script.onload=()=>{let g=globalThis;if(g.cv?.Mat){setCv(g.cv);resolve()}else if(g.cv){g.cv["onRuntimeInitialized"]=()=>{setCv(g.cv);resolve()}}else{reject(new Error("OpenCV.js loaded but cv not found on globalThis"))}};script.onerror=()=>reject(new Error("Failed to load @techstark/opencv-js from CDN"));document.head.appendChild(script)});return}throw new Error("Cannot initialize OpenCV runtime. Install @techstark/opencv-js or run in a browser.")}execute(operationName,options){let result=executeOperation(operationName,this.img,options);this.img=result.img;this.width=result.width;this.height=result.height;return this}grayscale(options){return this.execute("grayscale",options)}blur(options){return this.execute("blur",options)}threshold(options){return this.execute("threshold",options)}adaptiveThreshold(options){return this.execute("adaptiveThreshold",options)}invert(options){return this.execute("invert",options)}canny(options){return this.execute("canny",options)}dilate(options){return this.execute("dilate",options)}erode(options){return this.execute("erode",options)}border(options){return this.execute("border",options)}resize(options){return this.execute("resize",options)}rotate(options){return this.execute("rotate",options)}warp(options){return this.execute("warp",options)}convert(options){return this.execute("convert",options)}morphologicalGradient(options){return this.execute("morphologicalGradient",options)}toMat(){return this.img}toCanvas(){let platform=getPlatform();let canvas=platform.createCanvas(this.width,this.height);try{cv.imshow(canvas,this.img)}catch(e){let ctx=canvas.getContext("2d");if(!ctx)throw new Error("Could not get 2d context from canvas");let imgData=ctx.createImageData(this.width,this.height);if(this.img.channels()===1){let data=imgData.data;let gray=new Uint8Array(this.img.data);for(let i=0;i<gray.length;i++){data[i*4]=gray[i];data[i*4+1]=gray[i];data[i*4+2]=gray[i];data[i*4+3]=255}}else{imgData.data.set(new Uint8ClampedArray(this.img.data))}ctx.putImageData(imgData,0,0)}return canvas}destroy(){try{this.img.delete()}catch{}}}import{getPlatform}from"./canvas-factory.js";import{cv,setCv}from"./cv-provider.js";import{executeOperation}from"./pipeline/index.js";
+export class ImageProcessor{img;width;height;constructor(source){if(getPlatform().isCanvas(source)){let ctx=source.getContext("2d");let imageData=ctx.getImageData(0,0,source.width,source.height);this.img=cv.matFromImageData(imageData);this.width=source.width;this.height=source.height}else if(source instanceof cv.Mat){this.img=source;this.width=source.cols;this.height=source.rows}else{throw new Error("Invalid source type. Must be either Canvas or cv.Mat.")}}static async initRuntime(){if(globalThis.cv?.Mat){setCv(globalThis.cv);return}try{let mod=await import("@techstark/opencv-js");let _cv=mod.default||mod;setCv(_cv);if(!_cv.Mat){await new Promise((res)=>{_cv["onRuntimeInitialized"]=()=>res()})}return}catch{}if(typeof document!=="undefined"){await new Promise((resolve,reject)=>{let script=document.createElement("script");script.src="https://cdn.jsdelivr.net/npm/@techstark/opencv-js@4.10.0-release.1/dist/opencv.js";script.async=true;script.onload=()=>{let g=globalThis;if(g.cv?.Mat){setCv(g.cv);resolve()}else if(g.cv){g.cv["onRuntimeInitialized"]=()=>{setCv(g.cv);resolve()}}else{reject(new Error("OpenCV.js loaded but cv not found on globalThis"))}};script.onerror=()=>reject(new Error("Failed to load @techstark/opencv-js from CDN"));document.head.appendChild(script)});return}throw new Error("Cannot initialize OpenCV runtime. Install @techstark/opencv-js or run in a browser.")}execute(operationName,options){let result=executeOperation(operationName,this.img,options);this.img=result.img;this.width=result.width;this.height=result.height;return this}grayscale(options){return this.execute("grayscale",options)}blur(options){return this.execute("blur",options)}threshold(options){return this.execute("threshold",options)}adaptiveThreshold(options){return this.execute("adaptiveThreshold",options)}invert(options){return this.execute("invert",options)}canny(options){return this.execute("canny",options)}dilate(options){return this.execute("dilate",options)}erode(options){return this.execute("erode",options)}border(options){return this.execute("border",options)}resize(options){return this.execute("resize",options)}rotate(options){return this.execute("rotate",options)}warp(options){return this.execute("warp",options)}convert(options){return this.execute("convert",options)}morphologicalGradient(options){return this.execute("morphologicalGradient",options)}toMat(){return this.img}toCanvas(){let platform=getPlatform();let canvas=platform.createCanvas(this.width,this.height);try{cv.imshow(canvas,this.img)}catch(e){let ctx=canvas.getContext("2d");if(!ctx)throw new Error("Could not get 2d context from canvas");let imgData=ctx.createImageData(this.width,this.height);if(this.img.channels()===1){let data=imgData.data;let gray=new Uint8Array(this.img.data);for(let i=0;i<gray.length;i++){data[i*4]=gray[i];data[i*4+1]=gray[i];data[i*4+2]=gray[i];data[i*4+3]=255}}else{imgData.data.set(new Uint8ClampedArray(this.img.data))}ctx.putImageData(imgData,0,0)}return canvas}destroy(){try{this.img.delete()}catch{}}}import{getPlatform}from"./canvas-factory.js";import{cv,setCv}from"./cv-provider.js";import{executeOperation}from"./pipeline/index.js";

package/index.canvas-web.d.ts

@@ -0,0 +1,6 @@
+export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
+export { getPlatform, setPlatform } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export { webPlatform } from "./platform/web.js";
+export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
+export { CanvasProcessor } from "./canvas-processor.js";

package/index.canvas-web.js

@@ -0,0 +1 @@
+import{setPlatform}from"./canvas-factory.js";import{webPlatform}from"./platform/web.js";setPlatform(webPlatform);export{getPlatform,setPlatform}from"./canvas-factory.js";export{webPlatform}from"./platform/web.js";export{CanvasToolkitBase as CanvasToolkit,CanvasToolkitBase}from"./canvas-toolkit.base.js";export{CanvasProcessor}from"./canvas-processor.js";

package/index.canvas.d.ts

@@ -0,0 +1,8 @@
+export { Canvas, createCanvas, ImageData, loadImage } from "@napi-rs/canvas";
+export type { SKRSContext2D } from "@napi-rs/canvas";
+export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
+export { getPlatform, setPlatform } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
+export { CanvasToolkit } from "./canvas-toolkit.js";
+export { CanvasProcessor } from "./canvas-processor.js";

package/index.canvas.js

@@ -0,0 +1 @@
+import{setPlatform}from"./canvas-factory.js";import{nodePlatform}from"./platform/node.js";setPlatform(nodePlatform);export{Canvas,createCanvas,ImageData,loadImage}from"@napi-rs/canvas";export{getPlatform,setPlatform}from"./canvas-factory.js";export{CanvasToolkitBase}from"./canvas-toolkit.base.js";export{CanvasToolkit}from"./canvas-toolkit.js";export{CanvasProcessor}from"./canvas-processor.js";

package/index.d.ts

@@ -6,9 +6,11 @@ export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
 export { executeOperation, OperationRegistry, registry, } from "./pipeline/index.js";
 export { getPlatform, setPlatform } from "./canvas-factory.js";
 export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
-export { CanvasToolkitBase } from "./canvas-toolkit.base.js";
+export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
+export { CanvasProcessor } from "./canvas-processor.js";
 export { Contours } from "./contours.js";
 export { calculateMeanGrayscaleValue, calculateMeanNormalizedLabLightness, type CalculateMeanLightnessOptions, } from "./image-analysis.js";
 export { ImageProcessor } from "./image-processor.js";
+export { DeskewService, type DeskewOptions } from "./deskew.js";
 export type { AdaptiveThresholdOptions, BlurOptions, BorderOptions, CannyOptions, DilateOptions, ErodeOptions, GrayscaleOptions, InvertOptions, MorphologicalGradientOptions, OperationFunction, OperationName, OperationOptions, OperationResult, PartialOptions, RegisteredOperations, RequiredOptions, ResizeOptions, RotateOptions, ThresholdOptions, WarpOptions, } from "./pipeline/index.js";

package/index.js

@@ -1 +1 @@
-import _cv from"@techstark/opencv-js";import{cv,setCv}from"./cv-provider.js";setCv(_cv);export{cv};import{setPlatform}from"./canvas-factory.js";import{nodePlatform}from"./platform/node.js";setPlatform(nodePlatform);export{Canvas,createCanvas,ImageData,loadImage}from"@napi-rs/canvas";export{executeOperation,OperationRegistry,registry}from"./pipeline/index.js";export{getPlatform,setPlatform}from"./canvas-factory.js";export{CanvasToolkitBase}from"./canvas-toolkit.base.js";export{CanvasToolkit}from"./canvas-toolkit.js";export{Contours}from"./contours.js";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis.js";export{ImageProcessor}from"./image-processor.js";
+import _cv from"@techstark/opencv-js";import{cv,setCv}from"./cv-provider.js";setCv(_cv);export{cv};import{setPlatform}from"./canvas-factory.js";import{nodePlatform}from"./platform/node.js";setPlatform(nodePlatform);export{Canvas,createCanvas,ImageData,loadImage}from"@napi-rs/canvas";export{executeOperation,OperationRegistry,registry}from"./pipeline/index.js";export{getPlatform,setPlatform}from"./canvas-factory.js";export{CanvasToolkitBase}from"./canvas-toolkit.base.js";export{CanvasToolkit}from"./canvas-toolkit.js";export{CanvasProcessor}from"./canvas-processor.js";export{Contours}from"./contours.js";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis.js";export{ImageProcessor}from"./image-processor.js";export{DeskewService}from"./deskew.js";

package/index.web.d.ts

@@ -5,8 +5,10 @@ export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factor
 export { webPlatform } from "./platform/web.js";
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
 export { executeOperation, OperationRegistry, registry, } from "./pipeline/index.js";
-export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, } from "./canvas-toolkit.base.js";
+export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
+export { CanvasProcessor } from "./canvas-processor.js";
 export { Contours } from "./contours.js";
 export { calculateMeanGrayscaleValue, calculateMeanNormalizedLabLightness, type CalculateMeanLightnessOptions, } from "./image-analysis.js";
 export { ImageProcessor } from "./image-processor.js";
+export { DeskewService, type DeskewOptions } from "./deskew.js";
 export type { AdaptiveThresholdOptions, BlurOptions, BorderOptions, CannyOptions, DilateOptions, ErodeOptions, GrayscaleOptions, InvertOptions, MorphologicalGradientOptions, OperationFunction, OperationName, OperationOptions, OperationResult, PartialOptions, RegisteredOperations, RequiredOptions, ResizeOptions, RotateOptions, ThresholdOptions, WarpOptions, } from "./pipeline/index.js";

package/index.web.js

@@ -1 +1 @@
-import{cv}from"./cv-provider.js";export{cv};import{setPlatform}from"./canvas-factory.js";import{webPlatform}from"./platform/web.js";setPlatform(webPlatform);export{getPlatform,setPlatform}from"./canvas-factory.js";export{webPlatform}from"./platform/web.js";export{executeOperation,OperationRegistry,registry}from"./pipeline/index.js";export{CanvasToolkitBase as CanvasToolkit,CanvasToolkitBase}from"./canvas-toolkit.base.js";export{Contours}from"./contours.js";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis.js";export{ImageProcessor}from"./image-processor.js";
+import{cv}from"./cv-provider.js";export{cv};import{setPlatform}from"./canvas-factory.js";import{webPlatform}from"./platform/web.js";setPlatform(webPlatform);export{getPlatform,setPlatform}from"./canvas-factory.js";export{webPlatform}from"./platform/web.js";export{executeOperation,OperationRegistry,registry}from"./pipeline/index.js";export{CanvasToolkitBase as CanvasToolkit,CanvasToolkitBase}from"./canvas-toolkit.base.js";export{CanvasProcessor}from"./canvas-processor.js";export{Contours}from"./contours.js";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis.js";export{ImageProcessor}from"./image-processor.js";export{DeskewService}from"./deskew.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.",
   "keywords": [
     "open-cv",
@@ -33,6 +33,14 @@
     "./web": {
       "types": "./index.web.d.ts",
       "default": "./index.web.js"
+    },
+    "./canvas": {
+      "types": "./index.canvas.d.ts",
+      "default": "./index.canvas.js"
+    },
+    "./canvas-web": {
+      "types": "./index.canvas-web.d.ts",
+      "default": "./index.canvas-web.js"
     }
   },
   "scripts": {
@@ -40,7 +48,8 @@
     "build:test": "bun task build && bun test",
     "build:publish": "bun task build && bun task report-size && bun task publish",
     "lint": "prettier --check ./src",
-    "lint:fix": "prettier --write ./src"
+    "lint:fix": "prettier --write ./src",
+    "demo": "bunx -y serve -l 4567 ."
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "latest",