ppu-ocv 1.7.0 → 3.0.0

package/README.md

@@ -11,7 +11,7 @@ const processor = new ImageProcessor(canvas);
 
 const result = processor
   .grayscale()
-  .blur({ size: 5 })
+  .blur({ size: [5, 5] })
   .threshold()
   .invert()
   .dilate({ size: [20, 20], iter: 5 })
@@ -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
 
@@ -43,48 +45,45 @@ yarn add ppu-ocv
 bun add ppu-ocv
 ```
 
-> [!NOTE]
-> This project is developed and tested primarily with Bun.  
-> Support for Node.js, Deno, or browser environments is **not guaranteed**.  
-> If you choose to use it outside of Bun and encounter any issues, feel free to report them.  
-> I'm open to fixing bugs for other runtimes with community help.
+## Usage (Node.js / Bun)
 
-## Usage
-
-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 }).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", {
@@ -101,6 +100,127 @@ 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
+
+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 { CanvasProcessor, ImageProcessor, cv } from "ppu-ocv/web";
+
+await ImageProcessor.initRuntime();
+
+const response = await fetch("/my-image.jpg");
+const buffer = await response.arrayBuffer();
+
+const canvas = await CanvasProcessor.prepareCanvas(buffer);
+const processor = new ImageProcessor(canvas);
+
+processor
+  .grayscale()
+  .blur({ size: [5, 5] })
+  .threshold();
+
+const result = processor.toCanvas(); // returns HTMLCanvasElement
+document.body.appendChild(result);
+
+processor.destroy();
+```
+
+### Vanilla HTML (no bundler)
+
+`initRuntime()` automatically loads `@techstark/opencv-js` from the npm CDN if it's not already available. No extra script tags or import maps needed:
+
+```html
+<script type="module">
+  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();
+
+  const result = processor.toCanvas();
+  processor.destroy();
+</script>
+```
+
+> **Note:** ES modules require HTTP/HTTPS — use a local server (`npx serve .`) for dev, or deploy to GitHub Pages.
+
+See the [interactive demo](./index.html) for a full working example.
+
+### Entry point reference
+
+| 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. 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) {
+    /* ... */
+  },
+};
+
+setPlatform(myPlatform);
+```
+
 ## Built-in pipeline operations
 
 To avoid bloat, we only ship essential operations for chaining. Currently shipped operations are:
@@ -123,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`
 
@@ -147,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.
+A collection of utility functions for analyzing image properties (requires OpenCV).
 
-- `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.
-
-- `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
 
@@ -194,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).
@@ -208,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.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Platform abstraction layer for canvas operations.
+ * Allows ppu-ocv to work with both @napi-rs/canvas (Node) and browser canvas APIs.
+ */
+/** Structural type satisfied by both @napi-rs/canvas Canvas and HTMLCanvasElement/OffscreenCanvas */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(contextId: "2d"): any;
+    toBuffer?: (...args: any[]) => Buffer;
+    toDataURL?: (...args: any[]) => string;
+}
+/** Structural type for 2D rendering context */
+export interface Context2DLike {
+    canvas: any;
+    drawImage(...args: any[]): void;
+    getImageData(sx: number, sy: number, sw: number, sh: number): {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    };
+    putImageData(imageData: any, dx: number, dy: number): void;
+    createImageData(width: number, height: number): any;
+    beginPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    stroke(): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+}
+/** Platform-specific canvas operations */
+export interface CanvasPlatform {
+    createCanvas(width: number, height: number): CanvasLike;
+    loadImage(source: ArrayBuffer | string): Promise<CanvasLike>;
+    isCanvas(value: unknown): value is CanvasLike;
+}
+/** Register the platform-specific canvas implementation */
+export declare function setPlatform(platform: CanvasPlatform): void;
+/** Get the registered platform. Throws if none has been set. */
+export declare function getPlatform(): CanvasPlatform;

package/canvas-factory.js

@@ -0,0 +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), "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

@@ -0,0 +1,52 @@
+import type { BoundingBox } from "./index.interface.js";
+import type { CanvasLike, Context2DLike } from "./canvas-factory.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.
+ */
+export declare class CanvasToolkitBase {
+    protected static _baseInstance: CanvasToolkitBase | null;
+    protected step: number;
+    protected constructor();
+    static getInstance(): CanvasToolkitBase;
+    /**
+     * Crop a part of source canvas and return a new canvas of the cropped part
+     */
+    crop(options: {
+        bbox: BoundingBox;
+        canvas: CanvasLike;
+    }): CanvasLike;
+    /**
+     * Check whether a binary canvas is dirty (full of major color either black or white) or not
+     */
+    isDirty(options: {
+        canvas: CanvasLike;
+        threshold?: number;
+        majorColorThreshold?: number;
+    }): boolean;
+    /**
+     * Draw a non-filled rectangle on the canvas
+     */
+    drawLine(options: {
+        ctx: Context2DLike;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        lineWidth?: number;
+        color?: string;
+    }): void;
+    /**
+     * Draw a contour on the canvas
+     */
+    drawContour(options: {
+        ctx: Context2DLike;
+        contour: ContourLike;
+        strokeStyle?: string;
+        lineWidth?: number;
+    }): void;
+}

package/canvas-toolkit.base.js

@@ -0,0 +1 @@
+export class CanvasToolkitBase{static _baseInstance=null;step=0;constructor(){}static getInstance(){if(!CanvasToolkitBase._baseInstance){CanvasToolkitBase._baseInstance=new CanvasToolkitBase}return CanvasToolkitBase._baseInstance}crop(options){const{bbox,canvas}=options;let croppedCanvas=getPlatform().createCanvas(bbox.x1-bbox.x0,bbox.y1-bbox.y0);let croppedCtx=croppedCanvas.getContext("2d");croppedCtx.drawImage(canvas,bbox.x0,bbox.y0,bbox.x1-bbox.x0,bbox.y1-bbox.y0,0,0,croppedCanvas.width,croppedCanvas.height);return croppedCanvas}isDirty(options){const{canvas,threshold=127.5,majorColorThreshold=0.97}=options;let whiteCount=0;let blackCount=0;let borderlessCanvas=this.crop({bbox:{x0:canvas.width*0.1,y0:canvas.height*0.1,x1:canvas.width*0.9,y1:canvas.height*0.9},canvas});let ctx=borderlessCanvas.getContext("2d");let colorData=ctx.getImageData(0,0,borderlessCanvas.width,borderlessCanvas.height).data;for(let i=0;i<colorData.length;i+=4){let red=colorData[i];let green=colorData[i+1];let blue=colorData[i+2];if(red>=threshold&&green>=threshold&&blue>=threshold){whiteCount++}else{blackCount++}}let majorColorRatio=Math.max(whiteCount,blackCount)/(blackCount+whiteCount);return majorColorRatio<majorColorThreshold}drawLine(options){const{ctx,x,y,width,height,lineWidth=2,color="blue"}=options;ctx.beginPath();ctx.strokeStyle=color;ctx.lineWidth=lineWidth;ctx.strokeRect(x,y,width,height);ctx.closePath()}drawContour(options){const{ctx,contour,strokeStyle="red",lineWidth=2}=options;let pts=contour.data32S;if(pts.length<4)return;ctx.strokeStyle=strokeStyle;ctx.lineWidth=lineWidth;ctx.beginPath();ctx.moveTo(pts[0],pts[1]);for(let i=2;i<pts.length;i+=2){ctx.lineTo(pts[i],pts[i+1])}ctx.closePath();ctx.stroke()}}import{getPlatform}from"./canvas-factory.js";

package/canvas-toolkit.d.ts

@@ -1,58 +1,13 @@
-import type { BoundingBox, SKRSContext2D } from "./index.js";
-import { Canvas, cv } from "./index.js";
+import type { CanvasLike } from "./canvas-factory.js";
+import { CanvasToolkitBase } from "./canvas-toolkit.base.js";
 /**
- * Singleton class for canvas manipulation utilities
+ * Node.js canvas toolkit with file-system operations.
+ * Extends CanvasToolkitBase with saveImage() and clearOutput().
  */
-export declare class CanvasToolkit {
-    private static instance;
-    private step;
-    /**
-     * Private constructor to prevent direct instantiation
-     */
-    private constructor();
-    /**
-     * Get the singleton instance of CanvasToolkit
-     * @returns The singleton instance
-     * @example
-     * const canvasToolkit = CanvasToolkit.getInstance();
-     */
+export declare class CanvasToolkit extends CanvasToolkitBase {
+    private static _nodeInstance;
+    protected constructor();
     static getInstance(): CanvasToolkit;
-    /**
-     * Crop a part of source canvas and return a new canvas of the cropped part
-     * @param options
-     * @param options.bbox Bounding box of the cropped part
-     * @param options.canvas Source canvas
-     * @returns A new canvas of the cropped part
-     * @example
-     * const croppedCanvas = CanvasToolkit.getInstance().crop({
-     *   bbox: { x0: 10, y0: 10, x1: 100, y1: 100 },
-     *   canvas: sourceCanvas,
-     * });
-     */
-    crop(options: {
-        bbox: BoundingBox;
-        canvas: Canvas;
-    }): Canvas;
-    /**
-     * Check whether a binary canvas is dirty (full of major color either black or white) or not
-     * @param options
-     * @param options.canvas Source canvas
-     * @param options.threshold Threshold for color detection (default: 127.5)
-     * @param options.majorColorThreshold Major color threshold (default: 0.97)
-     * @returns true if the canvas is dirty, false otherwise
-     * @example
-     * const isDirty = CanvasToolkit.getInstance().isDirty({
-     *   canvas: sourceCanvas,
-     *   threshold: 127.5,
-     *   majorColorThreshold: 0.97,
-     * });
-     * console.log(isDirty); // true or false
-     */
-    isDirty(options: {
-        canvas: Canvas;
-        threshold?: number;
-        majorColorThreshold?: number;
-    }): boolean;
     /**
      * Save a canvas to an image file
      * @param options
@@ -67,7 +22,7 @@ export declare class CanvasToolkit {
      * });
      */
     saveImage(options: {
-        canvas: Canvas;
+        canvas: CanvasLike;
         filename: string;
         path: string;
     }): Promise<void>;
@@ -76,38 +31,4 @@ export declare class CanvasToolkit {
      * @param path Path to the output folder (default: "out")
      */
     clearOutput(path?: string): void;
-    /**
-     * Draw a non-filled rectangle on the canvas
-     * @param options
-     * @param options.ctx Canvas rendering context
-     * @param options.x X coordinate of the top-left corner
-     * @param options.y Y coordinate of the top-left corner
-     * @param options.width Width of the rectangle
-     * @param options.height Height of the rectangle
-     * @param options.lineWidth Line width (default: 2)
-     * @param options.color Color of the rectangle (default: "blue")
-     */
-    drawLine(options: {
-        ctx: SKRSContext2D;
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        lineWidth?: number;
-        color?: string;
-    }): void;
-    /**
-     * Draw a contour on the canvas
-     * @param options
-     * @param options.ctx Canvas rendering context
-     * @param options.contour Contour to be drawn
-     * @param options.strokeStyle Stroke color (default: "red")
-     * @param options.lineWidth Line width (default: 2)
-     */
-    drawContour(options: {
-        ctx: SKRSContext2D;
-        contour: cv.Mat;
-        strokeStyle?: string;
-        lineWidth?: number;
-    }): void;
 }

package/canvas-toolkit.js

@@ -1 +1 @@
-export class CanvasToolkit{static instance=null;step=0;constructor(){}static getInstance(){if(!CanvasToolkit.instance){CanvasToolkit.instance=new CanvasToolkit}return CanvasToolkit.instance}crop(options){const{bbox,canvas}=options;let croppedCanvas=createCanvas(bbox.x1-bbox.x0,bbox.y1-bbox.y0);let croppedCtx=croppedCanvas.getContext("2d");croppedCtx.drawImage(canvas,bbox.x0,bbox.y0,bbox.x1-bbox.x0,bbox.y1-bbox.y0,0,0,croppedCanvas.width,croppedCanvas.height);return croppedCanvas}isDirty(options){const{canvas,threshold=127.5,majorColorThreshold=0.97}=options;let whiteCount=0;let blackCount=0;let borderlessCanvas=this.crop({bbox:{x0:canvas.width*0.1,y0:canvas.height*0.1,x1:canvas.width*0.9,y1:canvas.height*0.9},canvas});let ctx=borderlessCanvas.getContext("2d");let colorData=ctx.getImageData(0,0,borderlessCanvas.width,borderlessCanvas.height).data;for(let i=0;i<colorData.length;i+=4){let red=colorData[i];let green=colorData[i+1];let blue=colorData[i+2];if(red>=threshold&&green>=threshold&&blue>=threshold){whiteCount++}else{blackCount++}}let majorColorRatio=Math.max(whiteCount,blackCount)/(blackCount+whiteCount);return majorColorRatio<majorColorThreshold}saveImage(options){const{canvas,filename,path="out"}=options;let folderPath=join(process.cwd(),path);if(!existsSync(folderPath)){mkdirSync(folderPath,{recursive:true})}let filePath=join(folderPath,`${this.step++}. ${filename}.png`);let out=createWriteStream(filePath);let buffer=canvas.toBuffer("image/png");return new Promise((res,rej)=>{out.write(buffer,(err)=>{if(err){rej(err)}else{res()}})})}clearOutput(path="out"){let folderPath=join(process.cwd(),path);if(existsSync(folderPath)){let files=readdirSync(folderPath);for(let file of files){if(file===".gitignore")continue;let filePath=join(folderPath,file);unlinkSync(filePath)}}}drawLine(options){const{ctx,x,y,width,height,lineWidth=2,color="blue"}=options;ctx.beginPath();ctx.strokeStyle=color;ctx.lineWidth=lineWidth;ctx.strokeRect(x,y,width,height);ctx.closePath()}drawContour(options){const{ctx,contour,strokeStyle="red",lineWidth=2}=options;let pts=contour.data32S;if(pts.length<4)return;ctx.strokeStyle=strokeStyle;ctx.lineWidth=lineWidth;ctx.beginPath();ctx.moveTo(pts[0],pts[1]);for(let i=2;i<pts.length;i+=2){ctx.lineTo(pts[i],pts[i+1])}ctx.closePath();ctx.stroke()}}import{createCanvas}from"./index.js";import{createWriteStream,existsSync,mkdirSync,readdirSync,unlinkSync}from"fs";import{join}from"path";
+import{CanvasToolkitBase}from"./canvas-toolkit.base.js";import{createWriteStream,existsSync,mkdirSync,readdirSync,unlinkSync}from"fs";import{join}from"path";export class CanvasToolkit extends CanvasToolkitBase{static _nodeInstance=null;constructor(){super()}static getInstance(){if(!CanvasToolkit._nodeInstance){CanvasToolkit._nodeInstance=new CanvasToolkit}return CanvasToolkit._nodeInstance}saveImage(options){const{canvas,filename,path="out"}=options;let folderPath=join(process.cwd(),path);if(!existsSync(folderPath)){mkdirSync(folderPath,{recursive:true})}let filePath=join(folderPath,`${this.step++}. ${filename}.png`);let out=createWriteStream(filePath);let buffer=canvas.toBuffer("image/png");return new Promise((res,rej)=>{out.write(buffer,(err)=>{if(err){rej(err)}else{res()}})})}clearOutput(path="out"){let folderPath=join(process.cwd(),path);if(existsSync(folderPath)){let files=readdirSync(folderPath);for(let file of files){if(file===".gitignore")continue;let filePath=join(folderPath,file);unlinkSync(filePath)}}}}

package/contours.d.ts

@@ -1,5 +1,6 @@
-import type { BoundingBox, Canvas, Points } from "./index.js";
-import { cv } from "./index.js";
+import type { CanvasLike } from "./canvas-factory.js";
+import { cv } from "./cv-provider.js";
+import type { BoundingBox, Points } from "./index.interface.js";
 export interface ContoursOptions {
     /** The contour retrieval mode. (cv.RETR_...) */
     mode: cv.RetrievalModes;
@@ -62,7 +63,7 @@ export declare class Contours {
      * @returns The four corner points of the contour (topLeft, topRight, bottomLeft, bottomRight) and the bounding box.
      */
     getCornerPoints(options: {
-        canvas: Canvas;
+        canvas: CanvasLike;
         contour?: cv.Mat;
     }): {
         points: Points;

package/contours.js

@@ -1 +1 @@
-export class Contours{contours;constructor(img,options={}){let opts={...defaultOptions(),...options};if(img instanceof cv.Mat){let contours=new cv.MatVector;let hierarchy=new cv.Mat;try{cv.findContours(img,contours,hierarchy,opts.mode,opts.method)}catch(error){throw error}hierarchy.delete();this.contours=contours}else{throw new Error("Invalid img type. Must be cv.Mat.")}}getAll(){return this.contours}getSize(){return this.contours.size()}getFromIndex(index){if(index<this.contours.size()){return this.contours.get(index)}return new cv.Mat}getRect(contour){return cv.boundingRect(contour)}iterate(callback){for(let i=0,len=this.contours.size();i<len;i++){let contour=this.contours.get(i);callback(contour)}return this}getLargestContourArea(){let maxArea=0;let largestContour=null;this.iterate((contour)=>{let area=cv.contourArea(contour);if(area>maxArea){maxArea=area;largestContour=contour}});return largestContour}getCornerPoints(options){const{canvas,contour=this.getLargestContourArea()}=options;let bbox={x0:0,y0:0,x1:canvas.width,y1:canvas.height};if(!contour){return{points:{topLeft:{x:bbox.x0,y:bbox.y0},topRight:{x:bbox.x1,y:bbox.y0},bottomLeft:{x:bbox.x0,y:bbox.y1},bottomRight:{x:bbox.x1,y:bbox.y1}},bbox}}let rect=cv.minAreaRect(contour);let vertices=cv.RotatedRect.points(rect);let points={topLeft:{x:0,y:0},topRight:{x:0,y:0},bottomRight:{x:0,y:0},bottomLeft:{x:0,y:0}};let sums=vertices.map((pt)=>pt.x+pt.y);let diffs=vertices.map((pt)=>pt.y-pt.x);let topLeftIdx=sums.indexOf(Math.min(...sums));let topRightIdx=diffs.indexOf(Math.min(...diffs));let bottomRightIdx=sums.indexOf(Math.max(...sums));let bottomLeftIdx=diffs.indexOf(Math.max(...diffs));if(!vertices[topLeftIdx]||!vertices[topRightIdx]||!vertices[bottomRightIdx]||!vertices[bottomLeftIdx]){return{points:{topLeft:{x:bbox.x0,y:bbox.y0},topRight:{x:bbox.x1,y:bbox.y0},bottomLeft:{x:bbox.x0,y:bbox.y1},bottomRight:{x:bbox.x1,y:bbox.y1}},bbox}}points.topLeft={x:vertices[topLeftIdx].x,y:vertices[topLeftIdx].y};points.topRight={x:vertices[topRightIdx].x,y:vertices[topRightIdx].y};points.bottomRight={x:vertices[bottomRightIdx].x,y:vertices[bottomRightIdx].y};points.bottomLeft={x:vertices[bottomLeftIdx].x,y:vertices[bottomLeftIdx].y};contour.delete();let ensureInBounds=(p)=>{p.x=Math.max(0,Math.min(canvas.width,p.x));p.y=Math.max(0,Math.min(canvas.height,p.y));return p};points.topLeft=ensureInBounds(points.topLeft);points.topRight=ensureInBounds(points.topRight);points.bottomLeft=ensureInBounds(points.bottomLeft);points.bottomRight=ensureInBounds(points.bottomRight);return{points,bbox}}getApproximateRectangleContour(options){const{threshold=0.02,contour=this.getLargestContourArea()}=options??{};if(!contour)return;let epsilon=threshold*cv.arcLength(contour,true);let approxContour=new cv.Mat;cv.approxPolyDP(contour,approxContour,epsilon,true);contour.delete();return approxContour}destroy(){try{this.contours.delete()}catch(error){}}}import{cv}from"./index.js";function defaultOptions(){return{mode:cv.RETR_EXTERNAL,method:cv.CHAIN_APPROX_SIMPLE}}
+export class Contours{contours;constructor(img,options={}){let opts={...defaultOptions(),...options};if(img instanceof cv.Mat){let contours=new cv.MatVector;let hierarchy=new cv.Mat;try{cv.findContours(img,contours,hierarchy,opts.mode,opts.method)}catch(error){throw error}hierarchy.delete();this.contours=contours}else{throw new Error("Invalid img type. Must be cv.Mat.")}}getAll(){return this.contours}getSize(){return this.contours.size()}getFromIndex(index){if(index<this.contours.size()){return this.contours.get(index)}return new cv.Mat}getRect(contour){return cv.boundingRect(contour)}iterate(callback){for(let i=0,len=this.contours.size();i<len;i++){let contour=this.contours.get(i);callback(contour)}return this}getLargestContourArea(){let maxArea=0;let largestContour=null;this.iterate((contour)=>{let area=cv.contourArea(contour);if(area>maxArea){maxArea=area;largestContour=contour}});return largestContour}getCornerPoints(options){const{canvas,contour=this.getLargestContourArea()}=options;let bbox={x0:0,y0:0,x1:canvas.width,y1:canvas.height};if(!contour){return{points:{topLeft:{x:bbox.x0,y:bbox.y0},topRight:{x:bbox.x1,y:bbox.y0},bottomLeft:{x:bbox.x0,y:bbox.y1},bottomRight:{x:bbox.x1,y:bbox.y1}},bbox}}let rect=cv.minAreaRect(contour);let vertices=cv.RotatedRect.points(rect);let points={topLeft:{x:0,y:0},topRight:{x:0,y:0},bottomRight:{x:0,y:0},bottomLeft:{x:0,y:0}};let sums=vertices.map((pt)=>pt.x+pt.y);let diffs=vertices.map((pt)=>pt.y-pt.x);let topLeftIdx=sums.indexOf(Math.min(...sums));let topRightIdx=diffs.indexOf(Math.min(...diffs));let bottomRightIdx=sums.indexOf(Math.max(...sums));let bottomLeftIdx=diffs.indexOf(Math.max(...diffs));if(!vertices[topLeftIdx]||!vertices[topRightIdx]||!vertices[bottomRightIdx]||!vertices[bottomLeftIdx]){return{points:{topLeft:{x:bbox.x0,y:bbox.y0},topRight:{x:bbox.x1,y:bbox.y0},bottomLeft:{x:bbox.x0,y:bbox.y1},bottomRight:{x:bbox.x1,y:bbox.y1}},bbox}}points.topLeft={x:vertices[topLeftIdx].x,y:vertices[topLeftIdx].y};points.topRight={x:vertices[topRightIdx].x,y:vertices[topRightIdx].y};points.bottomRight={x:vertices[bottomRightIdx].x,y:vertices[bottomRightIdx].y};points.bottomLeft={x:vertices[bottomLeftIdx].x,y:vertices[bottomLeftIdx].y};contour.delete();let ensureInBounds=(p)=>{p.x=Math.max(0,Math.min(canvas.width,p.x));p.y=Math.max(0,Math.min(canvas.height,p.y));return p};points.topLeft=ensureInBounds(points.topLeft);points.topRight=ensureInBounds(points.topRight);points.bottomLeft=ensureInBounds(points.bottomLeft);points.bottomRight=ensureInBounds(points.bottomRight);return{points,bbox}}getApproximateRectangleContour(options){const{threshold=0.02,contour=this.getLargestContourArea()}=options??{};if(!contour)return;let epsilon=threshold*cv.arcLength(contour,true);let approxContour=new cv.Mat;cv.approxPolyDP(contour,approxContour,epsilon,true);contour.delete();return approxContour}destroy(){try{this.contours.delete()}catch(error){}}}import{cv}from"./cv-provider.js";function defaultOptions(){return{mode:cv.RETR_EXTERNAL,method:cv.CHAIN_APPROX_SIMPLE}}