ppu-ocv 3.1.0 → 3.1.2

package/README.md

@@ -1,10 +1,10 @@
 # ppu-ocv
 
-A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.
+[![NPM](https://img.shields.io/npm/dw/ppu-ocv)](https://www.npmjs.com/package/ppu-ocv) [![JSR](https://jsr.io/badges/@snowfluke/ppu-ocv)](https://jsr.io/@snowfluke/ppu-ocv)
 
-![ppu-ocv pipeline demo](https://raw.githubusercontent.com/PT-Perkasa-Pilar-Utama/ppu-ocv/refs/heads/main/assets/ppu-ocv-demo.jpg)
+A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing. Decoupled canvas utilities run anywhere — Node, Bun, browsers, browser extensions, and service workers — with or without OpenCV.
 
-Image manipulation as easy as:
+![ppu-ocv pipeline demo](https://raw.githubusercontent.com/PT-Perkasa-Pilar-Utama/ppu-ocv/refs/heads/main/assets/ppu-ocv-demo.jpg)
 
 ```ts
 const processor = new ImageProcessor(canvas);
@@ -17,23 +17,33 @@ const result = processor
   .dilate({ size: [20, 20], iter: 5 })
   .toCanvas();
 
-// Memory cleanup
 processor.destroy();
 ```
 
-This work is based on https://github.com/TechStark/opencv-js.
+Based on [TechStark/opencv-js](https://github.com/TechStark/opencv-js).
+
+## Table of Contents
 
-## Why use this library?
+- [Why ppu-ocv?](#why-ppu-ocv)
+- [Installation](#installation)
+- [Usage (Node.js / Bun)](#usage-nodejs--bun)
+- [Canvas-only Usage (no OpenCV)](#canvas-only-usage-no-opencv)
+- [Web / Browser Support](#web--browser-support)
+- [Built-in Pipeline Operations](#built-in-pipeline-operations)
+- [Extending Operations](#extending-operations)
+- [Class Documentation](#class-documentation)
+- [Migrating from v2](#migrating-from-v2)
+- [Contributing](#contributing)
+- [License](#license)
 
-OpenCV is powerful but can be cumbersome to use directly. This library provides:
+## Why ppu-ocv?
 
-1. **Simplified API**: Transform complex OpenCV calls into simple chainable methods
-2. **Reduced Boilerplate**: No need to manage memory, conversions, or dimensions manually
-3. **Development Speed**: Add image processing to your app in minutes, not hours
-4. **Extensibility**: Custom operations for your specific needs without library modifications
-5. **TypeScript Integration**: Full IntelliSense support with parameter validation
-6. **Web Support**: Supports running directly in the browser
-7. **Loosely Coupled**: Canvas utilities are fully decoupled from OpenCV. Usable in Browser Extensions, Service Workers, and other constrained environments where OpenCV cannot be initialised
+- **Simplified API** — chainable methods that hide OpenCV's verbose Mat allocation
+- **No memory management** — automatic Mat lifecycle within the pipeline
+- **Type-safe** — full TypeScript inference for operations and options
+- **Extensible** — register custom operations with `registry.register(...)` without forking
+- **Cross-platform** — same API in Node, Bun, browsers, and constrained runtimes
+- **Loosely coupled** — canvas utilities work standalone; OpenCV is only loaded when actually needed
 
 ## Installation
 
@@ -125,9 +135,7 @@ const buffer = await CanvasProcessor.prepareBuffer(cropped);
 import { CanvasProcessor, CanvasToolkit } from "ppu-ocv/canvas-web";
 
 const response = await fetch("/image.jpg");
-const canvas = await CanvasProcessor.prepareCanvas(
-  await response.arrayBuffer(),
-);
+const canvas = await CanvasProcessor.prepareCanvas(await response.arrayBuffer());
 ```
 
 ## Web / Browser Support
@@ -171,9 +179,7 @@ processor.destroy();
   await ImageProcessor.initRuntime();
 
   const response = await fetch("/my-image.jpg");
-  const canvas = await CanvasProcessor.prepareCanvas(
-    await response.arrayBuffer(),
-  );
+  const canvas = await CanvasProcessor.prepareCanvas(await response.arrayBuffer());
 
   const processor = new ImageProcessor(canvas);
   processor
@@ -296,8 +302,8 @@ regions.sort((a, b) => b.area - a.area); // largest first
 
 **Region detection** (returns data, does not mutate)
 
-| Method        | Options                                          | Description                                                  |
-| ------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| Method        | Options                                                                                  | Description                                                    |
+| ------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `findRegions` | `foreground?` (`"light"`), `thresh?` (127), `minArea?`, `maxArea?`, `padding?`, `scale?` | 8-connected flood-fill on a binary canvas → `DetectedRegion[]` |
 
 `DetectedRegion` shape: `{ bbox: BoundingBox, area: number }` where `bbox` is `{ x0, y0, x1, y1 }` (x1/y1 exclusive). Equivalent to OpenCV's `findContours(RETR_EXTERNAL) + boundingRect` — all matched bboxes agree within ±1 px on solid binary images. ³
@@ -368,37 +374,24 @@ A collection of utility functions for analyzing image properties (requires OpenC
 
 ## Contributing
 
-Contributions are welcome! If you would like to contribute, please follow these steps:
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — setup, commit conventions, quality checks, and PR flow. Also:
 
-1. **Fork the Repository:** Create your own fork of the project.
-2. **Create a Feature Branch:** Use a descriptive branch name for your changes.
-3. **Implement Changes:** Make your modifications, add tests, and ensure everything passes.
-4. **Submit a Pull Request:** Open a pull request to discuss your changes and get feedback.
+- [Code of Conduct](./CODE_OF_CONDUCT.md) — community standards.
+- [Security policy](./SECURITY.md) — how to report vulnerabilities privately.
+- [Issue tracker](https://github.com/PT-Perkasa-Pilar-Utama/ppu-ocv/issues) — bug reports, feature requests, and docs gaps each have a template.
 
-### Running Tests
-
-This project uses Bun for testing. To run the tests locally, execute:
+Quick local commands:
 
 ```bash
-bun test
+bun install
+bun test           # run unit tests
+bun run fmt        # check formatting
+bun run lint       # check lint
+bun run type-check # tsgo --noEmit
+bun task build     # emit ./lib
+bun task bench     # micro-bench the operations registry
 ```
 
-Ensure that all tests pass before submitting your pull request.
-
-## Scripts
-
-Recommended development environment is in a Linux-based environment.
-
-Library template: https://github.com/aquapi/lib-template
-
-### [Build](./scripts/build.ts)
-
-Emit `.js` and `.d.ts` files to [`lib`](./lib).
-
-### [Publish](./scripts/publish.ts)
-
-Move [`package.json`](./package.json), [`README.md`](./README.md) to [`lib`](./lib) and publish the package.
-
 ## Migrating from v2
 
 See [MIGRATION.md](./MIGRATION.md) for a full guide. The short version:

package/index.canvas-web.d.ts

@@ -1,6 +1,6 @@
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
 export { getPlatform, setPlatform } from "./canvas-factory.js";
-export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { webPlatform } from "./platform/web.js";
 export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
 export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.canvas.d.ts

@@ -2,7 +2,7 @@ export { Canvas, createCanvas, ImageData, loadImage } from "@napi-rs/canvas";
 export type { SKRSContext2D } from "@napi-rs/canvas";
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
 export { getPlatform, setPlatform } from "./canvas-factory.js";
-export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
 export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.d.ts

@@ -3,9 +3,9 @@ export { cv };
 export { Canvas, createCanvas, ImageData, loadImage } from "@napi-rs/canvas";
 export type { SKRSContext2D } from "@napi-rs/canvas";
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
-export { executeOperation, OperationRegistry, registry, } from "./pipeline/index.js";
+export { executeOperation, OperationRegistry, registry } from "./pipeline/index.js";
 export { getPlatform, setPlatform } from "./canvas-factory.js";
-export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { CanvasToolkitBase, type ContourLike } from "./canvas-toolkit.base.js";
 export { CanvasToolkit } from "./canvas-toolkit.js";
 export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";

package/index.web.d.ts

@@ -1,10 +1,10 @@
 import { cv } from "./cv-provider.js";
 export { cv };
 export { getPlatform, setPlatform } from "./canvas-factory.js";
-export type { CanvasLike, CanvasPlatform, Context2DLike, } from "./canvas-factory.js";
+export type { CanvasLike, CanvasPlatform, Context2DLike } from "./canvas-factory.js";
 export { webPlatform } from "./platform/web.js";
 export type { BoundingBox, Coordinate, Points } from "./index.interface.js";
-export { executeOperation, OperationRegistry, registry, } from "./pipeline/index.js";
+export { executeOperation, OperationRegistry, registry } from "./pipeline/index.js";
 export { CanvasToolkitBase as CanvasToolkit, CanvasToolkitBase, type ContourLike, } from "./canvas-toolkit.base.js";
 export { CanvasProcessor, type DetectedRegion } from "./canvas-processor.js";
 export { Contours } from "./contours.js";

package/operations/adaptive-threshold.d.ts

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

package/operations/blur.d.ts

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

package/operations/border.d.ts

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

package/operations/canny.d.ts

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

package/operations/convert.d.ts

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

package/operations/dilate.d.ts

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

package/operations/erode.d.ts

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

package/operations/grayscale.d.ts

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

package/operations/invert.d.ts

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

package/operations/morphological-gradient.d.ts

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

package/operations/resize.d.ts

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

package/operations/rotate.d.ts

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

package/operations/threshold.d.ts

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

package/operations/warp.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.",
   "keywords": [
     "open-cv",
@@ -45,21 +45,29 @@
   },
   "scripts": {
     "task": "bun scripts/task.ts",
+    "build": "bun task build",
     "build:test": "bun task build && bun test",
     "build:publish": "bun task build && bun task report-size && bun task publish",
-    "lint": "prettier --check ./src",
-    "lint:fix": "prettier --write ./src",
-    "demo": "bunx -y serve -l 4567 ."
+    "type-check": "bunx tsgo --noEmit",
+    "test": "bun test",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt --check",
+    "fmt:fix": "oxfmt .",
+    "demo": "bunx -y serve -l 4567 .",
+    "prepare": "husky"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "latest",
     "@types/bun": "latest",
     "@types/uglify-js": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20260513.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.0.0",
     "mitata": "latest",
-    "prettier": "^3.8.1",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
     "tsx": "latest",
     "typescript": "latest",
-    "typescript-eslint": "latest",
     "uglify-js": ">=2.4.24"
   },
   "repository": {

package/pipeline/registry.d.ts

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

package/pipeline/types.d.ts

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