ppu-ocv 3.1.2 → 3.1.4

package/canvas-factory.d.ts

@@ -2,44 +2,71 @@
  * Platform abstraction layer for canvas operations.
  * Allows ppu-ocv to work with both @napi-rs/canvas (Node) and browser canvas APIs.
  */
-/** Structural type satisfied by both @napi-rs/canvas Canvas and HTMLCanvasElement/OffscreenCanvas */
+/** Structural type satisfied by both @napi-rs/canvas Canvas and HTMLCanvasElement/OffscreenCanvas. */
 export interface CanvasLike {
+    /** Canvas width in pixels. */
     width: number;
+    /** Canvas height in pixels. */
     height: number;
+    /** Return a 2D rendering context for drawing on the canvas. */
     getContext(contextId: "2d"): any;
+    /** Serialize the canvas to a binary buffer (Node-side `@napi-rs/canvas`). Absent on browser canvases. */
     toBuffer?: (...args: any[]) => Buffer;
+    /** Serialize the canvas to a data-URL string (browser canvases). Absent on Node-side `@napi-rs/canvas`. */
     toDataURL?: (...args: any[]) => string;
 }
-/** Structural type for 2D rendering context */
+/** Structural type for 2D rendering context, matching the cross-runtime subset used by ppu-ocv. */
 export interface Context2DLike {
+    /** The canvas this context is bound to. */
     canvas: any;
+    /** Draw an image, canvas, or bitmap onto the context. Signature follows the standard Canvas2D `drawImage`. */
     drawImage(...args: any[]): void;
+    /** Read raw RGBA pixel data from a rectangular region of the canvas. */
     getImageData(sx: number, sy: number, sw: number, sh: number): {
         data: Uint8ClampedArray;
         width: number;
         height: number;
     };
+    /** Write raw RGBA pixel data back to the canvas at `(dx, dy)`. */
     putImageData(imageData: any, dx: number, dy: number): void;
+    /** Allocate a blank `ImageData` of the given size. */
     createImageData(width: number, height: number): any;
+    /** Start a new path for stroke/fill commands. */
     beginPath(): void;
+    /** Close the current sub-path by connecting the last point to the first. */
     closePath(): void;
+    /** Move the path cursor to `(x, y)` without drawing. */
     moveTo(x: number, y: number): void;
+    /** Draw a straight line from the current path point to `(x, y)`. */
     lineTo(x: number, y: number): void;
+    /** Stroke the current path with the current `strokeStyle` and `lineWidth`. */
     stroke(): void;
+    /** Stroke an axis-aligned rectangle outline. */
     strokeRect(x: number, y: number, w: number, h: number): void;
+    /** Color, gradient, or pattern used by `stroke` and `strokeRect`. */
     strokeStyle: string | CanvasGradient | CanvasPattern;
+    /** Width in pixels of the line drawn by `stroke` / `strokeRect`. */
     lineWidth: number;
+    /** Color, gradient, or pattern used by `fill` and `fillRect`. */
     fillStyle: string | CanvasGradient | CanvasPattern;
+    /** Fill an axis-aligned rectangle with the current `fillStyle`. */
     fillRect(x: number, y: number, w: number, h: number): void;
+    /** Save the current drawing state (transform, styles) onto the state stack. */
     save(): void;
+    /** Restore the most recently saved drawing state. */
     restore(): void;
+    /** Translate the coordinate system by `(x, y)`. */
     translate(x: number, y: number): void;
+    /** Rotate the coordinate system clockwise by `angle` radians. */
     rotate(angle: number): void;
 }
-/** Platform-specific canvas operations */
+/** Platform-specific canvas operations. Each runtime entry point registers an implementation via {@link setPlatform}. */
 export interface CanvasPlatform {
+    /** Create a blank canvas of the given width and height. */
     createCanvas(width: number, height: number): CanvasLike;
+    /** Decode an image from a buffer or URL and draw it onto a fresh canvas. */
     loadImage(source: ArrayBuffer | string): Promise<CanvasLike>;
+    /** Type guard for "is this value a canvas of this platform?". */
     isCanvas(value: unknown): value is CanvasLike;
 }
 /** Register the platform-specific canvas implementation */

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

@@ -1,7 +1,8 @@
 import type { BoundingBox } from "./index.interface.js";
 import type { CanvasLike, Context2DLike } from "./canvas-factory.js";
-/** Structural interface for contour-like objects with 32-bit signed integer point data */
+/** Structural interface for contour-like objects with 32-bit signed integer point data. */
 export interface ContourLike {
+    /** Flat `[x0, y0, x1, y1, ...]` point array. Matches `cv.Mat.data32S` for contour Mats. */
     data32S: Int32Array | number[];
 }
 /**
@@ -12,6 +13,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.d.ts

@@ -7,6 +7,7 @@ import { CanvasToolkitBase } from "./canvas-toolkit.base.js";
 export declare class CanvasToolkit extends CanvasToolkitBase {
     private static _nodeInstance;
     protected constructor();
+    /** Return the singleton instance of {@link CanvasToolkit}. */
     static getInstance(): CanvasToolkit;
     /**
      * Save a canvas to an image file

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

@@ -18,28 +18,54 @@ type CV = typeof _cvType;
  */
 export declare function setCv(instance: CV): void;
 /**
- * TypeScript Declaration Merging:
- * By exporting both a `namespace cv` and a `const cv`, consumers importing `{ cv }`
- * get BOTH the types (e.g. `cv.Mat`) AND the runtime Proxy object.
+ * Type-side companion to the {@link cv} runtime proxy.
+ *
+ * Re-exports the OpenCV.js type aliases (Mat, Rect, Size, enum constants…) under
+ * the `cv.` namespace, so consumers importing `{ cv }` get the types AND the
+ * runtime Proxy object via TypeScript's declaration-merging rules.
  */
 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.d.ts

@@ -38,6 +38,10 @@ export interface DeskewOptions {
 export declare class DeskewService {
     private readonly verbose;
     private readonly minimumAreaThreshold;
+    /**
+     * Create a DeskewService.
+     * @param options - Configuration. See {@link DeskewOptions}.
+     */
     constructor(options?: DeskewOptions);
     private log;
     /**

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,9 +5,31 @@ 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 {
+    /** Underlying OpenCV Mat. Each operation deletes the previous Mat and replaces this reference. */
     img: cv.Mat;
+    /** Current image width in pixels, kept in sync with `img.cols`. */
     width: number;
+    /** Current image height in pixels, kept in sync with `img.rows`. */
     height: number;
     /**
      * Create an ImageProcessor instance from a Canvas or cv.Mat
@@ -15,11 +37,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.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,3 +1,27 @@
+/**
+ * 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";

package/operations/adaptive-threshold.d.ts

@@ -1,5 +1,6 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
+/** Options for the adaptive threshold operation. */
 export interface AdaptiveThresholdOptions extends PartialOptions {
     /** Upper threshold value (0-255) */
     upper: number;
@@ -12,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,9 +1,11 @@
 import { cv } from "../cv-provider.js";
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
+/** 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,5 +1,6 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** Options for adding a constant-color border around the image. */
 export interface BorderOptions extends PartialOptions {
     /** Size of the border in pixels */
     size: number;
@@ -8,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,9 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,7 +1,9 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,9 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,9 +1,11 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,5 +1,7 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,5 +1,7 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,7 +1,9 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,9 +1,11 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,9 +1,11 @@
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** 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,5 +1,6 @@
 import type { OperationResult, PartialOptions } from "../pipeline/types.js";
 import { cv } from "../cv-provider.js";
+/** Options for the global threshold operation. */
 export interface ThresholdOptions extends PartialOptions {
     /** Lower threshold value (0-255) */
     lower: number;
@@ -8,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,6 +1,7 @@
 import { cv } from "../cv-provider.js";
 import type { BoundingBox, Points } from "../index.interface.js";
 import type { OperationResult, RequiredOptions } from "../pipeline/types.js";
+/** 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.
@@ -10,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.2",
+  "version": "3.1.4",
   "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",
@@ -49,7 +49,7 @@
     "build:test": "bun task build && bun test",
     "build:publish": "bun task build && bun task report-size && bun task publish",
     "type-check": "bunx tsgo --noEmit",
-    "test": "bun test",
+    "test": "bun test --parallel=$(ls tests/*.test.ts | wc -l | tr -d ' ')",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt --check",
@@ -61,6 +61,7 @@
     "@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",

package/pipeline/registry.d.ts

@@ -1,13 +1,39 @@
 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

@@ -13,19 +13,33 @@ 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;
 /**
  * Central registry mapping operation names to their option types. Each entry
@@ -40,21 +54,37 @@ export type OperationFunction<T> = (img: cv.Mat, options: T) => OperationResult;
  * it stays an interface rather than a type alias.
  */
 export interface RegisteredOperations {
+    /** Adaptive (windowed) thresholding. See {@link AdaptiveThresholdOptions}. */
     adaptiveThreshold: AdaptiveThresholdOptions;
+    /** Gaussian blur. See {@link BlurOptions}. */
     blur: BlurOptions;
+    /** Constant-color border around the image. See {@link BorderOptions}. */
     border: BorderOptions;
+    /** Canny edge detection. See {@link CannyOptions}. */
     canny: CannyOptions;
+    /** Convert Mat depth/channel type. See {@link ConvertOptions}. */
     convert: ConvertOptions;
+    /** Morphological dilation. See {@link DilateOptions}. */
     dilate: DilateOptions;
+    /** Morphological erosion. See {@link ErodeOptions}. */
     erode: ErodeOptions;
+    /** Convert to grayscale via `COLOR_RGBA2GRAY`. See {@link GrayscaleOptions}. */
     grayscale: GrayscaleOptions;
+    /** Bitwise-NOT color inversion. See {@link InvertOptions}. */
     invert: InvertOptions;
+    /** Morphological gradient (dilation minus erosion). See {@link MorphologicalGradientOptions}. */
     morphologicalGradient: MorphologicalGradientOptions;
+    /** Resize to absolute pixel dimensions. See {@link ResizeOptions}. */
     resize: ResizeOptions;
+    /** Affine rotation around a pivot point. See {@link RotateOptions}. */
     rotate: RotateOptions;
+    /** Global threshold (including Otsu). See {@link ThresholdOptions}. */
     threshold: ThresholdOptions;
+    /** Four-point perspective warp. See {@link WarpOptions}. */
     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 {};