vh/vtracer

mirror of https://github.com/visioncortex/vtracer.git synced 2026-09-05 20:01:37 -07:00

Files

T

Chris Tsang 46a1b90ccd Add watershed clustering: hierarchical watershed frontend

An alternative region-forming frontend selected by --clustering watershed
(the color_mode field is replaced by clustering: color-cluster | bw |
watershed across CLI, Rust, Python, and Node — it selects the algorithm,
not a color space).

The algorithm is the watershed hierarchy by volume on the 4-adjacency
pixel graph, implemented from the papers:

  Cousty, Bertrand, Najman, Couprie, "Watershed Cuts: Minimum Spanning
  Forests and the Drop of Water Principle", IEEE TPAMI 31(8), 2009.
  Najman, Cousty, Perret, "Playing with Kruskal", ISMM 2013.

Edge weights are the max per-channel color difference between adjacent
pixels (no gradient image); a counting-sorted Kruskal pass builds the
binary partition tree as a flat parents array; a leaves-to-root pass
computes subtree area and volume; each merge's persistence (the volume of
the smaller side, plateau-corrected) becomes its MST edge's saliency; and
cutting the hierarchy is single-linkage over MST edges below the cut
level. Watershed cuts label every pixel — no watershed-line pixel class —
so the output is a strict, gapless partition that drops straight into
both stacked and cutout modes. Integer arithmetic and flat u32 arrays
throughout; deterministic across platforms; ~66 ms on a 1400x775 photo.

The one dial, --watershed-detail (0..=255), maps exponentially to a
target region count (each +25.5 doubles it) since the persistence
distribution is far too skewed for a linear threshold. filter_speckle
absorbs undersized basins into their most color-similar neighbour rather
than dropping them, preserving the partition. The largest region is
emitted first as a solid full-canvas background layer so stacked mode
keeps its seam-free overdraw; the mosaic flatten is unaffected.

Tests: partition invariant (disjoint masks tiling the canvas), detail
monotonicity, min-area absorption, determinism, watershed cases in the
pipeline/golden suites, stacked-vs-cutout interior equivalence, a
watershed seam test, and SegmentKey coverage for the new params.

2026-07-27 14:45:25 +01:00

1.7 KiB

Raw Blame History

vtracer (Node.js)

Raster → vector (SVG) for Node, a WebAssembly build of the vtracer framework. Image decoding and vectorization both happen in wasm, so there is no native dependency — just npm install.

Install

npm install @visioncortex/vtracer

Usage

const vtracer = require('@visioncortex/vtracer');

// file in, file out
await vtracer.convertFile('in.png', 'out.svg');
await vtracer.convertFile('in.jpg', 'out.svg', { mode: 'polygon', hierarchical: 'cutout' });

// buffers
const svg = vtracer.convertBuffer(fs.readFileSync('in.png'), { preset: 'poster' });

// raw RGBA8 pixels
const svg2 = vtracer.convertPixels(rgba, width, height, { clustering: 'bw' });

API

convertBuffer(buffer, options?) => string — encoded image (PNG/JPEG/GIF/BMP) → SVG.
convertPixels(rgba, width, height, options?) => string — raw RGBA8 → SVG.
convertFile(input, output, options?) => Promise<void> — read, trace, write.
convertFileSync(input, output, options?) => void.

`Options` (all optional, camelCase)

preset ("bw" | "poster" | "photo", applied first), clustering ("color" | "bw"), hierarchical ("stacked" | "cutout" for the seam-free mosaic), mode ("pixel" | "polygon" | "spline"), filterSpeckle, colorPrecision, layerDifference, cornerThreshold, lengthThreshold, maxIterations, spliceThreshold, pathPrecision, palette (list of #rrggbb), maxColors, optimize (0 | 1 | 2).

Build from source

Requires the Rust toolchain and wasm-pack:

npm run build   # wasm-pack build --target nodejs --out-dir pkg
npm test

1.7 KiB Raw Blame History