ppu-doc-correction 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# ppu-doc-correction
+
+A lightweight, type-safe document image correction library for Node.js, Bun, and browsers. Provides three **independent**, lazy-loading correction services powered by PaddlePaddle ONNX models:
+
+1. **`DocOrientService`** — document orientation classification (0/90/180/270 degrees)
+2. **`TextUnwarpService`** — geometric document unwarping (UVDoc model)
+3. **`TextOrientService`** — text line orientation classification (0/180 degrees)
+
+Each service is fully self-contained: it handles model downloading, caching, ONNX session management, and cleanup independently. Models are lazily loaded on first use -- only the model you need is downloaded.
+
+## Installation
+
+```bash
+npm install ppu-doc-correction
+yarn add ppu-doc-correction
+bun add ppu-doc-correction
+```
+
+## Usage
+
+### Document Orientation
+
+```ts
+import { DocOrientService } from "ppu-doc-correction";
+
+const service = new DocOrientService({
+  debugging: { verbose: true },
+});
+
+const result = await service.run(imageBuffer);
+console.log(result.orientation); // 0 | 90 | 180 | 270
+console.log(result.scores);     // [0.82, 0.06, 0.03, 0.09]
+
+await service.destroy();
+```
+
+### Text Image Unwarping
+
+```ts
+import { TextUnwarpService } from "ppu-doc-correction";
+
+const service = new TextUnwarpService();
+
+const result = await service.run(warpedImageBuffer);
+// result.correctedImage is the unwarped ArrayBuffer
+
+await service.destroy();
+```
+
+### Text Line Orientation
+
+```ts
+import { TextOrientService } from "ppu-doc-correction";
+
+const service = new TextOrientService();
+
+const result = await service.run(textLineBuffer);
+console.log(result.orientation); // 0 | 180
+
+await service.destroy();
+```
+
+### Custom Model Path
+
+```ts
+const service = new DocOrientService({
+  model: "./models/PP-LCNet_x1_0_doc_ori.onnx",
+});
+```
+
+You can also pass an `ArrayBuffer` directly:
+
+```ts
+const modelBuffer = await Bun.file("./models/PP-LCNet_x1_0_doc_ori.onnx").arrayBuffer();
+const service = new DocOrientService({ model: modelBuffer });
+```
+
+### Debug Mode
+
+When `debug: true` is set, corrected images are saved to the `debugFolder` (default: `out/`):
+
+```ts
+const service = new DocOrientService({
+  debugging: { debug: true, verbose: true, debugFolder: "out" },
+});
+```
+
+### Clearing Model Cache
+
+```ts
+const service = new DocOrientService();
+service.clearModelCache();
+```
+
+Or via CLI:
+
+```bash
+bun clear-cache
+```
+
+## Web / Browser Support
+
+Import from `ppu-doc-correction/web`:
+
+```ts
+import { DocOrientService } from "ppu-doc-correction/web";
+
+const service = new DocOrientService();
+const result = await service.run(canvas);
+console.log(result.orientation);
+await service.destroy();
+```
+
+See the interactive demo: [Web Demo](https://pt-perkasa-pilar-utama.github.io/ppu-doc-correction/)
+
+## Models
+
+| Model | Input Shape | Output Shape | Purpose |
+| :--- | :--- | :--- | :--- |
+| PP-LCNet_x1_0_doc_ori | [1, 3, 224, 224] | [1, 4] | Document orientation (4 classes) |
+| UVDoc | [1, 3, H, W] | [1, 3, H, W] | Text image unwarping |
+| PP-LCNet_x0_25_textline_ori | [1, 3, 80, 160] | [1, 2] | Text line orientation (2 classes) |
+
+Models are sourced from [ppu-paddle-ocr-models](https://github.com/PT-Perkasa-Pilar-Utama/ppu-paddle-ocr-models).
+
+### Alternative Text Orientation Model
+
+A larger, more accurate text orientation model:
+
+```ts
+import { TextOrientService, MODEL_BASE_URL } from "ppu-doc-correction";
+
+const service = new TextOrientService({
+  model: `${MODEL_BASE_URL}/correction/PP-LCNet_x1_0_textline_ori.onnx`,
+});
+```
+
+## Configuration
+
+### Per-Service Options
+
+Each service accepts its own options object:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `model` | `string \| ArrayBuffer` | Model path, URL, or buffer. Omit for default. |
+| `debugging` | `DebuggingOptions` | Logging and image dump behavior |
+| `session` | `SessionOptions` | ONNX Runtime session configuration |
+| `docOrient` / `textUnwarp` / `textOrient` | preprocessing options | Service-specific preprocessing |
+
+### `DebuggingOptions`
+
+| Property | Type | Default | Description |
+| :--- | :---: | :---: | :--- |
+| `verbose` | `boolean` | `false` | Enable detailed console logs |
+| `debug` | `boolean` | `false` | Save corrected images to disk |
+| `debugFolder` | `string` | `"out"` | Output directory for debug images |
+
+### `SessionOptions`
+
+| Property | Type | Default | Description |
+| :--- | :---: | :---: | :--- |
+| `executionProviders` | `string[]` | `['cpu']` | ONNX execution providers |
+| `graphOptimizationLevel` | `string` | `'all'` | Graph optimization level |
+| `enableCpuMemArena` | `boolean` | `true` | CPU memory arena |
+| `enableMemPattern` | `boolean` | `true` | Memory pattern optimization |
+
+## Benchmark
+
+```bash
+bun task bench index
+```
+
+## Contributing
+
+1. **Fork** the repository
+2. **Create** a feature branch
+3. **Implement** changes and add tests
+4. **Submit** a pull request
+
+### Running Tests
+
+```bash
+bun test
+bun build:test
+bun lint
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Scripts
+
+### [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.
+
+### [Bench](./scripts/bench.ts)
+
+```bash
+bun task bench index     # Run bench/index.bench.ts
+bun task bench --node    # Run in Node.js
+```

package/constants.d.ts

@@ -0,0 +1,15 @@
+import type { DebuggingOptions, DocOrientOptions, SessionOptions, TextOrientOptions, TextUnwarpOptions } from "./interface.js";
+/** Base URL for downloading default correction model files from GitHub. */
+export declare const MODEL_BASE_URL = "https://media.githubusercontent.com/media/PT-Perkasa-Pilar-Utama/ppu-paddle-ocr-models/main";
+/** Default model file URLs for each correction model. */
+export declare const MODEL_URLS: Record<string, string>;
+/** Default debugging options -- logging and image dumps disabled. */
+export declare const DEFAULT_DEBUGGING_OPTIONS: DebuggingOptions;
+/** Default ONNX Runtime session options. */
+export declare const DEFAULT_SESSION_OPTIONS: SessionOptions;
+/** Default document orientation classification options. */
+export declare const DEFAULT_DOC_ORIENT_OPTIONS: DocOrientOptions;
+/** Default text image unwarping options. */
+export declare const DEFAULT_TEXT_UNWARP_OPTIONS: TextUnwarpOptions;
+/** Default text line orientation classification options. */
+export declare const DEFAULT_TEXT_ORIENT_OPTIONS: TextOrientOptions;

package/constants.js

@@ -0,0 +1 @@
+export let MODEL_BASE_URL="https://media.githubusercontent.com/media/PT-Perkasa-Pilar-Utama/ppu-paddle-ocr-models/main";export let MODEL_URLS={docOrient:`${MODEL_BASE_URL}/correction/PP-LCNet_x1_0_doc_ori.onnx`,textUnwarp:`${MODEL_BASE_URL}/correction/UVDoc.onnx`,textOrient:`${MODEL_BASE_URL}/correction/PP-LCNet_x0_25_textline_ori.onnx`};export let DEFAULT_DEBUGGING_OPTIONS={verbose:false,debug:false,debugFolder:"out"};export let DEFAULT_SESSION_OPTIONS={executionProviders:["cpu"],graphOptimizationLevel:"all",enableCpuMemArena:true,enableMemPattern:true,executionMode:"sequential",interOpNumThreads:0,intraOpNumThreads:0};export let DEFAULT_DOC_ORIENT_OPTIONS={mean:[0.485,0.456,0.406],stdDeviation:[0.229,0.224,0.225]};export let DEFAULT_TEXT_UNWARP_OPTIONS={preserveDimensions:true};export let DEFAULT_TEXT_ORIENT_OPTIONS={mean:[0.485,0.456,0.406],stdDeviation:[0.229,0.224,0.225]};

package/core/base-doc-orient.service.d.ts

@@ -0,0 +1,45 @@
+import type { InferenceSession } from "onnxruntime-common";
+import type { DebuggingOptions, DocOrientOptions, DocOrientResult } from "../interface.js";
+import type { CoreCanvas, PlatformProvider } from "./platform.js";
+/**
+ * Platform-agnostic service for classifying document image orientation.
+ *
+ * Determines whether a document image is rotated 0, 90, 180, or 270 degrees
+ * and produces a corrected image.
+ */
+export declare class BaseDocOrientService {
+    protected readonly options: DocOrientOptions;
+    protected readonly debugging: DebuggingOptions;
+    protected readonly session: InferenceSession;
+    protected readonly platform: PlatformProvider;
+    constructor(platform: PlatformProvider, session: InferenceSession, options?: Partial<DocOrientOptions>, debugging?: Partial<DebuggingOptions>);
+    protected log(message: string): void;
+    /**
+     * Classify the orientation of a document image and return the corrected result.
+     * @param image - Source image as ArrayBuffer or platform-specific Canvas.
+     */
+    run(image: ArrayBuffer | CoreCanvas): Promise<DocOrientResult>;
+    /**
+     * Preprocess the image into a normalized CHW float tensor.
+     *
+     * Uses letterbox resize: scales the image so the longer side fits 224px,
+     * preserves aspect ratio, and centers on a zero-padded 224x224 canvas.
+     */
+    private preprocess;
+    /**
+     * Run ONNX inference and return softmax scores.
+     */
+    private runInference;
+    /**
+     * Compute softmax over raw logits.
+     */
+    private softmax;
+    /**
+     * Determine orientation from softmax scores.
+     */
+    private getOrientation;
+    /**
+     * Rotate the canvas to correct orientation.
+     */
+    private applyRotation;
+}

package/core/base-doc-orient.service.js

@@ -0,0 +1 @@
+export class BaseDocOrientService{options;debugging;session;platform;constructor(platform,session,options={},debugging={}){this.platform=platform;this.session=session;this.options={...DEFAULT_DOC_ORIENT_OPTIONS,...options};this.debugging={...DEFAULT_DEBUGGING_OPTIONS,...debugging}}log(message){if(this.debugging.verbose){console.log(`[DocOrientService] ${message}`)}}async run(image){this.log("Starting document orientation classification");let canvas=this.platform.isCanvas(image)?image:await CanvasProcessor.prepareCanvas(image);let tensor=this.preprocess(canvas);let scores=await this.runInference(tensor);let orientation=this.getOrientation(scores);this.log(`Detected orientation: ${orientation} degrees`);let correctedCanvas=this.applyRotation(canvas,orientation);let correctedImage=await CanvasProcessor.prepareBuffer(correctedCanvas);if(this.debugging.debug&&this.debugging.debugFolder){await this.platform.saveDebugImage(correctedCanvas,"doc-orient-corrected",this.debugging.debugFolder);this.log(`Debug image saved to: ${this.debugging.debugFolder}/doc-orient-corrected`)}return{orientation,scores,correctedImage}}preprocess(canvas){const{width:srcW,height:srcH}=canvas;let scale=Math.min(INPUT_WIDTH/srcW,INPUT_HEIGHT/srcH);let resizedW=Math.round(srcW*scale);let resizedH=Math.round(srcH*scale);let offsetX=Math.floor((INPUT_WIDTH-resizedW)/2);let offsetY=Math.floor((INPUT_HEIGHT-resizedH)/2);let resized=new CanvasProcessor(canvas).resize({width:resizedW,height:resizedH}).toCanvas();let resizedCtx=resized.getContext("2d");let imageData=resizedCtx.getImageData(0,0,resizedW,resizedH);let rgbaData=imageData.data;let tensor=new Float32Array(NUM_CHANNELS*INPUT_HEIGHT*INPUT_WIDTH);const{mean,stdDeviation}=this.options;for(let h=0;h<resizedH;h++){for(let w=0;w<resizedW;w++){let rgbaIdx=(h*resizedW+w)*4;let tensorBaseIdx=(h+offsetY)*INPUT_WIDTH+(w+offsetX);for(let c=0;c<NUM_CHANNELS;c++){let pixelValue=rgbaData[rgbaIdx+c]/255;let normalizedValue=(pixelValue-mean[c])/stdDeviation[c];tensor[c*INPUT_HEIGHT*INPUT_WIDTH+tensorBaseIdx]=normalizedValue}}}this.log(`Preprocessed: ${srcW}x${srcH} -> ${resizedW}x${resizedH} (centered on ${INPUT_WIDTH}x${INPUT_HEIGHT})`);return tensor}async runInference(tensor){let inputTensor;try{this.log("Running inference...");inputTensor=new this.platform.ort.Tensor("float32",tensor,[1,NUM_CHANNELS,INPUT_HEIGHT,INPUT_WIDTH]);let feeds={x:inputTensor};let results=await this.session.run(feeds);let outputName=this.session.outputNames[0]||"fetch_name_0";let outputTensor=results[outputName];if(!outputTensor){throw new Error(`Output tensor '${outputName}' not found in results`)}let rawScores=outputTensor.data;let scores=this.softmax(rawScores);this.log(`Scores: [${scores.map((s)=>s.toFixed(4)).join(", ")}]`);return scores}finally{inputTensor?.dispose()}}softmax(logits){let maxLogit=Math.max(...logits);let exps=Array.from(logits,(v)=>Math.exp(v-maxLogit));let sumExp=exps.reduce((a,b)=>a+b,0);return exps.map((e)=>e/sumExp)}getOrientation(scores){let maxIdx=0;let maxScore=scores[0];for(let i=1;i<scores.length;i++){if(scores[i]>maxScore){maxScore=scores[i];maxIdx=i}}return ORIENTATIONS[maxIdx]}applyRotation(canvas,orientation){if(orientation===0){return canvas}const{width,height}=canvas;let swapDimensions=orientation===90||orientation===270;let outWidth=swapDimensions?height:width;let outHeight=swapDimensions?width:height;let rotated=this.platform.createCanvas(outWidth,outHeight);let ctx=rotated.getContext("2d");ctx.translate(outWidth/2,outHeight/2);ctx.rotate(-orientation*Math.PI/180);ctx.drawImage(canvas,-width/2,-height/2);return rotated}}import{CanvasProcessor}from"ppu-ocv/canvas";import{DEFAULT_DEBUGGING_OPTIONS,DEFAULT_DOC_ORIENT_OPTIONS}from"../constants.js";let INPUT_WIDTH=224;let INPUT_HEIGHT=224;let NUM_CHANNELS=3;let ORIENTATIONS=[0,90,180,270];

package/core/base-text-orient.service.d.ts

@@ -0,0 +1,49 @@
+import type { InferenceSession } from "onnxruntime-common";
+import type { DebuggingOptions, TextOrientOptions, TextOrientResult } from "../interface.js";
+import type { CoreCanvas, PlatformProvider } from "./platform.js";
+/**
+ * Platform-agnostic service for classifying text line orientation.
+ *
+ * Determines whether a text line image is upright (0 degrees) or
+ * upside-down (180 degrees) and produces a corrected image.
+ */
+export declare class BaseTextOrientService {
+    protected readonly options: TextOrientOptions;
+    protected readonly debugging: DebuggingOptions;
+    protected readonly session: InferenceSession;
+    protected readonly platform: PlatformProvider;
+    constructor(platform: PlatformProvider, session: InferenceSession, options?: Partial<TextOrientOptions>, debugging?: Partial<DebuggingOptions>);
+    protected log(message: string): void;
+    /**
+     * Classify the orientation of a text line image and return the corrected result.
+     * @param image - Source image as ArrayBuffer or platform-specific Canvas.
+     */
+    run(image: ArrayBuffer | CoreCanvas): Promise<TextOrientResult>;
+    /**
+     * Preprocess the image into a normalized CHW float tensor.
+     *
+     * For landscape images (width >= height): scales height to INPUT_HEIGHT,
+     * preserves aspect ratio, and zero-pads the remaining width.
+     *
+     * For portrait images (height > width): scales width to INPUT_WIDTH,
+     * preserves aspect ratio, and center-crops the height to INPUT_HEIGHT.
+     * This avoids squishing a tall image into a tiny strip.
+     */
+    private preprocess;
+    /**
+     * Run ONNX inference and return softmax scores.
+     */
+    private runInference;
+    /**
+     * Compute softmax over raw logits.
+     */
+    private softmax;
+    /**
+     * Determine orientation from softmax scores.
+     */
+    private getOrientation;
+    /**
+     * Rotate the canvas 180 degrees if needed.
+     */
+    private applyRotation;
+}

package/core/base-text-orient.service.js

@@ -0,0 +1 @@
+export class BaseTextOrientService{options;debugging;session;platform;constructor(platform,session,options={},debugging={}){this.platform=platform;this.session=session;this.options={...DEFAULT_TEXT_ORIENT_OPTIONS,...options};this.debugging={...DEFAULT_DEBUGGING_OPTIONS,...debugging}}log(message){if(this.debugging.verbose){console.log(`[TextOrientService] ${message}`)}}async run(image){this.log("Starting text line orientation classification");let canvas=this.platform.isCanvas(image)?image:await CanvasProcessor.prepareCanvas(image);let tensor=this.preprocess(canvas);let scores=await this.runInference(tensor);let orientation=this.getOrientation(scores);this.log(`Detected text orientation: ${orientation} degrees`);let correctedCanvas=this.applyRotation(canvas,orientation);let correctedImage=await CanvasProcessor.prepareBuffer(correctedCanvas);if(this.debugging.debug&&this.debugging.debugFolder){await this.platform.saveDebugImage(correctedCanvas,"text-orient-corrected",this.debugging.debugFolder);this.log(`Debug image saved to: ${this.debugging.debugFolder}/text-orient-corrected`)}return{orientation,scores,correctedImage}}preprocess(canvas){const{width:srcW,height:srcH}=canvas;let resizedW;let resizedH;let cropOffsetY=0;if(srcW>=srcH){let ratio=srcW/srcH;resizedW=Math.min(Math.ceil(INPUT_HEIGHT*ratio),INPUT_WIDTH);resizedH=INPUT_HEIGHT}else{let ratio=srcH/srcW;resizedW=INPUT_WIDTH;resizedH=Math.ceil(INPUT_WIDTH*ratio);cropOffsetY=Math.max(0,Math.floor((resizedH-INPUT_HEIGHT)/2))}let resized=new CanvasProcessor(canvas).resize({width:resizedW,height:resizedH}).toCanvas();let ctx=resized.getContext("2d");let readH=Math.min(resizedH-cropOffsetY,INPUT_HEIGHT);let imageData=ctx.getImageData(0,cropOffsetY,resizedW,readH);let rgbaData=imageData.data;let tensor=new Float32Array(NUM_CHANNELS*INPUT_HEIGHT*INPUT_WIDTH);const{mean,stdDeviation}=this.options;let fillW=Math.min(resizedW,INPUT_WIDTH);for(let h=0;h<readH;h++){for(let w=0;w<fillW;w++){let rgbaIdx=(h*resizedW+w)*4;let tensorBaseIdx=h*INPUT_WIDTH+w;for(let c=0;c<NUM_CHANNELS;c++){let pixelValue=rgbaData[rgbaIdx+c]/255;let normalizedValue=(pixelValue-mean[c])/stdDeviation[c];tensor[c*INPUT_HEIGHT*INPUT_WIDTH+tensorBaseIdx]=normalizedValue}}}this.log(`Preprocessed: ${srcW}x${srcH} -> ${resizedW}x${resizedH}`+(cropOffsetY>0?` (center-cropped to ${INPUT_WIDTH}x${INPUT_HEIGHT})`:` (padded to ${INPUT_WIDTH}x${INPUT_HEIGHT})`));return tensor}async runInference(tensor){let inputTensor;try{this.log("Running inference...");inputTensor=new this.platform.ort.Tensor("float32",tensor,[1,NUM_CHANNELS,INPUT_HEIGHT,INPUT_WIDTH]);let feeds={x:inputTensor};let results=await this.session.run(feeds);let outputName=this.session.outputNames[0]||"fetch_name_0";let outputTensor=results[outputName];if(!outputTensor){throw new Error(`Output tensor '${outputName}' not found in results`)}let rawScores=outputTensor.data;let scores=this.softmax(rawScores);this.log(`Scores: [${scores.map((s)=>s.toFixed(4)).join(", ")}]`);return scores}finally{inputTensor?.dispose()}}softmax(logits){let maxLogit=Math.max(...logits);let exps=Array.from(logits,(v)=>Math.exp(v-maxLogit));let sumExp=exps.reduce((a,b)=>a+b,0);return exps.map((e)=>e/sumExp)}getOrientation(scores){return scores[0]>=scores[1]?ORIENTATIONS[0]:ORIENTATIONS[1]}applyRotation(canvas,orientation){if(orientation===0){return canvas}const{width,height}=canvas;let rotated=this.platform.createCanvas(width,height);let ctx=rotated.getContext("2d");ctx.translate(width/2,height/2);ctx.rotate(Math.PI);ctx.drawImage(canvas,-width/2,-height/2);return rotated}}import{CanvasProcessor}from"ppu-ocv/canvas";import{DEFAULT_DEBUGGING_OPTIONS,DEFAULT_TEXT_ORIENT_OPTIONS}from"../constants.js";let INPUT_WIDTH=160;let INPUT_HEIGHT=80;let NUM_CHANNELS=3;let ORIENTATIONS=[0,180];

package/core/base-text-unwarp.service.d.ts

@@ -0,0 +1,34 @@
+import type { InferenceSession } from "onnxruntime-common";
+import type { DebuggingOptions, TextUnwarpOptions, TextUnwarpResult } from "../interface.js";
+import type { CoreCanvas, PlatformProvider } from "./platform.js";
+/**
+ * Platform-agnostic service for removing warping and distortion from document images.
+ *
+ * Uses the UVDoc model to perform geometric correction, transforming
+ * warped document photos into flat, readable images.
+ */
+export declare class BaseTextUnwarpService {
+    protected readonly options: TextUnwarpOptions;
+    protected readonly debugging: DebuggingOptions;
+    protected readonly session: InferenceSession;
+    protected readonly platform: PlatformProvider;
+    constructor(platform: PlatformProvider, session: InferenceSession, options?: Partial<TextUnwarpOptions>, debugging?: Partial<DebuggingOptions>);
+    protected log(message: string): void;
+    /**
+     * Unwarp a distorted document image.
+     * @param image - Source image as ArrayBuffer or platform-specific Canvas.
+     */
+    run(image: ArrayBuffer | CoreCanvas): Promise<TextUnwarpResult>;
+    /**
+     * Normalize image to [0,1] float32 and convert HWC to CHW layout.
+     */
+    private preprocess;
+    /**
+     * Run UVDoc ONNX inference.
+     */
+    private runInference;
+    /**
+     * Convert CHW output tensor back to a canvas image.
+     */
+    private postprocess;
+}

package/core/base-text-unwarp.service.js

@@ -0,0 +1 @@
+export class BaseTextUnwarpService{options;debugging;session;platform;constructor(platform,session,options={},debugging={}){this.platform=platform;this.session=session;this.options={...DEFAULT_TEXT_UNWARP_OPTIONS,...options};this.debugging={...DEFAULT_DEBUGGING_OPTIONS,...debugging}}log(message){if(this.debugging.verbose){console.log(`[TextUnwarpService] ${message}`)}}async run(image){this.log("Starting text image unwarping");let canvas=this.platform.isCanvas(image)?image:await CanvasProcessor.prepareCanvas(image);let originalWidth=canvas.width;let originalHeight=canvas.height;let tensor=this.preprocess(canvas);let outputData=await this.runInference(tensor,canvas.width,canvas.height);let correctedCanvas=this.postprocess(outputData.data,outputData.width,outputData.height);let finalCanvas=correctedCanvas;if(this.options.preserveDimensions&&(correctedCanvas.width!==originalWidth||correctedCanvas.height!==originalHeight)){finalCanvas=new CanvasProcessor(correctedCanvas).resize({width:originalWidth,height:originalHeight}).toCanvas()}let correctedImage=await CanvasProcessor.prepareBuffer(finalCanvas);if(this.debugging.debug&&this.debugging.debugFolder){await this.platform.saveDebugImage(finalCanvas,"text-unwarp-corrected",this.debugging.debugFolder);this.log(`Debug image saved to: ${this.debugging.debugFolder}/text-unwarp-corrected`)}this.log(`Unwarping complete: ${originalWidth}x${originalHeight} -> ${finalCanvas.width}x${finalCanvas.height}`);return{correctedImage}}preprocess(canvas){const{width,height}=canvas;let ctx=canvas.getContext("2d");let imageData=ctx.getImageData(0,0,width,height);let rgbaData=imageData.data;let tensor=new Float32Array(NUM_CHANNELS*height*width);for(let h=0;h<height;h++){for(let w=0;w<width;w++){let rgbaIdx=(h*width+w)*4;let tensorBaseIdx=h*width+w;for(let c=0;c<NUM_CHANNELS;c++){tensor[c*height*width+tensorBaseIdx]=rgbaData[rgbaIdx+c]/255}}}this.log(`Preprocessed: ${width}x${height}, tensor size: ${tensor.length}`);return tensor}async runInference(tensor,width,height){let inputTensor;try{this.log(`Running inference with input shape: [1, ${NUM_CHANNELS}, ${height}, ${width}]`);inputTensor=new this.platform.ort.Tensor("float32",tensor,[1,NUM_CHANNELS,height,width]);let feeds={image:inputTensor};let results=await this.session.run(feeds);let outputName=this.session.outputNames[0]||"fetch_name_0";let outputTensor=results[outputName];if(!outputTensor){throw new Error(`Output tensor '${outputName}' not found in results`)}let dims=outputTensor.dims;let outHeight=dims[2];let outWidth=dims[3];this.log(`Inference complete, output shape: [${dims.join(", ")}]`);return{data:outputTensor.data,width:outWidth,height:outHeight}}finally{inputTensor?.dispose()}}postprocess(data,width,height){let canvas=this.platform.createCanvas(width,height);let ctx=canvas.getContext("2d");let imageData=ctx.createImageData(width,height);let pixels=imageData.data;for(let h=0;h<height;h++){for(let w=0;w<width;w++){let pixelIdx=(h*width+w)*4;let tensorBaseIdx=h*width+w;for(let c=0;c<NUM_CHANNELS;c++){let value=data[c*height*width+tensorBaseIdx];pixels[pixelIdx+c]=Math.round(Math.min(1,Math.max(0,value))*255)}pixels[pixelIdx+3]=255}}ctx.putImageData(imageData,0,0);return canvas}}import{CanvasProcessor}from"ppu-ocv/canvas";import{DEFAULT_DEBUGGING_OPTIONS,DEFAULT_TEXT_UNWARP_OPTIONS}from"../constants.js";let NUM_CHANNELS=3;

package/core/platform.d.ts

@@ -0,0 +1,27 @@
+import type { InferenceSession, Tensor } from "onnxruntime-common";
+import type { Canvas } from "ppu-ocv";
+import type { CanvasLike } from "ppu-ocv/web";
+export type CoreCanvas = Canvas | CanvasLike;
+/**
+ * A generic abstraction mapping specifically to pure runtime-level APIs
+ * (like ort/onnxruntime, canvas APIs, fetching mechanisms, etc).
+ *
+ * This injects the platform-specific dependencies into the shared Core logic.
+ */
+export interface PlatformProvider<TCanvas = CoreCanvas> {
+    /** The specific pathing delimiter used on this platform (ie '/' vs '\') */
+    pathSeparator: string;
+    /** Platform-specific ONNX Runtime namespace (`onnxruntime-node` vs `onnxruntime-web`) */
+    ort: {
+        Tensor: typeof Tensor;
+        InferenceSession: typeof InferenceSession;
+    };
+    /** Platform-specific canvas constructor (`createCanvas` vs `getPlatform().createCanvas`) */
+    createCanvas: (width: number, height: number) => TCanvas;
+    /** Type guard determining if an object is a recognized Canvas API implementation */
+    isCanvas: (image: unknown) => image is TCanvas;
+    /** Resolves resources asynchronously via local FileSystem (`fs`) or HTTP (`fetch`) based on the environment */
+    loadResource: (source: string | ArrayBuffer | undefined, defaultUrl: string) => Promise<ArrayBuffer>;
+    /** Optionally dump a given Canvas representation directly onto the disk (No-Op on Web context) */
+    saveDebugImage: (canvas: TCanvas, filename: string, path: string) => Promise<void>;
+}

package/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module
+ *
+ * Blazing-fast document correction for Node.js and Bun.
+ *
+ * Three independent, lazy-loading services for document image correction:
+ * - `DocOrientService` — document orientation classification (0/90/180/270)
+ * - `TextUnwarpService` — geometric document unwarping (UVDoc)
+ * - `TextOrientService` — text line orientation classification (0/180)
+ *
+ * @example
+ * ```ts
+ * import { DocOrientService } from "ppu-doc-correction";
+ *
+ * const service = new DocOrientService();
+ * const result = await service.run(imageBuffer);
+ * console.log(result.orientation); // 0, 90, 180, 270
+ * await service.destroy();
+ * ```
+ */
+export { DocOrientService } from "./processor/doc-orient.service.js";
+export { TextOrientService } from "./processor/text-orient.service.js";
+export { TextUnwarpService } from "./processor/text-unwarp.service.js";
+export type { DebuggingOptions, DocOrientation, DocOrientOptions, DocOrientResult, DocOrientServiceOptions, SessionOptions, TextOrientation, TextOrientOptions, TextOrientResult, TextOrientServiceOptions, TextUnwarpOptions, TextUnwarpResult, TextUnwarpServiceOptions, } from "./interface.js";
+export { DEFAULT_DEBUGGING_OPTIONS, DEFAULT_DOC_ORIENT_OPTIONS, DEFAULT_SESSION_OPTIONS, DEFAULT_TEXT_ORIENT_OPTIONS, DEFAULT_TEXT_UNWARP_OPTIONS, MODEL_BASE_URL, MODEL_URLS, } from "./constants.js";

package/index.js

@@ -0,0 +1 @@
+export{DocOrientService}from"./processor/doc-orient.service.js";export{TextOrientService}from"./processor/text-orient.service.js";export{TextUnwarpService}from"./processor/text-unwarp.service.js";export{DEFAULT_DEBUGGING_OPTIONS,DEFAULT_DOC_ORIENT_OPTIONS,DEFAULT_SESSION_OPTIONS,DEFAULT_TEXT_ORIENT_OPTIONS,DEFAULT_TEXT_UNWARP_OPTIONS,MODEL_BASE_URL,MODEL_URLS}from"./constants.js";

package/interface.d.ts

@@ -0,0 +1,178 @@
+/**
+ * ONNX Runtime session configuration options.
+ */
+export interface SessionOptions {
+    /**
+     * Execution providers to use for inference (e.g., 'cpu', 'cuda').
+     * @default ['cpu']
+     */
+    executionProviders?: string[];
+    /**
+     * Graph optimization level for ONNX Runtime.
+     * @default 'all'
+     */
+    graphOptimizationLevel?: "disabled" | "basic" | "extended" | "layout" | "all";
+    /**
+     * Enable CPU memory arena for better memory management.
+     * @default true
+     */
+    enableCpuMemArena?: boolean;
+    /**
+     * Enable memory pattern optimization.
+     * @default true
+     */
+    enableMemPattern?: boolean;
+    /**
+     * Execution mode for the session.
+     * @default 'sequential'
+     */
+    executionMode?: "sequential" | "parallel";
+    /**
+     * Number of inter-op threads. 0 lets ONNX decide.
+     * @default 0
+     */
+    interOpNumThreads?: number;
+    /**
+     * Number of intra-op threads. 0 lets ONNX decide.
+     * @default 0
+     */
+    intraOpNumThreads?: number;
+}
+/**
+ * Controls verbose output and image dumps for debugging.
+ */
+export interface DebuggingOptions {
+    /**
+     * Enable detailed logging of each processing step.
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Save intermediate image data to disk for inspection.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Directory where debug images will be written.
+     * Relative to the current working directory.
+     * @default "out"
+     */
+    debugFolder?: string;
+}
+/**
+ * Document image orientation (0, 90, 180, or 270 degrees).
+ */
+export type DocOrientation = 0 | 90 | 180 | 270;
+/**
+ * Text line orientation (0 or 180 degrees).
+ */
+export type TextOrientation = 0 | 180;
+/**
+ * Preprocessing options for document orientation classification.
+ */
+export interface DocOrientOptions {
+    /**
+     * Per-channel mean values for input normalization [R, G, B].
+     * @default [0.485, 0.456, 0.406]
+     */
+    mean?: [number, number, number];
+    /**
+     * Per-channel standard deviation values for input normalization [R, G, B].
+     * @default [0.229, 0.224, 0.225]
+     */
+    stdDeviation?: [number, number, number];
+}
+/**
+ * Preprocessing options for text image unwarping.
+ */
+export interface TextUnwarpOptions {
+    /**
+     * Whether to preserve the original image dimensions in the output.
+     * When true, the output is resized to match the input dimensions.
+     * @default true
+     */
+    preserveDimensions?: boolean;
+}
+/**
+ * Preprocessing options for text line orientation classification.
+ */
+export interface TextOrientOptions {
+    /**
+     * Per-channel mean values for input normalization [R, G, B].
+     * @default [0.485, 0.456, 0.406]
+     */
+    mean?: [number, number, number];
+    /**
+     * Per-channel standard deviation values for input normalization [R, G, B].
+     * @default [0.229, 0.224, 0.225]
+     */
+    stdDeviation?: [number, number, number];
+}
+/**
+ * Result of document orientation classification.
+ */
+export interface DocOrientResult {
+    /** Detected orientation angle in degrees. */
+    orientation: DocOrientation;
+    /** Confidence scores for each orientation class [0, 90, 180, 270]. */
+    scores: [number, number, number, number];
+    /** Corrected image as an ArrayBuffer (PNG encoded). */
+    correctedImage: ArrayBuffer;
+}
+/**
+ * Result of text image unwarping.
+ */
+export interface TextUnwarpResult {
+    /** Unwarped image as an ArrayBuffer (PNG encoded). */
+    correctedImage: ArrayBuffer;
+}
+/**
+ * Result of text line orientation classification.
+ */
+export interface TextOrientResult {
+    /** Detected orientation angle in degrees. */
+    orientation: TextOrientation;
+    /** Confidence scores for each orientation class [0, 180]. */
+    scores: [number, number];
+    /** Corrected image as an ArrayBuffer (PNG encoded). */
+    correctedImage: ArrayBuffer;
+}
+/**
+ * Options for the DocOrientService.
+ */
+export interface DocOrientServiceOptions {
+    /** ONNX model source: file path, URL, or ArrayBuffer. Omit for default. */
+    model?: string | ArrayBuffer;
+    /** Preprocessing options. */
+    docOrient?: DocOrientOptions;
+    /** Debugging options. */
+    debugging?: DebuggingOptions;
+    /** ONNX Runtime session options. */
+    session?: SessionOptions;
+}
+/**
+ * Options for the TextUnwarpService.
+ */
+export interface TextUnwarpServiceOptions {
+    /** ONNX model source: file path, URL, or ArrayBuffer. Omit for default. */
+    model?: string | ArrayBuffer;
+    /** Preprocessing options. */
+    textUnwarp?: TextUnwarpOptions;
+    /** Debugging options. */
+    debugging?: DebuggingOptions;
+    /** ONNX Runtime session options. */
+    session?: SessionOptions;
+}
+/**
+ * Options for the TextOrientService.
+ */
+export interface TextOrientServiceOptions {
+    /** ONNX model source: file path, URL, or ArrayBuffer. Omit for default. */
+    model?: string | ArrayBuffer;
+    /** Preprocessing options. */
+    textOrient?: TextOrientOptions;
+    /** Debugging options. */
+    debugging?: DebuggingOptions;
+    /** ONNX Runtime session options. */
+    session?: SessionOptions;
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "ppu-doc-correction",
+  "version": "1.0.0",
+  "description": "Lightweight, type-safe document image correction for Node.js, Bun, and browsers. Provides orientation classification, text unwarping (UVDoc), and text line orientation correction.",
+  "keywords": [
+    "bun-compatible",
+    "computer-vision",
+    "document-ai",
+    "document-correction",
+    "document-processing",
+    "image-processing",
+    "image-unwarping",
+    "onnx",
+    "onnxruntime",
+    "orientation-detection",
+    "paddle-paddle",
+    "paddlepaddle",
+    "uvdoc"
+  ],
+  "author": "snowfluke",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./web": {
+      "types": "./web/index.d.ts",
+      "default": "./web/index.js"
+    }
+  },
+  "scripts": {
+    "task": "bun scripts/task.ts",
+    "build:test": "bun task build && bun test",
+    "build:publish": "bun task build && bun task report-size && bun task publish",
+    "clear-cache": "bun scripts/clear-cache.ts",
+    "lint": "prettier --check ./src",
+    "lint:fix": "prettier --write ./src",
+    "demo": "bunx -y serve -l 3456 ."
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "latest",
+    "@types/bun": "latest",
+    "@types/uglify-js": "latest",
+    "canvas": "^3.2.1",
+    "mitata": "latest",
+    "onnxruntime-node": "^1.24.2",
+    "onnxruntime-web": "^1.24.2",
+    "prettier": "^3.8.1",
+    "tsx": "latest",
+    "typescript": "latest",
+    "typescript-eslint": "latest",
+    "uglify-js": ">=2.4.24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PT-Perkasa-Pilar-Utama/ppu-doc-correction.git"
+  },
+  "dependencies": {
+    "ppu-ocv": "^3.1.0"
+  },
+  "peerDependencies": {
+    "onnxruntime-node": "^1.24.2",
+    "onnxruntime-web": "^1.24.2"
+  },
+  "peerDependenciesMeta": {
+    "onnxruntime-node": {
+      "optional": true
+    },
+    "onnxruntime-web": {
+      "optional": true
+    }
+  }
+}

package/processor/doc-orient.service.d.ts

@@ -0,0 +1,35 @@
+import { BaseDocOrientService } from "../core/base-doc-orient.service.js";
+import type { DocOrientServiceOptions } from "../interface.js";
+/**
+ * Self-contained Node.js service for classifying document image orientation.
+ *
+ * Handles model loading, caching, and lazy initialization internally.
+ * The model is loaded on the first call to `run()`.
+ *
+ * @example
+ * ```ts
+ * const service = new DocOrientService();
+ * const result = await service.run(imageBuffer);
+ * console.log(result.orientation); // 0, 90, 180, or 270
+ * await service.destroy();
+ * ```
+ */
+export declare class DocOrientService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: DocOrientServiceOptions);
+    private log;
+    private ensureSession;
+    /**
+     * Classify the orientation of a document image.
+     * Lazily loads the model on first call.
+     */
+    run(...args: Parameters<BaseDocOrientService["run"]>): ReturnType<BaseDocOrientService["run"]>;
+    /** Check if the model session has been loaded. */
+    isInitialized(): boolean;
+    /** Release the ONNX session and free resources. */
+    destroy(): Promise<void>;
+    /** Delete all locally cached ONNX model files. */
+    clearModelCache(): void;
+}

package/processor/doc-orient.service.js

@@ -0,0 +1,3 @@
+export class DocOrientService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[DocOrientService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await loadResource(this.options.model,MODEL_URLS.docOrient,(msg)=>this.log(msg));let sessionOptions=this.options.session||DEFAULT_SESSION_OPTIONS;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseDocOrientService(new NodePlatformProvider,this.session,this.options.docOrient,this.options.debugging)}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}clearModelCache(){clearModelCache((msg)=>this.log(msg))}}import*as ort from"onnxruntime-node";import{BaseDocOrientService}from"../core/base-doc-orient.service.js";import{MODEL_URLS,DEFAULT_SESSION_OPTIONS}from"../constants.js";import{NodePlatformProvider}from"./platform.node.js";import{loadResource,clearModelCache}from"./model-loader.js";

package/processor/model-loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Fetch a resource from a URL and cache it locally.
+ */
+export declare function fetchAndCache(url: string, log: (msg: string) => void): Promise<ArrayBuffer>;
+/**
+ * Load a resource from a buffer, file path, URL, or default URL.
+ */
+export declare function loadResource(source: string | ArrayBuffer | undefined, defaultUrl: string, log: (msg: string) => void): Promise<ArrayBuffer>;
+/**
+ * Delete all locally cached ONNX model files.
+ */
+export declare function clearModelCache(log: (msg: string) => void): void;

package/processor/model-loader.js

@@ -0,0 +1,3 @@
+import{existsSync,mkdirSync,readFileSync,writeFileSync}from"fs";import*as os from"os";import*as path from"path";let CACHE_DIR=path.join(os.homedir(),".cache","ppu-doc-correction");export async function fetchAndCache(url,log){let fileName=path.basename(new URL(url).pathname);let cachePath=path.join(CACHE_DIR,fileName);if(existsSync(cachePath)){log(`Loading cached resource from: ${cachePath}`);let buf=readFileSync(cachePath);return buf.buffer.slice(buf.byteOffset,buf.byteOffset+buf.byteLength)}console.log(`Downloading resource: ${fileName}
+`+`                      Cached at: ${CACHE_DIR}`);log(`Fetching resource from URL: ${url}`);let response=await fetch(url);if(!response.ok){throw new Error(`Failed to fetch resource from ${url}`)}if(!response.body){throw new Error("Response body is null or undefined")}let contentLength=response.headers.get("Content-Length");let totalLength=contentLength?parseInt(contentLength,10):0;let receivedLength=0;let chunks=[];let reader=response.body.getReader();while(true){const{done,value}=await reader.read();if(done)break;chunks.push(value);receivedLength+=value.length;if(totalLength>0){let percentage=(receivedLength/totalLength*100).toFixed(2);process.stdout.write(`\rDownloading... ${percentage}%`)}}process.stdout.write(`
+`);let buffer=new Uint8Array(receivedLength);let position=0;for(let chunk of chunks){buffer.set(chunk,position);position+=chunk.length}log(`Caching resource to: ${cachePath}`);if(!existsSync(CACHE_DIR)){mkdirSync(CACHE_DIR,{recursive:true})}writeFileSync(cachePath,Buffer.from(buffer));return buffer.buffer}export async function loadResource(source,defaultUrl,log){if(source instanceof ArrayBuffer){log("Loading resource from ArrayBuffer");return source}if(typeof source==="string"){if(source.startsWith("http")){return fetchAndCache(source,log)}else{let resolvedPath=path.resolve(process.cwd(),source);log(`Loading resource from path: ${resolvedPath}`);let buf=readFileSync(resolvedPath);return buf.buffer.slice(buf.byteOffset,buf.byteOffset+buf.byteLength)}}return fetchAndCache(defaultUrl,log)}export function clearModelCache(log){const{rmSync}=require("fs");if(existsSync(CACHE_DIR)){log(`Clearing model cache at: ${CACHE_DIR}`);rmSync(CACHE_DIR,{recursive:true,force:true});console.log(`Model cache cleared: ${CACHE_DIR}`)}else{log("Cache directory does not exist, nothing to clear.")}}

package/processor/platform.node.d.ts

@@ -0,0 +1,10 @@
+import * as ort from "onnxruntime-node";
+import type { CoreCanvas, PlatformProvider } from "../core/platform.js";
+export declare class NodePlatformProvider implements PlatformProvider<CoreCanvas> {
+    readonly pathSeparator: string;
+    readonly ort: typeof ort;
+    createCanvas(width: number, height: number): CoreCanvas;
+    isCanvas(image: unknown): image is CoreCanvas;
+    loadResource(source: string | ArrayBuffer | undefined, defaultUrl: string): Promise<ArrayBuffer>;
+    saveDebugImage(canvas: CoreCanvas, filename: string, outputDir: string): Promise<void>;
+}

package/processor/platform.node.js

@@ -0,0 +1 @@
+export class NodePlatformProvider{pathSeparator=path.sep;ort=ort;createCanvas(width,height){return new Canvas(width,height)}isCanvas(image){return image instanceof Canvas}async loadResource(source,defaultUrl){if(source instanceof ArrayBuffer){return source}let sourceToLoad=typeof source==="string"?source:defaultUrl;if(sourceToLoad.startsWith("http")){let response=await fetch(sourceToLoad);if(!response.ok){throw new Error(`Failed to fetch resource from ${sourceToLoad}`)}return response.arrayBuffer()}let buffer=await fs.readFile(sourceToLoad);return buffer.buffer.slice(buffer.byteOffset,buffer.byteOffset+buffer.byteLength)}async saveDebugImage(canvas,filename,outputDir){await fs.mkdir(outputDir,{recursive:true});await CanvasToolkit.getInstance().saveImage({canvas,filename,path:outputDir})}}import*as fs from"fs/promises";import*as ort from"onnxruntime-node";import*as path from"path";import{Canvas,CanvasToolkit}from"ppu-ocv";

package/processor/text-orient.service.d.ts

@@ -0,0 +1,35 @@
+import { BaseTextOrientService } from "../core/base-text-orient.service.js";
+import type { TextOrientServiceOptions } from "../interface.js";
+/**
+ * Self-contained Node.js service for classifying text line orientation.
+ *
+ * Handles model loading, caching, and lazy initialization internally.
+ * The model is loaded on the first call to `run()`.
+ *
+ * @example
+ * ```ts
+ * const service = new TextOrientService();
+ * const result = await service.run(imageBuffer);
+ * console.log(result.orientation); // 0 or 180
+ * await service.destroy();
+ * ```
+ */
+export declare class TextOrientService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: TextOrientServiceOptions);
+    private log;
+    private ensureSession;
+    /**
+     * Classify the orientation of a text line image.
+     * Lazily loads the model on first call.
+     */
+    run(...args: Parameters<BaseTextOrientService["run"]>): ReturnType<BaseTextOrientService["run"]>;
+    /** Check if the model session has been loaded. */
+    isInitialized(): boolean;
+    /** Release the ONNX session and free resources. */
+    destroy(): Promise<void>;
+    /** Delete all locally cached ONNX model files. */
+    clearModelCache(): void;
+}

package/processor/text-orient.service.js

@@ -0,0 +1,3 @@
+export class TextOrientService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[TextOrientService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await loadResource(this.options.model,MODEL_URLS.textOrient,(msg)=>this.log(msg));let sessionOptions=this.options.session||DEFAULT_SESSION_OPTIONS;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseTextOrientService(new NodePlatformProvider,this.session,this.options.textOrient,this.options.debugging)}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}clearModelCache(){clearModelCache((msg)=>this.log(msg))}}import*as ort from"onnxruntime-node";import{BaseTextOrientService}from"../core/base-text-orient.service.js";import{MODEL_URLS,DEFAULT_SESSION_OPTIONS}from"../constants.js";import{NodePlatformProvider}from"./platform.node.js";import{loadResource,clearModelCache}from"./model-loader.js";

package/processor/text-unwarp.service.d.ts

@@ -0,0 +1,35 @@
+import { BaseTextUnwarpService } from "../core/base-text-unwarp.service.js";
+import type { TextUnwarpServiceOptions } from "../interface.js";
+/**
+ * Self-contained Node.js service for unwarping distorted document images.
+ *
+ * Handles model loading, caching, and lazy initialization internally.
+ * The model is loaded on the first call to `run()`.
+ *
+ * @example
+ * ```ts
+ * const service = new TextUnwarpService();
+ * const result = await service.run(imageBuffer);
+ * // result.correctedImage contains the unwarped image
+ * await service.destroy();
+ * ```
+ */
+export declare class TextUnwarpService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: TextUnwarpServiceOptions);
+    private log;
+    private ensureSession;
+    /**
+     * Unwarp a distorted document image.
+     * Lazily loads the model on first call.
+     */
+    run(...args: Parameters<BaseTextUnwarpService["run"]>): ReturnType<BaseTextUnwarpService["run"]>;
+    /** Check if the model session has been loaded. */
+    isInitialized(): boolean;
+    /** Release the ONNX session and free resources. */
+    destroy(): Promise<void>;
+    /** Delete all locally cached ONNX model files. */
+    clearModelCache(): void;
+}

package/processor/text-unwarp.service.js

@@ -0,0 +1,3 @@
+export class TextUnwarpService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[TextUnwarpService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await loadResource(this.options.model,MODEL_URLS.textUnwarp,(msg)=>this.log(msg));let sessionOptions=this.options.session||DEFAULT_SESSION_OPTIONS;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseTextUnwarpService(new NodePlatformProvider,this.session,this.options.textUnwarp,this.options.debugging)}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}clearModelCache(){clearModelCache((msg)=>this.log(msg))}}import*as ort from"onnxruntime-node";import{BaseTextUnwarpService}from"../core/base-text-unwarp.service.js";import{MODEL_URLS,DEFAULT_SESSION_OPTIONS}from"../constants.js";import{NodePlatformProvider}from"./platform.node.js";import{loadResource,clearModelCache}from"./model-loader.js";

package/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Deep merges multiple objects into the target object.
+ * Arrays are overwritten, not concatenated.
+ *
+ * @param target The target object to merge into.
+ * @param sources The source objects to merge from.
+ * @returns The merged target object.
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Checks if a value is a plain object.
+ *
+ * @param item The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export declare function isObject(item: unknown): item is Record<string, unknown>;

package/utils.js

@@ -0,0 +1 @@
+export function deepMerge(target,...sources){if(!sources.length)return target;let source=sources.shift();if(isObject(target)&&isObject(source)){for(let key in source){if(Object.prototype.hasOwnProperty.call(source,key)){let sourceValue=source[key];let targetValue=target[key];if(isObject(sourceValue)){if(!targetValue||!isObject(targetValue)){target[key]={}}deepMerge(target[key],sourceValue)}else if(sourceValue!==undefined){target[key]=sourceValue}}}}return deepMerge(target,...sources)}export function isObject(item){return item!==null&&typeof item==="object"&&!Array.isArray(item)&&!(item instanceof Date)&&!(item instanceof RegExp)&&!(item instanceof ArrayBuffer)&&!ArrayBuffer.isView(item)}

package/web/doc-orient.service.web.d.ts

@@ -0,0 +1,20 @@
+import { BaseDocOrientService } from "../core/base-doc-orient.service.js";
+import type { DocOrientServiceOptions } from "../interface.js";
+/**
+ * Self-contained browser service for classifying document image orientation.
+ *
+ * Handles model fetching and lazy initialization internally.
+ * The model is fetched on the first call to `run()`.
+ */
+export declare class DocOrientService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: DocOrientServiceOptions);
+    private log;
+    private ensureSession;
+    private loadModel;
+    run(...args: Parameters<BaseDocOrientService["run"]>): ReturnType<BaseDocOrientService["run"]>;
+    isInitialized(): boolean;
+    destroy(): Promise<void>;
+}

package/web/doc-orient.service.web.js

@@ -0,0 +1,3 @@
+export class DocOrientService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[DocOrientService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await this.loadModel();let sessionOptions=this.options.session||DEFAULT_WEB_SESSION;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseDocOrientService(new WebPlatformProvider,this.session,this.options.docOrient,this.options.debugging)}async loadModel(){if(this.options.model instanceof ArrayBuffer)return this.options.model;let url=typeof this.options.model==="string"?this.options.model:MODEL_URLS.docOrient;this.log(`Fetching model from: ${url}`);let response=await fetch(url);if(!response.ok)throw new Error(`Failed to fetch model from ${url}`);return response.arrayBuffer()}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}}import*as ort from"onnxruntime-web";import{BaseDocOrientService}from"../core/base-doc-orient.service.js";import{MODEL_URLS}from"../constants.js";import{WebPlatformProvider}from"./platform.web.js";let DEFAULT_WEB_SESSION={executionProviders:["wasm"],graphOptimizationLevel:"all"};

package/web/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module
+ *
+ * Document correction for browsers and web environments.
+ *
+ * Three independent, lazy-loading services using `onnxruntime-web` (WASM):
+ * - `DocOrientService` — document orientation classification
+ * - `TextUnwarpService` — geometric document unwarping
+ * - `TextOrientService` — text line orientation classification
+ *
+ * @example
+ * ```ts
+ * import { DocOrientService } from "ppu-doc-correction/web";
+ *
+ * const service = new DocOrientService();
+ * const result = await service.run(canvas);
+ * console.log(result.orientation);
+ * await service.destroy();
+ * ```
+ */
+export { DocOrientService } from "./doc-orient.service.web.js";
+export { TextOrientService } from "./text-orient.service.web.js";
+export { TextUnwarpService } from "./text-unwarp.service.web.js";
+export type { DebuggingOptions, DocOrientation, DocOrientOptions, DocOrientResult, DocOrientServiceOptions, SessionOptions, TextOrientation, TextOrientOptions, TextOrientResult, TextOrientServiceOptions, TextUnwarpOptions, TextUnwarpResult, TextUnwarpServiceOptions, } from "../interface.js";
+export { DEFAULT_DEBUGGING_OPTIONS, DEFAULT_DOC_ORIENT_OPTIONS, DEFAULT_SESSION_OPTIONS, DEFAULT_TEXT_ORIENT_OPTIONS, DEFAULT_TEXT_UNWARP_OPTIONS, MODEL_URLS, } from "../constants.js";

package/web/index.js

@@ -0,0 +1 @@
+export{DocOrientService}from"./doc-orient.service.web.js";export{TextOrientService}from"./text-orient.service.web.js";export{TextUnwarpService}from"./text-unwarp.service.web.js";export{DEFAULT_DEBUGGING_OPTIONS,DEFAULT_DOC_ORIENT_OPTIONS,DEFAULT_SESSION_OPTIONS,DEFAULT_TEXT_ORIENT_OPTIONS,DEFAULT_TEXT_UNWARP_OPTIONS,MODEL_URLS}from"../constants.js";

package/web/platform.web.d.ts

@@ -0,0 +1,12 @@
+import type { CoreCanvas, PlatformProvider } from "../core/platform.js";
+/**
+ * PlatformProvider implementation for browser environments.
+ */
+export declare class WebPlatformProvider implements PlatformProvider<CoreCanvas> {
+    readonly pathSeparator = "/";
+    readonly ort: PlatformProvider["ort"];
+    createCanvas(_width: number, _height: number): CoreCanvas;
+    isCanvas(image: unknown): image is CoreCanvas;
+    loadResource(source: string | ArrayBuffer | undefined, defaultUrl: string): Promise<ArrayBuffer>;
+    saveDebugImage(_canvas: CoreCanvas, _filename: string, _outputDir: string): Promise<void>;
+}

package/web/platform.web.js

@@ -0,0 +1 @@
+export class WebPlatformProvider{pathSeparator="/";ort=ort;createCanvas(_width,_height){let canvas=document.createElement("canvas");canvas.width=_width;canvas.height=_height;canvas.getContext("2d",{willReadFrequently:true});return canvas}isCanvas(image){return!!(image instanceof HTMLCanvasElement||typeof OffscreenCanvas!=="undefined"&&image instanceof OffscreenCanvas||image&&typeof image.getContext==="function")}async loadResource(source,defaultUrl){if(source instanceof ArrayBuffer){return source}let sourceToLoad=typeof source==="string"?source:defaultUrl;let response=await fetch(sourceToLoad);if(!response.ok){throw new Error(`Failed to fetch resource from ${sourceToLoad}`)}return response.arrayBuffer()}async saveDebugImage(_canvas,_filename,_outputDir){return Promise.resolve()}}import*as ort from"onnxruntime-web";if(typeof window!=="undefined"&&!ort.env.wasm.wasmPaths){ort.env.wasm.wasmPaths="https://cdn.jsdelivr.net/npm/onnxruntime-web@1.24.2/dist/"}

package/web/text-orient.service.web.d.ts

@@ -0,0 +1,20 @@
+import { BaseTextOrientService } from "../core/base-text-orient.service.js";
+import type { TextOrientServiceOptions } from "../interface.js";
+/**
+ * Self-contained browser service for classifying text line orientation.
+ *
+ * Handles model fetching and lazy initialization internally.
+ * The model is fetched on the first call to `run()`.
+ */
+export declare class TextOrientService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: TextOrientServiceOptions);
+    private log;
+    private ensureSession;
+    private loadModel;
+    run(...args: Parameters<BaseTextOrientService["run"]>): ReturnType<BaseTextOrientService["run"]>;
+    isInitialized(): boolean;
+    destroy(): Promise<void>;
+}

package/web/text-orient.service.web.js

@@ -0,0 +1,3 @@
+export class TextOrientService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[TextOrientService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await this.loadModel();let sessionOptions=this.options.session||DEFAULT_WEB_SESSION;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseTextOrientService(new WebPlatformProvider,this.session,this.options.textOrient,this.options.debugging)}async loadModel(){if(this.options.model instanceof ArrayBuffer)return this.options.model;let url=typeof this.options.model==="string"?this.options.model:MODEL_URLS.textOrient;this.log(`Fetching model from: ${url}`);let response=await fetch(url);if(!response.ok)throw new Error(`Failed to fetch model from ${url}`);return response.arrayBuffer()}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}}import*as ort from"onnxruntime-web";import{BaseTextOrientService}from"../core/base-text-orient.service.js";import{MODEL_URLS}from"../constants.js";import{WebPlatformProvider}from"./platform.web.js";let DEFAULT_WEB_SESSION={executionProviders:["wasm"],graphOptimizationLevel:"all"};

package/web/text-unwarp.service.web.d.ts

@@ -0,0 +1,20 @@
+import { BaseTextUnwarpService } from "../core/base-text-unwarp.service.js";
+import type { TextUnwarpServiceOptions } from "../interface.js";
+/**
+ * Self-contained browser service for unwarping distorted document images.
+ *
+ * Handles model fetching and lazy initialization internally.
+ * The model is fetched on the first call to `run()`.
+ */
+export declare class TextUnwarpService {
+    private readonly options;
+    private inner;
+    private session;
+    constructor(options?: TextUnwarpServiceOptions);
+    private log;
+    private ensureSession;
+    private loadModel;
+    run(...args: Parameters<BaseTextUnwarpService["run"]>): ReturnType<BaseTextUnwarpService["run"]>;
+    isInitialized(): boolean;
+    destroy(): Promise<void>;
+}

package/web/text-unwarp.service.web.js

@@ -0,0 +1,3 @@
+export class TextUnwarpService{options;inner=null;session=null;constructor(options={}){this.options=options}log(message){if(this.options.debugging?.verbose){console.log(`[TextUnwarpService] ${message}`)}}async ensureSession(){if(this.inner)return;let buffer=await this.loadModel();let sessionOptions=this.options.session||DEFAULT_WEB_SESSION;this.session=await ort.InferenceSession.create(new Uint8Array(buffer),sessionOptions);this.log(`Model loaded
+	input: ${this.session.inputNames}
+	output: ${this.session.outputNames}`);this.inner=new BaseTextUnwarpService(new WebPlatformProvider,this.session,this.options.textUnwarp,this.options.debugging)}async loadModel(){if(this.options.model instanceof ArrayBuffer)return this.options.model;let url=typeof this.options.model==="string"?this.options.model:MODEL_URLS.textUnwarp;this.log(`Fetching model from: ${url}`);let response=await fetch(url);if(!response.ok)throw new Error(`Failed to fetch model from ${url}`);return response.arrayBuffer()}async run(...args){await this.ensureSession();return this.inner.run(...args)}isInitialized(){return this.session!==null}async destroy(){await this.session?.release();this.session=null;this.inner=null}}import*as ort from"onnxruntime-web";import{BaseTextUnwarpService}from"../core/base-text-unwarp.service.js";import{MODEL_URLS}from"../constants.js";import{WebPlatformProvider}from"./platform.web.js";let DEFAULT_WEB_SESSION={executionProviders:["wasm"],graphOptimizationLevel:"all"};