mirror of
https://github.com/visioncortex/vtracer.git
synced 2026-09-12 07:06:03 -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.
46 lines
2.1 KiB
TypeScript
46 lines
2.1 KiB
TypeScript
/** Conversion options. Any field may be omitted; omitted fields use the framework default. */
|
||
export interface Options {
|
||
/** Applied before other fields: "bw" | "poster" | "photo". */
|
||
preset?: 'bw' | 'poster' | 'photo';
|
||
/** Region forming: hierarchical color clustering (default), binary threshold, or watershed. */
|
||
clustering?: 'color-cluster' | 'bw' | 'watershed';
|
||
hierarchical?: 'stacked' | 'cutout';
|
||
mode?: 'pixel' | 'polygon' | 'spline';
|
||
filterSpeckle?: number;
|
||
colorPrecision?: number;
|
||
layerDifference?: number;
|
||
cornerThreshold?: number;
|
||
lengthThreshold?: number;
|
||
maxIterations?: number;
|
||
spliceThreshold?: number;
|
||
pathPrecision?: number;
|
||
/** Fixed palette: `#rrggbb` strings. */
|
||
palette?: string[];
|
||
/** Auto-quantize target color count. */
|
||
maxColors?: number;
|
||
/** 0 = off, 1 = quantize+simplify, 2 = + shorthands/grouping. */
|
||
optimize?: number;
|
||
/** Binary mode (`clustering: 'bw'`): fixed threshold 0..=255; foreground when intensity is below it. */
|
||
binaryThreshold?: number;
|
||
/** Binary mode: use Bradley–Roth adaptive thresholding (handles uneven lighting). */
|
||
adaptive?: boolean;
|
||
/** Adaptive window side length in px; 0 = auto (~1/8 of the shorter side). */
|
||
adaptiveWindow?: number;
|
||
/** Adaptive sensitivity: percent below the local mean (default 15). */
|
||
adaptiveT?: number;
|
||
/** Watershed clustering: hierarchy cut level 0..=255 (higher = more regions, default 128). */
|
||
watershedDetail?: number;
|
||
}
|
||
|
||
/** Vectorize an encoded image (PNG/JPEG/GIF/BMP) buffer to an SVG string. */
|
||
export function convertBuffer(buffer: Uint8Array, options?: Options): string;
|
||
|
||
/** Vectorize a raw RGBA8 buffer (`width * height * 4` bytes) to an SVG string. */
|
||
export function convertPixels(rgba: Uint8Array, width: number, height: number, options?: Options): string;
|
||
|
||
/** Read an image file, vectorize it, and write the SVG to disk. */
|
||
export function convertFile(inputPath: string, outputPath: string, options?: Options): Promise<void>;
|
||
|
||
/** Synchronous {@link convertFile}. */
|
||
export function convertFileSync(inputPath: string, outputPath: string, options?: Options): void;
|