ppu-ocv 3.0.0 → 3.1.2

package/README.md

@@ -1,10 +1,10 @@
 # ppu-ocv
 
-A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.
+[![NPM](https://img.shields.io/npm/dw/ppu-ocv)](https://www.npmjs.com/package/ppu-ocv) [![JSR](https://jsr.io/badges/@snowfluke/ppu-ocv)](https://jsr.io/@snowfluke/ppu-ocv)
 
-![ppu-ocv pipeline demo](https://raw.githubusercontent.com/PT-Perkasa-Pilar-Utama/ppu-ocv/refs/heads/main/assets/ppu-ocv-demo.jpg)
+A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing. Decoupled canvas utilities run anywhere — Node, Bun, browsers, browser extensions, and service workers — with or without OpenCV.
 
-Image manipulation as easy as:
+![ppu-ocv pipeline demo](https://raw.githubusercontent.com/PT-Perkasa-Pilar-Utama/ppu-ocv/refs/heads/main/assets/ppu-ocv-demo.jpg)
 
 ```ts
 const processor = new ImageProcessor(canvas);
@@ -17,23 +17,33 @@ const result = processor
   .dilate({ size: [20, 20], iter: 5 })
   .toCanvas();
 
-// Memory cleanup
 processor.destroy();
 ```
 
-This work is based on https://github.com/TechStark/opencv-js.
+Based on [TechStark/opencv-js](https://github.com/TechStark/opencv-js).
 
-## Why use this library?
+## Table of Contents
 
-OpenCV is powerful but can be cumbersome to use directly. This library provides:
+- [Why ppu-ocv?](#why-ppu-ocv)
+- [Installation](#installation)
+- [Usage (Node.js / Bun)](#usage-nodejs--bun)
+- [Canvas-only Usage (no OpenCV)](#canvas-only-usage-no-opencv)
+- [Web / Browser Support](#web--browser-support)
+- [Built-in Pipeline Operations](#built-in-pipeline-operations)
+- [Extending Operations](#extending-operations)
+- [Class Documentation](#class-documentation)
+- [Migrating from v2](#migrating-from-v2)
+- [Contributing](#contributing)
+- [License](#license)
 
-1. **Simplified API**: Transform complex OpenCV calls into simple chainable methods
-2. **Reduced Boilerplate**: No need to manage memory, conversions, or dimensions manually
-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
+## Why ppu-ocv?
+
+- **Simplified API** — chainable methods that hide OpenCV's verbose Mat allocation
+- **No memory management** — automatic Mat lifecycle within the pipeline
+- **Type-safe** — full TypeScript inference for operations and options
+- **Extensible** — register custom operations with `registry.register(...)` without forking
+- **Cross-platform** — same API in Node, Bun, browsers, and constrained runtimes
+- **Loosely coupled** — canvas utilities work standalone; OpenCV is only loaded when actually needed
 
 ## Installation
 
@@ -125,9 +135,7 @@ const buffer = await CanvasProcessor.prepareBuffer(cropped);
 import { CanvasProcessor, CanvasToolkit } from "ppu-ocv/canvas-web";
 
 const response = await fetch("/image.jpg");
-const canvas = await CanvasProcessor.prepareCanvas(
-  await response.arrayBuffer(),
-);
+const canvas = await CanvasProcessor.prepareCanvas(await response.arrayBuffer());
 ```
 
 ## Web / Browser Support
@@ -171,9 +179,7 @@ processor.destroy();
   await ImageProcessor.initRuntime();
 
   const response = await fetch("/my-image.jpg");
-  const canvas = await CanvasProcessor.prepareCanvas(
-    await response.arrayBuffer(),
-  );
+  const canvas = await CanvasProcessor.prepareCanvas(await response.arrayBuffer());
 
   const processor = new ImageProcessor(canvas);
   processor
@@ -251,13 +257,65 @@ See: [How to extend ppu-ocv operations](./docs/how-to-extend-ppu-ocv-operations.
 
 #### `CanvasProcessor`
 
-Canvas I/O utilities with **no OpenCV dependency**. Available from all entry points including `ppu-ocv/canvas` and `ppu-ocv/canvas-web`.
+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`
 
 Requires OpenCV. Available from `ppu-ocv` and `ppu-ocv/web`.
@@ -316,37 +374,24 @@ A collection of utility functions for analyzing image properties (requires OpenC
 
 ## Contributing
 
-Contributions are welcome! If you would like to contribute, please follow these steps:
-
-1. **Fork the Repository:** Create your own fork of the project.
-2. **Create a Feature Branch:** Use a descriptive branch name for your changes.
-3. **Implement Changes:** Make your modifications, add tests, and ensure everything passes.
-4. **Submit a Pull Request:** Open a pull request to discuss your changes and get feedback.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — setup, commit conventions, quality checks, and PR flow. Also:
 
-### Running Tests
+- [Code of Conduct](./CODE_OF_CONDUCT.md) — community standards.
+- [Security policy](./SECURITY.md) — how to report vulnerabilities privately.
+- [Issue tracker](https://github.com/PT-Perkasa-Pilar-Utama/ppu-ocv/issues) — bug reports, feature requests, and docs gaps each have a template.
 
-This project uses Bun for testing. To run the tests locally, execute:
+Quick local commands:
 
 ```bash
-bun test
+bun install
+bun test           # run unit tests
+bun run fmt        # check formatting
+bun run lint       # check lint
+bun run type-check # tsgo --noEmit
+bun task build     # emit ./lib
+bun task bench     # micro-bench the operations registry
 ```
 
-Ensure that all tests pass before submitting your pull request.
-
-## Scripts
-
-Recommended development environment is in a Linux-based environment.
-
-Library template: https://github.com/aquapi/lib-template
-
-### [Build](./scripts/build.ts)
-
-Emit `.js` and `.d.ts` files to [`lib`](./lib).
-
-### [Publish](./scripts/publish.ts)
-
-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:

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-processor.d.ts

@@ -1,10 +1,192 @@
+import type { BoundingBox } from "./index.interface.js";
 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.
+ * 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.

package/canvas-processor.js

@@ -1 +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";
+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/index.canvas-web.d.ts

@@ -1,6 +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 type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { webPlatform } from "./platform/web.js";
 export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
-export { CanvasProcessor } from "./canvas-processor.js";
+export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.canvas.d.ts

@@ -2,7 +2,7 @@ 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 type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
-export { CanvasProcessor } from "./canvas-processor.js";
+export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.d.ts

@@ -3,12 +3,12 @@ export { cv };
 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 { executeOperation, OperationRegistry, registry, } from "./pipeline/index.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 type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
-export { CanvasProcessor } from "./canvas-processor.js";
+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";

package/index.web.d.ts

@@ -1,12 +1,12 @@
 import { cv } from "./cv-provider.js";
 export { cv };
 export { getPlatform, setPlatform } from "./canvas-factory.js";
-export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { webPlatform } from "./platform/web.js";
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
-export { executeOperation, OperationRegistry, registry, } from "./pipeline/index.js";
+export { executeOperation, OperationRegistry, registry } from "./pipeline/index.js";
 export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
-export { CanvasProcessor } from "./canvas-processor.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";

package/operations/adaptive-threshold.d.ts

@@ -1,10 +1,5 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        adaptiveThreshold: AdaptiveThresholdOptions;
-    }
-}
 export interface AdaptiveThresholdOptions extends PartialOptions {
     /** Upper threshold value (0-255) */
     upper: number;

package/operations/blur.d.ts

@@ -1,10 +1,5 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        blur: BlurOptions;
-    }
-}
 export interface BlurOptions extends PartialOptions {
     /** Size of the blur [x, y] */
     size: [number, number];

package/operations/border.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        border: BorderOptions;
-    }
-}
 export interface BorderOptions extends PartialOptions {
     /** Size of the border in pixels */
     size: number;

package/operations/canny.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        canny: CannyOptions;
-    }
-}
 export interface CannyOptions extends PartialOptions {
     /** Lower threshold for the hysteresis procedure (0-255) */
     lower: number;

package/operations/convert.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        convert: ConvertOptions;
-    }
-}
 export interface ConvertOptions extends RequiredOptions {
     /** Desired matrix type (cv.CV_...) if negative, it will be the same as input */
     rtype: number;

package/operations/dilate.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        dilate: DilateOptions;
-    }
-}
 export interface DilateOptions extends PartialOptions {
     /** Size of the block [x, y] */
     size: [number, number];

package/operations/erode.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        erode: ErodeOptions;
-    }
-}
 export interface ErodeOptions extends PartialOptions {
     /** Size of the block [x, y] */
     size: [number, number];

package/operations/grayscale.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        grayscale: GrayscaleOptions;
-    }
-}
 export interface GrayscaleOptions extends PartialOptions {
 }
 export declare function grayscale(img: cv.Mat, options: GrayscaleOptions): OperationResult;

package/operations/invert.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        invert: InvertOptions;
-    }
-}
 export interface InvertOptions extends PartialOptions {
 }
 export declare function invert(img: cv.Mat, options: InvertOptions): OperationResult;

package/operations/morphological-gradient.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        morphologicalGradient: MorphologicalGradientOptions;
-    }
-}
 export interface MorphologicalGradientOptions extends PartialOptions {
     /** Kernel size for the morphological gradient operation [x, y] */
     size: [number, number];

package/operations/resize.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        resize: ResizeOptions;
-    }
-}
 export interface ResizeOptions extends RequiredOptions {
     /** Width of the resized image */
     width: number;

package/operations/rotate.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        rotate: RotateOptions;
-    }
-}
 export interface RotateOptions extends RequiredOptions {
     /** Angle of rotation in degrees (positive for counter-clockwise) */
     angle: number;

package/operations/threshold.d.ts

@@ -1,10 +1,5 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        threshold: ThresholdOptions;
-    }
-}
 export interface ThresholdOptions extends PartialOptions {
     /** Lower threshold value (0-255) */
     lower: number;

package/operations/warp.d.ts

@@ -1,11 +1,6 @@
 import { cv } from "../cv-provider.js";
 import type { BoundingBox, Points } from "../index.interface.js";
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        warp: WarpOptions;
-    }
-}
 export interface WarpOptions extends RequiredOptions {
     /** Four points of the source image containing x and y point in
      * topLeft, topRight, bottomLeft and BottomRight.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "3.0.0",
+  "version": "3.1.2",
   "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",
@@ -45,21 +45,29 @@
   },
   "scripts": {
     "task": "bun scripts/task.ts",
+    "build": "bun task build",
     "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",
-    "demo": "bunx -y serve -l 4567 ."
+    "type-check": "bunx tsgo --noEmit",
+    "test": "bun test",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt --check",
+    "fmt:fix": "oxfmt .",
+    "demo": "bunx -y serve -l 4567 .",
+    "prepare": "husky"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "latest",
     "@types/bun": "latest",
     "@types/uglify-js": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20260513.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.0.0",
     "mitata": "latest",
-    "prettier": "^3.8.1",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
     "tsx": "latest",
     "typescript": "latest",
-    "typescript-eslint": "latest",
     "uglify-js": ">=2.4.24"
   },
   "repository": {

package/pipeline/registry.d.ts

@@ -1,4 +1,4 @@
-import { cv } from "../cv-provider.js";
+import type { cv } from "../cv-provider.js";
 import type { OperationFunction, OperationName, OperationOptions, OperationResult } from "./index.js";
 export declare class OperationRegistry {
     private operations;

package/pipeline/types.d.ts

@@ -1,4 +1,18 @@
-import { cv } from "../cv-provider.js";
+import type { cv } from "../cv-provider.js";
+import type { AdaptiveThresholdOptions } from "../operations/adaptive-threshold.js";
+import type { BlurOptions } from "../operations/blur.js";
+import type { BorderOptions } from "../operations/border.js";
+import type { CannyOptions } from "../operations/canny.js";
+import type { ConvertOptions } from "../operations/convert.js";
+import type { DilateOptions } from "../operations/dilate.js";
+import type { ErodeOptions } from "../operations/erode.js";
+import type { GrayscaleOptions } from "../operations/grayscale.js";
+import type { InvertOptions } from "../operations/invert.js";
+import type { MorphologicalGradientOptions } from "../operations/morphological-gradient.js";
+import type { ResizeOptions } from "../operations/resize.js";
+import type { RotateOptions } from "../operations/rotate.js";
+import type { ThresholdOptions } from "../operations/threshold.js";
+import type { WarpOptions } from "../operations/warp.js";
 export interface OperationResult {
     img: cv.Mat;
     width: number;
@@ -14,11 +28,32 @@ export interface PartialOptions {
 }
 export type OperationFunction<T> = (img: cv.Mat, options: T) => OperationResult;
 /**
- * @description
- * Central registry mapping operation names to their specific option types.
- * Operation modules MUST augment this interface.
+ * Central registry mapping operation names to their option types. Each entry
+ * is the options type exported by the corresponding `src/operations/*.ts`
+ * file. Adding a new operation requires three changes: create the file,
+ * export the Options type, and add the entry below.
+ *
+ * Previously this used `declare module` augmentation so each operation file
+ * could register itself. JSR rejects that pattern because it modifies global
+ * types, so the registry is now explicit. Consumers can still extend this
+ * interface from their own code via `declare module "ppu-ocv"` — that's why
+ * it stays an interface rather than a type alias.
  */
 export interface RegisteredOperations {
+    adaptiveThreshold: AdaptiveThresholdOptions;
+    blur: BlurOptions;
+    border: BorderOptions;
+    canny: CannyOptions;
+    convert: ConvertOptions;
+    dilate: DilateOptions;
+    erode: ErodeOptions;
+    grayscale: GrayscaleOptions;
+    invert: InvertOptions;
+    morphologicalGradient: MorphologicalGradientOptions;
+    resize: ResizeOptions;
+    rotate: RotateOptions;
+    threshold: ThresholdOptions;
+    warp: WarpOptions;
 }
 export type OperationName = keyof RegisteredOperations;
 export type OperationOptions<N extends OperationName> = RegisteredOperations[N];