ppu-ocv 2.0.0 → 3.1.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,86 @@ 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-native image processing with **no OpenCV dependency**. Available from all entry points including `ppu-ocv/canvas` and `ppu-ocv/canvas-web`. Provides a chainable instance API alongside static I/O helpers.
+
+```ts
+const result = new CanvasProcessor(canvas)
+  .resize({ width: 360, height: 640 })
+  .grayscale()
+  .threshold({ thresh: 127 })
+  .invert()
+  .border({ size: 10, color: "white" })
+  .toCanvas();
+
+// Detect connected white regions on a binary image
+const regions = new CanvasProcessor(binaryCanvas).findRegions({
+  foreground: "light",
+  minArea: 20,
+  // thresh: 0  ← use on resized binary images to match OpenCV (any non-zero pixel = foreground)
+  // padding: { vertical: 0.4, horizontal: 0.6 }  ← expand bbox by fraction of height
+  // scale: 1 / resizeRatio                        ← map coords back to original image space
+});
+regions.sort((a, b) => b.area - a.area); // largest first
+// regions[0] → { bbox: { x0, y0, x1, y1 }, area }
+```
+
+**Static I/O**
+
+| Method                 | Args        | Description                                           |
+| ---------------------- | ----------- | ----------------------------------------------------- |
+| static `prepareCanvas` | ArrayBuffer | Load image bytes into a `CanvasLike`                  |
+| static `prepareBuffer` | CanvasLike  | Export a `CanvasLike` to an `ArrayBuffer` (PNG bytes) |
+
+**Instance operations** (chainable, return `this`)
+
+| Method      | Options                            | OpenCV equivalent         | Fidelity       |
+| ----------- | ---------------------------------- | ------------------------- | -------------- |
+| `resize`    | `width`, `height`                  | `cv.resize` INTER_LINEAR  | 1:1 (↓), ≈ (↑) |
+| `grayscale` | —                                  | `COLOR_RGBA2GRAY`         | **1:1**        |
+| `convert`   | `alpha?`, `beta?`                  | `Mat.convertTo` (α·x + β) | **1:1**        |
+| `invert`    | —                                  | `cv.bitwise_not`          | **1:1** ¹      |
+| `threshold` | `thresh?` (127), `maxValue?` (255) | `THRESH_BINARY`           | **1:1**        |
+| `border`    | `size?` (10), `color?` (CSS)       | `BORDER_CONSTANT`         | **1:1**        |
+| `rotate`    | `angle`, `cx?`, `cy?`              | `warpAffine`              | ≈ (±6 px) ²    |
+| `toCanvas`  | —                                  | —                         | —              |
+
+**Region detection** (returns data, does not mutate)
+
+| Method        | Options                                          | Description                                                  |
+| ------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| `findRegions` | `foreground?` (`"light"`), `thresh?` (127), `minArea?`, `maxArea?`, `padding?`, `scale?` | 8-connected flood-fill on a binary canvas → `DetectedRegion[]` |
+
+`DetectedRegion` shape: `{ bbox: BoundingBox, area: number }` where `bbox` is `{ x0, y0, x1, y1 }` (x1/y1 exclusive). Equivalent to OpenCV's `findContours(RETR_EXTERNAL) + boundingRect` — all matched bboxes agree within ±1 px on solid binary images. ³
+
+**`thresh` option** — pixel value threshold for foreground detection (default `127`). For resized binary images, use `thresh: 0` so anti-aliased border pixels (values 1–127) are included as foreground, matching OpenCV's non-zero threshold. With `thresh: 0` + `padding` + `scale`, full-pipeline IoU vs OpenCV is **98.4%** (all 21/21 boxes matched).
+
+> ¹ Canvas `invert` preserves the alpha channel; OpenCV `bitwise_not` also inverts alpha. Results are identical when the source is opaque (alpha=255).
+>
+> ² Canvas uses anti-aliased bilinear interpolation; OpenCV uses plain bilinear. Difference is visually imperceptible and has no impact on OCR quality.
+>
+> ³ `RETR_LIST` may return additional inner-hole contours for white regions that contain dark sub-regions; `findRegions` counts each connected white component once regardless of interior holes.
+
 #### `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 +330,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 +387,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 +399,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

@@ -29,6 +29,12 @@ export interface Context2DLike {
     strokeRect(x: number, y: number, w: number, h: number): void;
     strokeStyle: string | CanvasGradient | CanvasPattern;
     lineWidth: number;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
 }
 /** Platform-specific canvas operations */
 export interface CanvasPlatform {

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,200 @@
+import type { BoundingBox } from "./index.interface.js";
+import type { CanvasLike } from "./canvas-factory.js";
+/**
+ * A detected region returned by {@link CanvasProcessor.findRegions}.
+ */
+export interface DetectedRegion {
+    /** Axis-aligned bounding box of the region (x1/y1 are exclusive). */
+    bbox: BoundingBox;
+    /** Number of foreground pixels in the region. */
+    area: number;
+}
+/**
+ * Canvas-native image processing with no OpenCV dependency.
+ *
+ * Provides two distinct APIs:
+ * - **Static I/O** (`prepareCanvas`, `prepareBuffer`) — format conversion helpers.
+ * - **Chainable instance operations** (`resize`, `grayscale`, `convert`, `invert`,
+ *   `threshold`, `border`, `rotate`) — lightweight canvas-native pipeline, usable
+ *   in constrained environments where OpenCV cannot run.
+ * - **Region detection** (`findRegions`) — 8-connected flood-fill bbox detection
+ *   on binary images, with optional padding and coordinate scaling.
+ *
+ * @example
+ * ```ts
+ * import { CanvasProcessor } from "ppu-ocv/canvas";
+ *
+ * const canvas = await CanvasProcessor.prepareCanvas(arrayBuffer);
+ *
+ * // Pixel pipeline
+ * const result = new CanvasProcessor(canvas)
+ *   .resize({ width: 800, height: 600 })
+ *   .grayscale()
+ *   .threshold({ thresh: 127 })
+ *   .border({ size: 10, color: "white" })
+ *   .toCanvas();
+ *
+ * // Region detection (equivalent to findContours + boundingRect)
+ * const regions = new CanvasProcessor(binaryCanvas).findRegions({
+ *   foreground: "light",
+ *   minArea: 20,
+ *   padding: { vertical: 0.4, horizontal: 0.6 },
+ *   scale: originalWidth / processedWidth,
+ * });
+ * ```
+ */
+export declare class CanvasProcessor {
+    private _canvas;
+    constructor(source: CanvasLike);
+    get width(): number;
+    get height(): number;
+    /**
+     * Scale the canvas to new dimensions.
+     * Uses the platform's native drawImage interpolation (bilinear in most runtimes).
+     */
+    resize(options: {
+        width: number;
+        height: number;
+    }): this;
+    /**
+     * Convert to grayscale using BT.601 luma coefficients
+     * (matches OpenCV's COLOR_RGBA2GRAY: 0.299R + 0.587G + 0.114B).
+     *
+     * The result is still RGBA — R, G, and B channels all equal the luma value.
+     * The alpha channel is preserved unchanged.
+     */
+    grayscale(): this;
+    /**
+     * Apply a linear per-pixel transformation: `dst = clamp(alpha * src + beta)`.
+     * Applies independently to R, G, and B channels; alpha channel is unchanged.
+     *
+     * This is the canvas-native equivalent of OpenCV's `Mat.convertTo(dst, rtype, alpha, beta)`,
+     * limited to the pixel-math aspect. `rtype` is not applicable here — canvas ImageData
+     * is always 8-bit RGBA (`Uint8ClampedArray`), so type conversion has no meaning.
+     *
+     * Useful for brightness/contrast adjustment:
+     * - `alpha > 1` increases contrast
+     * - `beta > 0` increases brightness
+     * - `alpha = 0.5, beta = 0` halves contrast
+     */
+    convert(options?: {
+        alpha?: number;
+        beta?: number;
+    }): this;
+    /**
+     * Invert all RGB channels: `dst = 255 - src`.
+     * Alpha channel is preserved unchanged.
+     * Equivalent to OpenCV's `cv.bitwise_not`.
+     */
+    invert(): this;
+    /**
+     * Apply binary threshold: pixels with luma above `thresh` become `maxValue`,
+     * all others become 0.
+     *
+     * Equivalent to OpenCV's `cv.threshold(src, dst, thresh, maxval, THRESH_BINARY)`.
+     * Operates on the luma of each pixel (R channel is used directly when the
+     * image is already grayscale, i.e. R === G === B).
+     *
+     * Note: Otsu's automatic threshold (`THRESH_OTSU`) is not supported
+     * canvas-natively — use a fixed `thresh` value instead.
+     */
+    threshold(options?: {
+        thresh?: number;
+        maxValue?: number;
+    }): this;
+    /**
+     * Add a uniform border around the canvas.
+     * Equivalent to OpenCV's `cv.copyMakeBorder` with `BORDER_CONSTANT`.
+     *
+     * @param options.size Border width in pixels (default 10)
+     * @param options.color CSS color string for the border fill (default "white")
+     */
+    border(options?: {
+        size?: number;
+        color?: string;
+    }): this;
+    /**
+     * Rotate the canvas around its centre (or a custom pivot) while keeping the
+     * original canvas dimensions. Pixels that fall outside the bounds after
+     * rotation are clipped (transparent).
+     *
+     * Positive `angle` rotates counter-clockwise, matching the convention used
+     * by OpenCV's `getRotationMatrix2D`.
+     *
+     * @param options.angle Rotation angle in degrees
+     * @param options.cx    Pivot X (default: canvas centre)
+     * @param options.cy    Pivot Y (default: canvas centre)
+     */
+    rotate(options: {
+        angle: number;
+        cx?: number;
+        cy?: number;
+    }): this;
+    /**
+     * Detect connected regions on a binary (black-and-white) canvas and return
+     * their bounding boxes and pixel areas.
+     *
+     * Uses an 8-connected DFS flood-fill — equivalent to OpenCV's
+     * `findContours` with `RETR_LIST + CHAIN_APPROX_SIMPLE` on a binary image,
+     * returning bounding-box level information.
+     *
+     * Best called after `.grayscale().threshold()` to ensure a clean binary input.
+     *
+     * @param options.foreground  Which pixel tone is the foreground to detect:
+     *                            `"light"` (white regions, default) or `"dark"` (black regions).
+     * @param options.thresh      Luma threshold that separates foreground from background (default 127).
+     *                            For `foreground: "light"`: pixel is foreground when `r > thresh`.
+     *                            For `foreground: "dark"`:  pixel is foreground when `r <= thresh`.
+     *                            **Use `thresh: 0` when working on a resized binary image** — resizing
+     *                            introduces anti-aliased gray border pixels (values 1–127) that the
+     *                            default threshold would miss, matching OpenCV's behaviour of treating
+     *                            any non-zero pixel as contour-adjacent.
+     * @param options.minArea     Ignore regions smaller than this many pixels (default 1).
+     * @param options.maxArea     Ignore regions larger than this many pixels (default unlimited).
+     * @param options.padding     Expand each detected bbox by a fraction of its **height**.
+     *                            Mirrors `extractBoxesFromContours` padding logic:
+     *                            `vertical` and `horizontal` are both applied as
+     *                            `Math.round(bboxHeight × factor)` and clamped to the canvas bounds.
+     *                            Default: no padding.
+     * @param options.scale       Multiply all bbox coordinates by this factor after padding.
+     *                            Use `originalWidth / processedWidth` (i.e. `1 / resizeRatio`)
+     *                            to convert from a resized canvas back to original image coordinates.
+     *                            Default: 1 (no scaling).
+     *
+     * @example
+     * ```ts
+     * // Direct equivalent of extractBoxesFromContours with default padding:
+     * const regions = new CanvasProcessor(binaryCanvas).findRegions({
+     *   foreground: "light",
+     *   minArea: 20,
+     *   padding: { vertical: 0.4, horizontal: 0.6 },
+     *   scale: originalWidth / processedWidth,
+     * });
+     * ```
+     */
+    findRegions(options?: {
+        foreground?: "light" | "dark";
+        thresh?: number;
+        minArea?: number;
+        maxArea?: number;
+        padding?: {
+            vertical?: number;
+            horizontal?: number;
+        };
+        scale?: number;
+    }): DetectedRegion[];
+    /**
+     * Return the current canvas state.
+     */
+    toCanvas(): CanvasLike;
+    /**
+     * 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{_canvas;constructor(source){this._canvas=source}get width(){return this._canvas.width}get height(){return this._canvas.height}resize(options){const{width,height}=options;let dst=getPlatform().createCanvas(width,height);dst.getContext("2d").drawImage(this._canvas,0,0,width,height);this._canvas=dst;return this}grayscale(){const{width,height}=this._canvas;let imageData=this._canvas.getContext("2d").getImageData(0,0,width,height);let d=imageData.data;for(let i=0;i<d.length;i+=4){let luma=Math.round(0.299*d[i]+0.587*d[i+1]+0.114*d[i+2]);d[i]=luma;d[i+1]=luma;d[i+2]=luma}let dst=getPlatform().createCanvas(width,height);dst.getContext("2d").putImageData(imageData,0,0);this._canvas=dst;return this}convert(options={}){const{alpha=1,beta=0}=options;if(alpha===1&&beta===0)return this;const{width,height}=this._canvas;let imageData=this._canvas.getContext("2d").getImageData(0,0,width,height);let d=imageData.data;for(let i=0;i<d.length;i+=4){d[i]=Math.round(d[i]*alpha+beta);d[i+1]=Math.round(d[i+1]*alpha+beta);d[i+2]=Math.round(d[i+2]*alpha+beta)}let dst=getPlatform().createCanvas(width,height);dst.getContext("2d").putImageData(imageData,0,0);this._canvas=dst;return this}invert(){const{width,height}=this._canvas;let imageData=this._canvas.getContext("2d").getImageData(0,0,width,height);let d=imageData.data;for(let i=0;i<d.length;i+=4){d[i]=255-d[i];d[i+1]=255-d[i+1];d[i+2]=255-d[i+2]}let dst=getPlatform().createCanvas(width,height);dst.getContext("2d").putImageData(imageData,0,0);this._canvas=dst;return this}threshold(options={}){const{thresh=127,maxValue=255}=options;const{width,height}=this._canvas;let imageData=this._canvas.getContext("2d").getImageData(0,0,width,height);let d=imageData.data;for(let i=0;i<d.length;i+=4){let luma=d[i]===d[i+1]&&d[i+1]===d[i+2]?d[i]:Math.round(0.299*d[i]+0.587*d[i+1]+0.114*d[i+2]);let val=luma>thresh?maxValue:0;d[i]=val;d[i+1]=val;d[i+2]=val}let dst=getPlatform().createCanvas(width,height);dst.getContext("2d").putImageData(imageData,0,0);this._canvas=dst;return this}border(options={}){const{size=10,color="white"}=options;const{width,height}=this._canvas;let dst=getPlatform().createCanvas(width+size*2,height+size*2);let ctx=dst.getContext("2d");ctx.fillStyle=color;ctx.fillRect(0,0,dst.width,dst.height);ctx.drawImage(this._canvas,size,size);this._canvas=dst;return this}rotate(options){const{angle,cx=this._canvas.width/2,cy=this._canvas.height/2}=options;if(angle===0)return this;const{width,height}=this._canvas;let dst=getPlatform().createCanvas(width,height);let ctx=dst.getContext("2d");ctx.save();ctx.translate(cx,cy);ctx.rotate(-angle*Math.PI/180);ctx.drawImage(this._canvas,-cx,-cy);ctx.restore();this._canvas=dst;return this}findRegions(options={}){const{foreground="light",thresh=127,minArea=1,maxArea=1/0,padding,scale=1}=options;const{width,height}=this._canvas;let data=this._canvas.getContext("2d").getImageData(0,0,width,height).data;let visited=new Uint8Array(width*height);let regions=[];let neighbours=[[-1,-1],[0,-1],[1,-1],[-1,0],[1,0],[-1,1],[0,1],[1,1]];let isForeground=(pixelIdx)=>{let r=data[pixelIdx];return foreground==="light"?r>thresh:r<=thresh};for(let startY=0;startY<height;startY++){for(let startX=0;startX<width;startX++){let startFlat=startY*width+startX;if(visited[startFlat])continue;visited[startFlat]=1;if(!isForeground(startFlat*4))continue;let stack=[startFlat];let minX=startX,maxX=startX;let minY=startY,maxY=startY;let area=0;while(stack.length>0){let flat=stack.pop();area++;let x=flat%width;let y=(flat-x)/width;if(x<minX)minX=x;else if(x>maxX)maxX=x;if(y<minY)minY=y;else if(y>maxY)maxY=y;for(const[dx,dy]of neighbours){let nx=x+dx;let ny=y+dy;if(nx<0||nx>=width||ny<0||ny>=height)continue;let nFlat=ny*width+nx;if(visited[nFlat])continue;visited[nFlat]=1;if(isForeground(nFlat*4))stack.push(nFlat)}}if(area>=minArea&&area<=maxArea){let x0=minX;let y0=minY;let x1=maxX+1;let y1=maxY+1;if(padding){let bboxH=y1-y0;let vPad=Math.round(bboxH*(padding.vertical??0));let hPad=Math.round(bboxH*(padding.horizontal??0));x0=Math.max(0,x0-hPad);y0=Math.max(0,y0-vPad);x1=Math.min(width,x1+hPad);y1=Math.min(height,y1+vPad)}if(scale!==1){x0=Math.max(0,Math.round(x0*scale));y0=Math.max(0,Math.round(y0*scale));x1=Math.round(x1*scale);y1=Math.round(y1*scale)}regions.push({bbox:{x0,y0,x1,y1},area})}}}return regions}toCanvas(){return this._canvas}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, type DetectedRegion } 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, type DetectedRegion } 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, type DetectedRegion } 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, type DetectedRegion } 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.1.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",