ppu-ocv 3.1.0 → 3.1.3

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).
+
+## Table of Contents
 
-## Why use this library?
+- [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)
 
-OpenCV is powerful but can be cumbersome to use directly. This library provides:
+## Why ppu-ocv?
 
-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
+- **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
@@ -296,8 +302,8 @@ regions.sort((a, b) => b.area - a.area); // largest first
 
 **Region detection** (returns data, does not mutate)
 
-| Method        | Options                                          | Description                                                  |
-| ------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| 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. ³
@@ -368,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:
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — setup, commit conventions, quality checks, and PR flow. Also:
 
-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.
+- [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.
 
-### Running Tests
-
-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-processor.d.ts

@@ -45,8 +45,11 @@ export interface DetectedRegion {
  */
 export declare class CanvasProcessor {
     private _canvas;
+    /** Create a processor wrapping the given canvas. */
     constructor(source: CanvasLike);
+    /** Current canvas width in pixels. */
     get width(): number;
+    /** Current canvas height in pixels. */
     get height(): number;
     /**
      * Scale the canvas to new dimensions.

package/canvas-processor.js

@@ -1 +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";
+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)+0.587*(d[i+1]??0)+0.114*(d[i+2]??0));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]??0)*alpha+beta);d[i+1]=Math.round((d[i+1]??0)*alpha+beta);d[i+2]=Math.round((d[i+2]??0)*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]??0);d[i+1]=255-(d[i+1]??0);d[i+2]=255-(d[i+2]??0)}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]??0:Math.round(0.299*(d[i]??0)+0.587*(d[i+1]??0)+0.114*(d[i+2]??0));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]??0;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();if(flat===undefined)break;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

@@ -12,6 +12,7 @@ export declare class CanvasToolkitBase {
     protected static _baseInstance: CanvasToolkitBase | null;
     protected step: number;
     protected constructor();
+    /** Return the singleton instance of {@link CanvasToolkitBase}. */
     static getInstance(): CanvasToolkitBase;
     /**
      * Crop a part of source canvas and return a new canvas of the cropped part

package/canvas-toolkit.base.js

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

package/canvas-toolkit.js

@@ -1 +1 @@
-import{CanvasToolkitBase}from"./canvas-toolkit.base.js";import{createWriteStream,existsSync,mkdirSync,readdirSync,unlinkSync}from"fs";import{join}from"path";export class CanvasToolkit extends CanvasToolkitBase{static _nodeInstance=null;constructor(){super()}static getInstance(){if(!CanvasToolkit._nodeInstance){CanvasToolkit._nodeInstance=new CanvasToolkit}return CanvasToolkit._nodeInstance}saveImage(options){const{canvas,filename,path="out"}=options;let folderPath=join(process.cwd(),path);if(!existsSync(folderPath)){mkdirSync(folderPath,{recursive:true})}let filePath=join(folderPath,`${this.step++}. ${filename}.png`);let out=createWriteStream(filePath);let buffer=canvas.toBuffer("image/png");return new Promise((res,rej)=>{out.write(buffer,(err)=>{if(err){rej(err)}else{res()}})})}clearOutput(path="out"){let folderPath=join(process.cwd(),path);if(existsSync(folderPath)){let files=readdirSync(folderPath);for(let file of files){if(file===".gitignore")continue;let filePath=join(folderPath,file);unlinkSync(filePath)}}}}
+import{CanvasToolkitBase}from"./canvas-toolkit.base.js";import{createWriteStream,existsSync,mkdirSync,readdirSync,unlinkSync}from"fs";import{join}from"path";export class CanvasToolkit extends CanvasToolkitBase{static _nodeInstance=null;constructor(){super()}static getInstance(){if(!CanvasToolkit._nodeInstance){CanvasToolkit._nodeInstance=new CanvasToolkit}return CanvasToolkit._nodeInstance}saveImage(options){const{canvas,filename,path="out"}=options;let folderPath=join(process.cwd(),path);if(!existsSync(folderPath)){mkdirSync(folderPath,{recursive:true})}let filePath=join(folderPath,`${this.step++}. ${filename}.png`);let out=createWriteStream(filePath);if(typeof canvas.toBuffer!=="function")throw new Error("toBuffer not available on this canvas");let buffer=canvas.toBuffer("image/png");return new Promise((res,rej)=>{out.write(buffer,(err)=>{if(err){rej(err)}else{res()}})})}clearOutput(path="out"){let folderPath=join(process.cwd(),path);if(existsSync(folderPath)){let files=readdirSync(folderPath);for(let file of files){if(file===".gitignore")continue;let filePath=join(folderPath,file);unlinkSync(filePath)}}}}

package/contours.d.ts

@@ -1,12 +1,17 @@
 import type { CanvasLike } from "./canvas-factory.js";
 import { cv } from "./cv-provider.js";
 import type { BoundingBox, Points } from "./index.interface.js";
+/** Options for configuring contour detection. */
 export interface ContoursOptions {
     /** The contour retrieval mode. (cv.RETR_...) */
     mode: cv.RetrievalModes;
     /** The contour approximation method. (cv.CHAIN_...) */
     method: cv.ContourApproximationModes;
 }
+/**
+ * Wrapper around OpenCV's `findContours` that provides convenient accessors
+ * for iterating, filtering, and analyzing contours in a binary image.
+ */
 export declare class Contours {
     private contours;
     /** The constructor for the Contours class. It takes an image and options as parameters. */

package/contours.js

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

package/cv-provider.d.ts

@@ -23,23 +23,47 @@ export declare function setCv(instance: CV): void;
  * get BOTH the types (e.g. `cv.Mat`) AND the runtime Proxy object.
  */
 export declare namespace cv {
+    /** OpenCV Mat (matrix / image buffer). */
     type Mat = _cvType.Mat;
+    /** A vector of Mat objects, used for contours. */
     type MatVector = _cvType.MatVector;
+    /** A 2D point `{ x, y }`. */
     type Point = _cvType.Point;
+    /** An axis-aligned rectangle `{ x, y, width, height }`. */
     type Rect = _cvType.Rect;
+    /** A 2D size `{ width, height }`. */
     type Size = _cvType.Size;
+    /** A 4-element scalar value, often used for colors `[b, g, r, a]`. */
     type Scalar = _cvType.Scalar;
+    /** Adaptive thresholding method constants (e.g., `cv.ADAPTIVE_THRESH_GAUSSIAN_C`). */
     type AdaptiveThresholdTypes = _cvType.AdaptiveThresholdTypes;
+    /** Thresholding type constants (e.g., `cv.THRESH_BINARY`). */
     type ThresholdTypes = _cvType.ThresholdTypes;
+    /** Line type constants (e.g., `cv.LINE_8`). */
     type LineTypes = _cvType.LineTypes;
+    /** Contour retrieval mode constants (e.g., `cv.RETR_EXTERNAL`). */
     type RetrievalModes = _cvType.RetrievalModes;
+    /** Contour approximation method constants (e.g., `cv.CHAIN_APPROX_SIMPLE`). */
     type ContourApproximationModes = _cvType.ContourApproximationModes;
+    /** Border type constants (e.g., `cv.BORDER_CONSTANT`). */
     type BorderTypes = _cvType.BorderTypes;
+    /** Interpolation flag constants (e.g., `cv.INTER_LINEAR`). */
     type InterpolationFlags = _cvType.InterpolationFlags;
+    /** Color conversion code constants (e.g., `cv.COLOR_RGBA2GRAY`). */
     type ColorConversionCodes = _cvType.ColorConversionCodes;
+    /** Morphological structuring element shape constants (e.g., `cv.MORPH_RECT`). */
     type MorphShapes = _cvType.MorphShapes;
+    /** Morphological operation type constants (e.g., `cv.MORPH_GRADIENT`). */
     type MorphTypes = _cvType.MorphTypes;
+    /** Integer alias — opencv-js represents `int` as a plain `number`. */
     type int = number;
 }
+/**
+ * Lazy proxy for the OpenCV runtime.
+ * Access any OpenCV constant or constructor (e.g. `cv.Mat`, `cv.RETR_EXTERNAL`)
+ * through this object. The underlying instance is resolved on first access,
+ * so importing this module never throws at module-load time — only when a
+ * property is actually accessed before {@link ImageProcessor.initRuntime} has run.
+ */
 export declare const cv: CV;
 export {};

package/deskew.js

@@ -1 +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";
+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{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{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{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

@@ -5,6 +5,25 @@ type NameWithRequiredOptions = {
     [N in OperationName]: OperationOptions<N> extends RequiredOptions ? N : never;
 }[OperationName];
 type NameWithOptionalOptions = Exclude<OperationName, NameWithRequiredOptions>;
+/**
+ * OpenCV-powered image processing pipeline.
+ *
+ * Wraps a `cv.Mat` and exposes a chainable API of named operations
+ * (grayscale, blur, threshold, etc.).  Each method mutates the internal
+ * state and returns `this`, so operations can be chained fluently.
+ *
+ * Call {@link ImageProcessor.initRuntime} once before creating any instances.
+ *
+ * @example
+ * ```ts
+ * await ImageProcessor.initRuntime();
+ * const result = new ImageProcessor(canvas)
+ *   .grayscale()
+ *   .blur()
+ *   .threshold()
+ *   .toCanvas();
+ * ```
+ */
 export declare class ImageProcessor {
     img: cv.Mat;
     width: number;
@@ -15,11 +34,8 @@ export declare class ImageProcessor {
      */
     constructor(source: CanvasLike | cv.Mat);
     /**
-     * Initialize OpenCV runtime. Must be called before any image processing.
-     *
-     * - **Node.js**: Uses `@techstark/opencv-js` from node_modules (loaded by entry point).
-     * - **Browser with bundler**: Resolves `@techstark/opencv-js` via the bundler.
-     * - **Browser without bundler**: Falls back to loading `@techstark/opencv-js` from npm CDN.
+     * Initialize OpenCV runtime. This is recommended to be called before any
+     * image processing.
      */
     static initRuntime(): Promise<void>;
     /**

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 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(){return new Promise((res)=>{if(cv&&cv.Mat){res()}else{cv["onRuntimeInitialized"]=()=>{res()}}})}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{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}from"./cv-provider.js";import{executeOperation}from"./pipeline/index.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, 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, type DetectedRegion } from "./canvas-processor.js";

package/index.d.ts

@@ -3,9 +3,9 @@ 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, type DetectedRegion } from "./canvas-processor.js";

package/index.interface.d.ts

@@ -1,16 +1,32 @@
+/** A 2D point in canvas pixel coordinates. */
 export interface Coordinate {
+    /** X coordinate in pixels, measured from the left edge. */
     x: number;
+    /** Y coordinate in pixels, measured from the top edge. */
     y: number;
 }
+/** The four corner points of an axis-aligned rectangle, e.g. a contour bounding box. */
 export interface Points {
+    /** Top-left corner. */
     topLeft: Coordinate;
+    /** Top-right corner. */
     topRight: Coordinate;
+    /** Bottom-left corner. */
     bottomLeft: Coordinate;
+    /** Bottom-right corner. */
     bottomRight: Coordinate;
 }
+/**
+ * An axis-aligned bounding box with exclusive `x1` / `y1`.
+ * Width is `x1 - x0`; height is `y1 - y0`.
+ */
 export interface BoundingBox {
+    /** Left edge, inclusive. */
     x0: number;
+    /** Top edge, inclusive. */
     y0: number;
+    /** Right edge, exclusive. */
     x1: number;
+    /** Bottom edge, exclusive. */
     y1: number;
 }

package/index.web.d.ts

@@ -1,10 +1,34 @@
+/**
+ * Web entry point — browsers with OpenCV + DOM canvas.
+ *
+ * Use this when you need the full image-processing pipeline in a browser.
+ * Canvas operations target `HTMLCanvasElement` / `OffscreenCanvas` instead
+ * of `@napi-rs/canvas`. OpenCV is loaded via `ImageProcessor.initRuntime()`
+ * — either from the bundled `@techstark/opencv-js` or from jsDelivr CDN
+ * when no bundler is in play.
+ *
+ * Not suitable for Manifest V3 Chrome extensions or other CSP-restricted
+ * runtimes — OpenCV.js uses Emscripten embind which calls `new Function`.
+ * For those environments, import `ppu-ocv/canvas-web` (no OpenCV).
+ *
+ * @example
+ * ```ts
+ * import { ImageProcessor, CanvasProcessor } from "ppu-ocv/web";
+ *
+ * await ImageProcessor.initRuntime();
+ * const canvas = await CanvasProcessor.prepareCanvas(await response.arrayBuffer());
+ * const result = new ImageProcessor(canvas).grayscale().toCanvas();
+ * ```
+ *
+ * @module
+ */
 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, type DetectedRegion } from "./canvas-processor.js";
 export { Contours } from "./contours.js";

package/operations/adaptive-threshold.d.ts

@@ -1,10 +1,6 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        adaptiveThreshold: AdaptiveThresholdOptions;
-    }
-}
+/** Options for the adaptive threshold operation. */
 export interface AdaptiveThresholdOptions extends PartialOptions {
     /** Upper threshold value (0-255) */
     upper: number;
@@ -17,4 +13,5 @@ export interface AdaptiveThresholdOptions extends PartialOptions {
     /** Constant subtracted from the mean or weighted mean */
     constant: number;
 }
+/** Apply adaptive thresholding to convert a grayscale image to binary. */
 export declare function adaptiveThreshold(img: cv.Mat, options: AdaptiveThresholdOptions): OperationResult;

package/operations/blur.d.ts

@@ -1,14 +1,11 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        blur: BlurOptions;
-    }
-}
+/** Options for the Gaussian blur operation. */
 export interface BlurOptions extends PartialOptions {
     /** Size of the blur [x, y] */
     size: [number, number];
     /** Gaussian kernel standard deviation on x axis */
     sigma: number;
 }
+/** Apply Gaussian blur to reduce noise. */
 export declare function blur(img: cv.Mat, options: BlurOptions): OperationResult;

package/operations/border.d.ts

@@ -1,10 +1,6 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        border: BorderOptions;
-    }
-}
+/** Options for adding a constant-color border around the image. */
 export interface BorderOptions extends PartialOptions {
     /** Size of the border in pixels */
     size: number;
@@ -13,4 +9,5 @@ export interface BorderOptions extends PartialOptions {
     /** Border color in [B, G, R, A] format */
     borderColor: [cv.int, cv.int, cv.int, cv.int];
 }
+/** Add a uniform border around the image using `cv.copyMakeBorder`. */
 export declare function border(img: cv.Mat, options: BorderOptions): OperationResult;

package/operations/canny.d.ts

@@ -1,14 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        canny: CannyOptions;
-    }
-}
+/** Options for the Canny edge-detection operation. */
 export interface CannyOptions extends PartialOptions {
     /** Lower threshold for the hysteresis procedure (0-255) */
     lower: number;
     /** Upper threshold for the hysteresis procedure (0-255) */
     upper: number;
 }
+/** Detect edges using the Canny algorithm. */
 export declare function canny(img: cv.Mat, options: CannyOptions): OperationResult;

package/operations/convert.d.ts

@@ -1,12 +1,9 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        convert: ConvertOptions;
-    }
-}
+/** Options for converting a Mat to a different depth/channel type. */
 export interface ConvertOptions extends RequiredOptions {
     /** Desired matrix type (cv.CV_...) if negative, it will be the same as input */
     rtype: number;
 }
+/** Convert the image matrix to a new type via `Mat.convertTo`. */
 export declare function convert(img: cv.Mat, options: ConvertOptions): OperationResult;

package/operations/dilate.d.ts

@@ -1,14 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        dilate: DilateOptions;
-    }
-}
+/** Options for the morphological dilation operation. */
 export interface DilateOptions extends PartialOptions {
     /** Size of the block [x, y] */
     size: [number, number];
     /** Number of iterations for the dilation operation */
     iter: number;
 }
+/** Dilate the image to expand foreground regions. */
 export declare function dilate(img: cv.Mat, options: DilateOptions): OperationResult;

package/operations/erode.d.ts

@@ -1,14 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        erode: ErodeOptions;
-    }
-}
+/** Options for the morphological erosion operation. */
 export interface ErodeOptions extends PartialOptions {
     /** Size of the block [x, y] */
     size: [number, number];
     /** Number of iterations for the erosion operation */
     iter: number;
 }
+/** Erode the image to shrink foreground regions and remove small noise. */
 export declare function erode(img: cv.Mat, options: ErodeOptions): OperationResult;

package/operations/grayscale.d.ts

@@ -1,10 +1,7 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        grayscale: GrayscaleOptions;
-    }
-}
+/** Options for the grayscale conversion operation (no configurable fields). */
 export interface GrayscaleOptions extends PartialOptions {
 }
-export declare function grayscale(img: cv.Mat, options: GrayscaleOptions): OperationResult;
+/** Convert the image to grayscale using `COLOR_RGBA2GRAY`. */
+export declare function grayscale(img: cv.Mat, _options: GrayscaleOptions): OperationResult;

package/operations/grayscale.js

@@ -1 +1 @@
-import{cv}from"../cv-provider.js";import{registry}from"../pipeline/registry.js";function defaultOptions(){return{}}export function grayscale(img,options){let imgGrayscale=new cv.Mat;cv.cvtColor(img,imgGrayscale,cv.COLOR_RGBA2GRAY);img.delete();return{img:imgGrayscale,width:imgGrayscale.cols,height:imgGrayscale.rows}}registry.register("grayscale",grayscale,defaultOptions);
+import{cv}from"../cv-provider.js";import{registry}from"../pipeline/registry.js";function defaultOptions(){return{}}export function grayscale(img,_options){let imgGrayscale=new cv.Mat;cv.cvtColor(img,imgGrayscale,cv.COLOR_RGBA2GRAY);img.delete();return{img:imgGrayscale,width:imgGrayscale.cols,height:imgGrayscale.rows}}registry.register("grayscale",grayscale,defaultOptions);

package/operations/invert.d.ts

@@ -1,10 +1,7 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        invert: InvertOptions;
-    }
-}
+/** Options for the bitwise-NOT color inversion operation (no configurable fields). */
 export interface InvertOptions extends PartialOptions {
 }
-export declare function invert(img: cv.Mat, options: InvertOptions): OperationResult;
+/** Invert all pixel values using `cv.bitwise_not`. */
+export declare function invert(img: cv.Mat, _options: InvertOptions): OperationResult;

package/operations/invert.js

@@ -1 +1 @@
-import{cv}from"../cv-provider.js";import{registry}from"../pipeline/registry.js";function defaultOptions(){return{}}export function invert(img,options){let imgInvert=new cv.Mat;cv.bitwise_not(img,imgInvert);img.delete();return{img:imgInvert,width:imgInvert.cols,height:imgInvert.rows}}registry.register("invert",invert,defaultOptions);
+import{cv}from"../cv-provider.js";import{registry}from"../pipeline/registry.js";function defaultOptions(){return{}}export function invert(img,_options){let imgInvert=new cv.Mat;cv.bitwise_not(img,imgInvert);img.delete();return{img:imgInvert,width:imgInvert.cols,height:imgInvert.rows}}registry.register("invert",invert,defaultOptions);

package/operations/morphological-gradient.d.ts

@@ -1,12 +1,9 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        morphologicalGradient: MorphologicalGradientOptions;
-    }
-}
+/** Options for the morphological gradient operation. */
 export interface MorphologicalGradientOptions extends PartialOptions {
     /** Kernel size for the morphological gradient operation [x, y] */
     size: [number, number];
 }
+/** Apply morphological gradient to highlight edges (dilation minus erosion). */
 export declare function morphologicalGradient(img: cv.Mat, options: MorphologicalGradientOptions): OperationResult;

package/operations/resize.d.ts

@@ -1,14 +1,11 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        resize: ResizeOptions;
-    }
-}
+/** Options for resizing the image to exact pixel dimensions. */
 export interface ResizeOptions extends RequiredOptions {
     /** Width of the resized image */
     width: number;
     /** Height of the resized image */
     height: number;
 }
+/** Resize the image to the given width and height. */
 export declare function resize(img: cv.Mat, options: ResizeOptions): OperationResult;

package/operations/rotate.d.ts

@@ -1,14 +1,11 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        rotate: RotateOptions;
-    }
-}
+/** Options for rotating the image around a pivot point. */
 export interface RotateOptions extends RequiredOptions {
     /** Angle of rotation in degrees (positive for counter-clockwise) */
     angle: number;
     /** Optional center of rotation. Defaults to the image center. */
     center?: cv.Point;
 }
+/** Rotate the image by the given angle around its centre (or a custom pivot). */
 export declare function rotate(img: cv.Mat, options: RotateOptions): OperationResult;

package/operations/threshold.d.ts

@@ -1,10 +1,6 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
-declare module "../pipeline/types" {
-    interface RegisteredOperations {
-        threshold: ThresholdOptions;
-    }
-}
+/** Options for the global threshold operation. */
 export interface ThresholdOptions extends PartialOptions {
     /** Lower threshold value (0-255) */
     lower: number;
@@ -13,4 +9,5 @@ export interface ThresholdOptions extends PartialOptions {
     /** Type of thresholding (cv.THRESH_...) */
     type: cv.ThresholdTypes;
 }
+/** Apply a global threshold to convert a grayscale image to binary. */
 export declare function threshold(img: cv.Mat, options: ThresholdOptions): OperationResult;

package/operations/warp.d.ts

@@ -1,11 +1,7 @@
 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;
-    }
-}
+/** Options for the perspective warp (four-point transform) operation. */
 export interface WarpOptions extends RequiredOptions {
     /** Four points of the source image containing x and y point in
      * topLeft, topRight, bottomLeft and BottomRight.
@@ -15,4 +11,5 @@ export interface WarpOptions extends RequiredOptions {
     /** A destination canvas bounding box for cropping the original canvas */
     bbox: BoundingBox;
 }
+/** Apply a perspective warp using four source/destination corner points. */
 export declare function warp(img: cv.Mat, options: WarpOptions): OperationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "3.1.0",
+  "version": "3.1.3",
   "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,30 @@
   },
   "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 --parallel=$(ls tests/*.test.ts | wc -l | tr -d ' ')",
+    "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",
+    "canvas": "^3.2.3",
+    "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,13 +1,39 @@
-import { cv } from "../cv-provider.js";
+import type { cv } from "../cv-provider.js";
 import type { OperationFunction, OperationName, OperationOptions, OperationResult } from "./index.js";
+/**
+ * Registry that maps operation names to their implementation functions and
+ * default-option factories. Operation files call {@link OperationRegistry.register}
+ * at module-load time to make themselves available to {@link executeOperation}.
+ */
 export declare class OperationRegistry {
     private operations;
     private defaultOptions;
+    /**
+     * Register a named operation.
+     * @param name Unique operation name (must match a key in {@link RegisteredOperations}).
+     * @param operation The function that performs the operation.
+     * @param defaultOptions Optional factory returning default option values.
+     */
     register<Name extends OperationName>(name: Name, operation: OperationFunction<OperationOptions<Name>>, defaultOptions?: () => Partial<OperationOptions<Name>>): void;
+    /** Look up the implementation for an operation by name. */
     getOperation(name: string): OperationFunction<any> | undefined;
+    /** Return the default-options factory for an operation, or an empty object if none was registered. */
     getDefaultOptionsGenerator(name: string): any;
+    /** Return `true` if an operation with the given name has been registered. */
     hasOperation(name: string): boolean;
+    /** Return the names of all registered operations. */
     getOperationNames(): OperationName[];
 }
+/** Singleton registry populated by each `src/operations/*.ts` module at load time. */
 export declare const registry: OperationRegistry;
+/**
+ * Look up and execute a registered operation, merging caller-supplied options
+ * with the operation's defaults.
+ *
+ * @param operationName Name of the registered operation.
+ * @param img Input OpenCV Mat. The Mat is consumed (deleted) by the operation.
+ * @param options Partial options to merge with the operation's defaults.
+ * @returns The operation result containing the transformed Mat and its dimensions.
+ * @throws {Error} If no operation with `operationName` is registered.
+ */
 export declare function executeOperation<Name extends OperationName>(operationName: Name, img: cv.Mat, options?: Partial<OperationOptions<Name>>): OperationResult;

package/pipeline/types.d.ts

@@ -1,25 +1,76 @@
-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";
+/** The output produced by every pipeline operation: the transformed Mat plus its dimensions. */
 export interface OperationResult {
+    /** Resulting OpenCV Mat after the operation. The caller is responsible for deleting it. */
     img: cv.Mat;
+    /** Width of the resulting image in pixels. */
     width: number;
+    /** Height of the resulting image in pixels. */
     height: number;
 }
 declare const RequiredBrand: unique symbol;
+/**
+ * Marker interface for operation options that have no usable defaults and
+ * must be supplied by the caller. Operation option types that extend this
+ * cannot be omitted when calling {@link ImageProcessor.execute}.
+ */
 export interface RequiredOptions {
     [RequiredBrand]?: never;
 }
 declare const PartialBrand: unique symbol;
+/**
+ * Marker interface for operation options that have sensible defaults.
+ * Operation option types that extend this may be omitted or partially supplied.
+ */
 export interface PartialOptions {
     [PartialBrand]?: never;
 }
+/** Signature every registered operation function must conform to. */
 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;
 }
+/** Union of all registered operation names. Extend {@link RegisteredOperations} to add new ones. */
 export type OperationName = keyof RegisteredOperations;
+/** Resolve the options type for a given operation name. */
 export type OperationOptions<N extends OperationName> = RegisteredOperations[N];
 export {};