ppu-ocv

A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.

Image manipulation as easy as:

const processor = new ImageProcessor(canvas);

const result = processor
  .grayscale()
  .blur({ size: [5, 5] })
  .threshold()
  .invert()
  .dilate({ size: [20, 20], iter: 5 })
  .toCanvas();

// Memory cleanup
processor.destroy();

This work is based on https://github.com/TechStark/opencv-js.

Why use this library?

OpenCV is powerful but can be cumbersome to use directly. This library provides:

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

Installation

Install using your preferred package manager:

npm install ppu-ocv
yarn add ppu-ocv
bun add ppu-ocv

Usage (Node.js / Bun)

Note that Operation order is matter, you should atleast know some basic in using OpenCV. See the operations table below this.

import { ImageProcessor } from "ppu-ocv";

const file = Bun.file("./assets/receipt.jpg");
const image = await file.arrayBuffer();

const canvas = await ImageProcessor.prepareCanvas(image);
await ImageProcessor.initRuntime();

const processor = new ImageProcessor(canvas);
processor
  .grayscale()
  .blur({ size: [5, 5] })
  .threshold();

const resultCanvas = processor.toCanvas();
processor.destroy();

Or you can do directly via execute api:

import { CanvasToolkit, ImageProcessor, cv } from "ppu-ocv";

const file = Bun.file("./assets/receipt.jpg");
const image = await file.arrayBuffer();

const canvasToolkit = CanvasToolkit.getInstance();
const canvas = await ImageProcessor.prepareCanvas(image);
await ImageProcessor.initRuntime();

const processor = new ImageProcessor(canvas);
const grayscaleImg = processor.execute("grayscale").toCanvas();

// the pipeline operation continued from grayscaled image
const thresholdImg = processor
  .execute("blur")
  .execute("threshold", {
    type: cv.THRESH_BINARY_INV + cv.THRESH_OTSU,
  })
  .toCanvas();

await canvasToolkit.saveImage({
  canvas: thresholdImg,
  filename: "threshold",
  path: "out",
});

For more advanced usage, see: Example usage of ppu-ocv

Web / Browser Support

Starting from v2.0.0, ppu-ocv supports running in the browser. Import from ppu-ocv/web instead of ppu-ocv to use the browser-native canvas APIs (HTMLCanvasElement / OffscreenCanvas) instead of @napi-rs/canvas.

With a bundler (Vite, webpack, etc.)

import { ImageProcessor, cv } from "ppu-ocv/web";

await ImageProcessor.initRuntime();

// From a file input or fetch
const response = await fetch("/my-image.jpg");
const buffer = await response.arrayBuffer();

const canvas = await ImageProcessor.prepareCanvas(buffer);
const processor = new ImageProcessor(canvas);

processor
  .grayscale()
  .blur({ size: [5, 5] })
  .threshold();

const result = processor.toCanvas(); // returns HTMLCanvasElement
document.body.appendChild(result);

processor.destroy();

Vanilla HTML (no bundler)

initRuntime() automatically loads @techstark/opencv-js from the npm CDN if it's not already available. No extra script tags or import maps needed:

<script type="module">
  import { ImageProcessor } from "https://cdn.jsdelivr.net/npm/ppu-ocv@2/index.web.js";
  await ImageProcessor.initRuntime();

  const processor = new ImageProcessor(canvas);
  processor
    .grayscale()
    .blur({ size: [5, 5] })
    .threshold();

  const result = processor.toCanvas();
  processor.destroy();
</script>

Note: ES modules require HTTP/HTTPS — use a local server (npx serve .) for dev, or deploy to GitHub Pages.

See the interactive demo for a full working example.

Node vs Web differences

Feature	ppu-ocv (Node)	ppu-ocv/web (Browser)
Canvas backend	@napi-rs/canvas	HTMLCanvasElement / OffscreenCanvas
CanvasToolkit	Full (includes saveImage, clearOutput)	Base only (crop, isDirty, drawLine, drawContour)
File I/O	✅ saveImage, clearOutput	❌ Not available (use download links or toDataURL)
ImageProcessor	✅	✅ Same API
Contours	✅	✅ Same API
Image analysis	✅	✅ Same API

Platform abstraction

Under the hood, ppu-ocv uses a platform abstraction layer. The ppu-ocv entry point auto-registers the Node platform, and ppu-ocv/web auto-registers the browser platform. You can also set a custom platform:

import { setPlatform, type CanvasPlatform } from "ppu-ocv/web";

const myPlatform: CanvasPlatform = {
  createCanvas(width, height) {
    /* ... */
  },
  loadImage(source) {
    /* ... */
  },
  isCanvas(value) {
    /* ... */
  },
};

setPlatform(myPlatform);

Built-in pipeline operations

To avoid bloat, we only ship essential operations for chaining. Currently shipped operations are:

Operation	Depends on…	Why
grayscale	–	Converts to single‐channel; many ops expect a gray image first.
blur	(ideally after) grayscale	Noise reduction works best on 1-channel data.
threshold	(after) grayscale	Produces a binary image; needs gray levels.
adaptiveThreshold	(after) grayscale (and optionally blur)	Local thresholding on gray values (smoother if blurred first).
invert	(after) threshold or adaptiveThreshold	Inverting a binary mask flips foreground/background.
canny	(after) grayscale + blur	Edge detection expects a smoothed gray image.
dilate	(after) threshold or edge detection	Expands foreground regions—usually on a binary mask.
erode	(after) threshold or edge detection	Shrinks or cleans up binary regions.
morphologicalGradient	(after) dilation + erosion (or threshold)	Highlights boundaries by subtracting eroded from dilated image.
warp	–	Geometric transform; can be applied at any point.
resize	–	Also independent; purely geometry.
border	–	Independent; purely geometry.
rotate	–	Independent.

Extending operations

You can easily add your own by creating a prototype method or extend the class of ImageProcessor.

See: How to extend ppu-ocv operations

Class documentation

ImageProcessor

Method	Args	Description
constructor	cv.Mat or Canvas	Instantiate processor with initial image
static prepareCanvas	ArrayBuffer	Utility to load image from file buffer to canvas
static initRuntime		Important open-cv runtime initialization, required to call once per runtime
operations	depends	Chainable operations like blur, grayscale, resize and so on
execute	name, options	Chainable operations directly via execute api
outputs		Non-chainable & non-interupting method for output like toMat, toCanvas
destroy		Non-chainable clean-up memory to destroy the object and the state

CanvasToolkit

Method	Args	Description
crop	BoundingBox, Canvas	Crop a part of source canvas and return a new canvas of the cropped part
isDirty	Canvas, threshold	Check whether a binary canvas is dirty (full of major color either black or white) or not
saveImage	Canvas, filename, path	Save a canvas to an image file
clearOutput	path	Clear the output folder
drawLine	ctx, coordinate, style	Draw a non-filled rectangle outline on the canvas
drawContour	ctx, contour, style	Draw a contour on the canvas

Contours

Method	Args	Description
constructor	cv.Mat, options	Instantiate Contours and automatically find & store contour list from args
getAll		Crop a part of source canvas and return a new canvas of the cropped part
getFromIndex	index	Get contour at a specific index
getRect		Get the rectangle that bounds the contour
iterate	callback	Iterate over all contours and call the callback function for each contour
getLargestContourArea		Get the largest contour area
getCornerPoints	Canvas, contour	Get four corner points for a given contour. Useful for perspective transformation (warp).
destroy		Destroy & clean-up the memory from the contours

ImageAnalysis

Just a collection of utility functions for analyzing image properties.

• calculateMeanNormalizedLabLightness: Calculates the mean normalized lightness of an image using the L channel of the Lab color space. Lightness is normalized based on the image's own maximum lightness value before averaging.

• calculateMeanGrayscaleValue: Calculates the mean pixel value of the image after converting it to grayscale.

Contributing

Contributions are welcome! If you would like to contribute, please follow these steps:

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.

Running Tests

This project uses Bun for testing. To run the tests locally, execute:

bun test

Ensure that all tests pass before submitting your pull request.

Scripts

Recommended development environment is in linux-based environment.

Library template: https://github.com/aquapi/lib-template

All script sources and usage.

Build

Emit .js and .d.ts files to lib.

Publish

Move package.json, README.md to lib and publish the package.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

If you encounter any issues or have suggestions, please open an issue in the repository.

Happy coding!