Bump every package version to 1.0.0-alpha.4 (PyPI 1.0.0a4) and promote the
CHANGELOG [Unreleased] section to 1.0.0-alpha.4. Refresh the tracked lockfile.
App download links are intentionally left at 1.0.0-alpha.3 (desktop app
release lands separately).
`6f163fc` widened watershed_detail from u8 to u32 in the core, CLI, and
Python binding but not the Node/wasm binding, which still assigned a u8 to
config.watershed_detail — a wasm build error (E0308). Widen the Node
Options field to u32 and refresh every "0..=255" watershed doc (CLI help,
Config field, .pyi, index.d.ts, and all three READMEs) to reflect that the
level is now uncapped (default 128; higher = more regions).
- version 1.0.0-alpha.3 across the workspace, Python, and Node packages
(and the vtracer dep pins, install snippets, and docs.rs link)
- CHANGELOG: date the section; note the new vtracer-bench crate and the
watershed blurred-crack filament fix
(Supersampling was explored after alpha.2 and reverted -- it did not
improve output enough to keep.)
The `vtracer` package never declared a `readme`, so its PyPI page rendered
an empty description. Point `[project].readme` at the crate's README, and
mirror it in Cargo.toml alongside the core crate's convention.
Pin the documented install to 1.0.0a2 while the 1.0 line is pre-release:
`--pre` would resolve it, but a bare `pip install vtracer` still lands on
0.6.15, whose cp314 wheels segfault on any keyword argument (pyo3 0.19
predates CPython 3.14 moving `PyTupleObject::ob_item`, #124).
Config(simplify=...) / property in Python; simplify option in Node,
with the tolerance documented in .pyi, index.d.ts, and both READMEs.
The Node README's option list also catches up with the clustering
rename and the binary/watershed options, and test.js drops the stale
colorMode key (silently ignored since the rename, so its bw assertion
was testing the default path) and asserts simplify shrinks output.
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.
New crates/vtracer-py (pyo3 + maturin, abi3) wrapping the vtracer framework.
Rather than a thin CLI-style wrapper, it exposes a mutable `Config` class with
named properties and `bw`/`poster`/`photo` preset constructors, plus three
input paths — `convert_file`, `convert_bytes` (encoded image, optional format),
and `convert_pixels` (raw RGBA8) — available as `Config` methods and
module-level functions. Palette is a list of `#rrggbb` strings; bad inputs
raise ValueError.
The core crate stays pure: image decoding lives here. The crate is excluded
from the cargo workspace (pyo3 extension-module cdylibs don't link libpython,
which breaks `cargo test` at the root) and is built with maturin. Ships a
vtracer.pyi type stub. README updated.
Chris Tsang