ppu-ocv 3.0.0 → 3.1.0

package/README.md

@@ -251,13 +251,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`.

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

@@ -3,4 +3,4 @@ export { getPlatform, setPlatform } from "./canvas-factory.js";
 export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
 export { webPlatform } from "./platform/web.js";
 export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
-export { CanvasProcessor } from "./canvas-processor.js";
+export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.canvas.d.ts

@@ -5,4 +5,4 @@ export { getPlatform, setPlatform } from "./canvas-factory.js";
 export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
 export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
-export { CanvasProcessor } from "./canvas-processor.js";
+export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.d.ts

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

@@ -6,7 +6,7 @@ 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, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "3.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",