@cadit-app/potrace-ts

A TypeScript library for tracing bitmap images to vector paths. Based on the Potrace algorithm and potrace.js by Casper Lamboo.

Features

• Worker-compatible - Core functions work in Web Workers without DOM
• Browser-ready - Works directly with esm.sh, no bundling required
• Type-safe - Full TypeScript definitions included
• Auto-threshold - Automatic threshold calculation using Otsu's method
• Auto-invert - Automatically detects light-on-dark images and inverts them
• Image decoding - Built-in PNG and JPEG decoding (no DOM required)
• Multiple APIs - From simple data URL tracing to low-level bitmap manipulation

Dependencies

• upng-js - Pure JavaScript PNG decoder
• jpeg-js - Pure JavaScript JPEG decoder

Installation

npm install @cadit-app/potrace-ts
# or
pnpm add @cadit-app/potrace-ts

Or use directly from esm.sh:

import { traceDataUrl, getSVG } from 'https://esm.sh/@cadit-app/potrace-ts';

Usage

Trace a PNG/JPEG Data URL (Recommended)

The simplest way to trace an image. Works in Web Workers.

import { traceDataUrl, getSVG, THRESHOLD_AUTO, INVERT_AUTO } from '@cadit-app/potrace-ts';

// Fully automatic (recommended) - auto threshold + auto invert
const paths = traceDataUrl(pngDataUrl);
const svg = getSVG(paths, 1);

// Manual threshold (0-255)
const paths = traceDataUrl(jpegDataUrl, { threshold: 180 });

// Explicit invert control
const paths = traceDataUrl(dataUrl, { invert: true });   // Always invert
const paths = traceDataUrl(dataUrl, { invert: false });  // Never invert
const paths = traceDataUrl(dataUrl, { invert: 'auto' }); // Auto-detect (default)

// Full options
const paths = traceDataUrl(dataUrl, {
  threshold: THRESHOLD_AUTO,  // -1 for auto, or 0-255
  invert: 'auto',             // 'auto', true, or false
  turnpolicy: 'black',
  turdsize: 2,
  optcurve: true,
  alphamax: 1,
  opttolerance: 0.2
});

Browser (with DOM)

import { traceUrl, getSVG } from '@cadit-app/potrace-ts';

// Trace an image URL (requires DOM)
const paths = await traceUrl('image.png');
const svg = getSVG(paths, 1);

Web Worker (no DOM required)

import { 
  traceBitmap, 
  getSVG, 
  imageDataToBitmap,
  decodeImageDataUrl,
  calculateAutoThreshold
} from '@cadit-app/potrace-ts';

// From ImageData (e.g., from OffscreenCanvas)
const imageData = offscreenCanvas.getContext('2d').getImageData(0, 0, width, height);
const threshold = calculateAutoThreshold(imageData); // Otsu's method
const bitmap = imageDataToBitmap(imageData, threshold);
const paths = traceBitmap(bitmap);
const svg = getSVG(paths, 1);

SVG Images

This library traces bitmap images (PNG, JPEG). For SVG files, you need to first render them to a bitmap using a library like resvg-js:

import { Resvg } from '@resvg/resvg-wasm';
import { traceDataUrl, getSVG } from '@cadit-app/potrace-ts';

// Render SVG to PNG
const resvg = new Resvg(svgString);
const pngData = resvg.render();
const pngBuffer = pngData.asPng();

// Convert to data URL
const base64 = btoa(String.fromCharCode(...pngBuffer));
const pngDataUrl = \`data:image/png;base64,\${base64}\`;

// Trace the rendered PNG
const paths = traceDataUrl(pngDataUrl);
const svg = getSVG(paths, 1);

API Reference

High-Level Functions

`traceDataUrl(dataUrl, options?)`

Trace a PNG or JPEG data URL. This is the recommended method for most use cases.

function traceDataUrl(dataUrl: string, options?: TraceDataUrlOptions): Path[]

Options:

• `threshold`: Brightness threshold (0-255), or `THRESHOLD_AUTO` (-1) for automatic. Default: auto
• `invert`: Invert image before tracing. Default: false
• Plus all `PotraceOptions` (see below)

`traceUrl(url, options?)`

Trace an image from URL. Requires DOM (browser main thread only).

`traceImage(image, options?)`

Trace an HTMLImageElement. Requires DOM.

`traceCanvas(canvas, options?)`

Trace an HTMLCanvasElement. Requires DOM.

Low-Level Functions

`traceBitmap(bitmap, options?)`

Trace a binary bitmap. Works everywhere (no DOM required).

`imageDataToBitmap(imageData, threshold?)`

Convert RGBA ImageData to binary bitmap.

`decodeImageDataUrl(dataUrl)`

Decode a PNG/JPEG data URL to ImageData. Works in Web Workers.

`calculateAutoThreshold(imageData)`

Calculate optimal threshold using Otsu's method.

`getSVG(paths, scale?)`

Convert traced paths to SVG string.

`getPaths(paths)`

Convert traced paths to a readable path format.

Options

interface PotraceOptions {
  turnpolicy: 'right' | 'black' | 'white' | 'majority' | 'minority';
  turdsize: number;    // Suppress speckles up to this size (default: 2)
  optcurve: boolean;   // Enable curve optimization (default: true)
  alphamax: number;    // Corner threshold (default: 1)
  opttolerance: number; // Curve optimization tolerance (default: 0.2)
}

Constants

• THRESHOLD_AUTO = -1 - Use automatic threshold (Otsu's method)
• INVERT_AUTO = 'auto' - Automatically detect whether to invert based on mean luminance

Supported Formats

| Format | Support | Notes | |--------|---------|-------| | PNG | ✅ Full | Including transparency | | JPEG | ✅ Full | | | SVG | ⚠️ Indirect | Render to PNG first (see above) | | WebP | ❌ Not yet | May be added in future | | GIF | ❌ No | |

License

ISC