Homotope

@homotope/engine

This is the engine of Homotope, an image vectorizer that runs in the browser: nothing is uploaded. Try it in the workshop (free, no account needed for SVG and PNG).

Raster-to-vector engine in pure TypeScript: turns a PNG or JPEG (any RGBA pixel buffer) into a clean SVG, and from that SVG into DXF, PDF or EPS. Released under the MIT license.

What this package is not: it has no editor, no server, no REST API, no MCP server and no printer checks; those live in the hosted service. The npm package is frozen at 0.2.0: what it contains is complete and usable on its own.

• No DOM, no runtime dependencies. The core runs unchanged in a Web Worker, in the main thread and in Node. Pixel data stays on the machine: nothing is uploaded anywhere.
• Topology first. The image is quantized in OKLab, segmented into regions, and every shared boundary is fitted once: two neighbouring shapes never overlap and never leave a gap. Holes are kept (an "O" stays an "O").
• Presets for logos, illustrations, pixel art, line art, black & white, photos, and a centerline mode that traces strokes as single open paths (plotters, engraving, embroidery).
• Fabrication exports: DXF (layers per colour, shared edges cut once), PDF, EPS, colour separations, and a cut-readiness check (tiny islands, too-close edges, node counts).
• An alternative to Potrace: no GPL code, full colour, exact shared borders.

Install

npm install @homotope/engine

Node only, to decode PNG/JPEG files (optional peer dependencies):

npm install pngjs jpeg-js

Requires an ES2022 runtime (Node ≥ 22, any current browser). ESM only.

Entry points

Browser bundles only receive what they import: the core never imports pngjs or jpeg-js.

Node example

import { readFileSync, writeFileSync } from 'node:fs';

import { vectorize, presetOptions } from '@homotope/engine'; import { convertSvg } from '@homotope/engine/export'; import { decodePng } from '@homotope/engine/node';

const image = decodePng(new Uint8Array(readFileSync('logo.png'))); const result = vectorize(image, presetOptions('logo'), { onProgress: (e) => process.stdout.write(\r${e.stage} ${Math.round(e.progress * 100)}%), });

writeFileSync('logo.svg', result.svg); writeFileSync('logo.dxf', convertSvg(result.svg, 'dxf')); console.log(\n${result.palette.colors.length} colours, ${result.stats.paths} paths);

Browser example (Web Worker)

vectorize is synchronous on purpose: run it in a worker so the page stays responsive. Its input is any ImageData-like object { width, height, data: Uint8ClampedArray } (RGBA, not premultiplied).

// main.ts

const bitmap = await createImageBitmap(file); const canvas = new OffscreenCanvas(bitmap.width, bitmap.height); const ctx = canvas.getContext('2d')!; ctx.drawImage(bitmap, 0, 0); const { width, height, data } = ctx.getImageData(0, 0, bitmap.width, bitmap.height);

const worker = new Worker(new URL('./vectorize.worker.ts', import.meta.url), { type: 'module' }); worker.onmessage = (e: MessageEvent<{ svg: string }>) => { const url = URL.createObjectURL(new Blob([e.data.svg], { type: 'image/svg+xml' })); document.querySelector ('#preview')!.src = url; // or offer it as a download }; worker.postMessage({ width, height, data }, [data.buffer]);

// vectorize.worker.ts

import { vectorize, presetOptions, type RasterImage } from '@homotope/engine';

self.onmessage = (e: MessageEvent ) => { const { svg } = vectorize(e.data, presetOptions('illustration')); self.postMessage({ svg }); };

Cancellation is cooperative: pass { cancel: { cancelled: boolean } } as the third argument (for example backed by a SharedArrayBuffer); vectorize then throws a CancelledError between and inside stages.

Presets

presetOptions(name) returns a full, independent options object that you can tweak.

import { presetOptions, vectorize } from '@homotope/engine';

const options = presetOptions('logo'); options.quantize.colors = 4; // fixed number of colours instead of 'auto' options.export.precision = 1; // decimals in path data options.export.mode = 'stacked'; // fewer nodes: shapes stacked instead of cut out const { svg } = vectorize(image, options);

Every option is typed and documented in VectorizeOptions (preprocess, quantize, segment, fit, export, centerline).

SVG output

• viewBox in the pixel coordinates of the original image, cubic Béziers, one per colour by default (export.mergeByColor).
• export.mode: 'cut' (default): every region is an exact path with its holes (fill-rule="evenodd"), no overlap; 'stacked': shapes stacked by depth, fewer nodes.
• Transparent pixels (preprocess.alphaMode: 'keep') produce no path.
• result.palette lists the colours (sRGB and OKLab, pixel counts); result.stats the number of paths and nodes; result.timings the time spent per stage.

Hosted version and API

homotope.app runs this engine in the browser with a visual editor (palette, presets, before/after), plus optional server processing, a REST API and an MCP server for AI assistants: see the API documentation.

Development

npm install

npm test # Vitest, no DOM npm run typecheck npm run lint npm run eval # renders every fixture and measures the error (Resvg) npm run build # dist/ (ESM + .d.ts)

See CONTRIBUTING.md.

License

MIT.