vh/vtracer

mirror of https://github.com/visioncortex/vtracer.git synced 2026-08-31 01:15:57 -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

2.6 KiB

Raw Blame History

vtracer (Python)

Python bindings for the vtracer raster-to-vector framework. Built with pyo3 + maturin; the core Rust crate stays pure (no I/O), and this crate adds image decoding and a Pythonic API.

Install

pip install vtracer

Usage

import vtracer

# one-liners
vtracer.convert_file("in.png", "out.svg")
svg = vtracer.convert_bytes(open("in.png", "rb").read())          # -> str
svg = vtracer.convert_pixels(rgba_bytes, width, height)           # raw RGBA8

# a rich, reusable configuration object
cfg = vtracer.Config(mode="polygon", filter_speckle=8)
cfg.hierarchical = "cutout"          # seam-free mosaic
cfg.palette = ["#1b1b1b", "#e0c088", "#5a7d3c"]   # snap to a fixed palette
cfg.max_colors = 8                   # or auto-quantize
cfg.optimize = 2
svg = cfg.convert_bytes(data)

# presets
vtracer.Config.poster().convert_file("photo.jpg", "poster.svg")
vtracer.Config.bw().convert_file("scan.png", "lineart.svg")

`Config`

Constructor keyword arguments (all optional) — also exposed as mutable properties, plus the presets Config.bw(), Config.poster(), Config.photo():

arg	default	notes
`clustering`	`"color-cluster"`	`"color-cluster"`, `"bw"`, or `"watershed"`
`hierarchical`	`"stacked"`	`"stacked"` or `"cutout"` (mosaic)
`mode`	`"spline"`	`"pixel"`, `"polygon"`, `"spline"`
`filter_speckle`	`4`	discard patches smaller than X px
`color_precision`	`6`	significant bits per channel
`layer_difference`	`16`	color diff between gradient layers
`corner_threshold`	`60`	degrees
`length_threshold`	`4.0`	px
`max_iterations`	`10`
`splice_threshold`	`45`	degrees
`path_precision`	`2`	output decimal places
`palette`	`None`	list of `#rrggbb` strings
`max_colors`	`None`	auto-quantize target
`optimize`	`1`	`0` off, `1` quantize+simplify, `2` + shorthands
`binary_threshold`	`128`	bw: fixed cutoff, foreground below it
`adaptive`	`False`	bw: Bradley–Roth adaptive thresholding
`adaptive_window`	`0`	bw adaptive: window px (`0` = auto)
`adaptive_t`	`15.0`	bw adaptive: % below local mean
`watershed_detail`	`128`	watershed: hierarchy cut level 0..=255

Each Config has convert_file(input, output), convert_bytes(data, format=None) -> str, and convert_pixels(rgba, width, height) -> str.

Build from source

maturin develop            # into the active virtualenv
maturin build --release    # produce a wheel

2.6 KiB Raw Blame History Unescape Escape