mirror of
https://github.com/visioncortex/vtracer.git
synced 2026-09-12 15:16:08 -07:00
Chris Tsang
46a1b90ccd
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.
54 lines
1.7 KiB
Markdown
54 lines
1.7 KiB
Markdown
# vtracer (Node.js)
|
|
|
|
Raster → vector (SVG) for Node, a WebAssembly build of the
|
|
[`vtracer`](https://github.com/visioncortex/vtracer) framework. Image decoding
|
|
and vectorization both happen in wasm, so there is **no native dependency** —
|
|
just `npm install`.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
npm install @visioncortex/vtracer
|
|
```
|
|
|
|
## Usage
|
|
|
|
```js
|
|
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`](https://rustwasm.github.io/wasm-pack/):
|
|
|
|
```sh
|
|
npm run build # wasm-pack build --target nodejs --out-dir pkg
|
|
npm test
|
|
```
|