Practical guide
Turn a trace into editable design material
Merge the near-identical colors a tracer produces, then group, snap and theme what is left.
Problem
A faithful trace is colour-fragmented. Measured on real artwork, a 720px illustration produced 1,019 distinct fills across 1,040 paths, and a detailed photographic source produced 81,027 fills across 138,909 elements. Nothing downstream works at that fragmentation: a stylesheet with a thousand custom properties is not a theme, and a design tool shows one undifferentiated blob. Consolidation is the pass that makes the rest meaningful.
Command
npx kurviq --input art.png --output art.svg \
--consolidate 12 --snap --structure groups --theme css-varsBefore and after
PNG SVG Pinwheel App Icon
A compact multicolor icon balances rounded geometry with restrained inner shading.
Across a 47-image corpus, bare --consolidate reduced 150,477 distinct fills to 10,379 and cut bytes by 21%. --flatten, --structure and --theme are render-identical on every image tested: the rasterized output is byte-for-byte the same, only the document changes.
Workflow
1. Consolidate first
Bare --consolidate merges fills that differ by less than a just-noticeable amount (CIEDE2000 dE 2.3) and was safe on every image tested. A hard cap such as --consolidate 12 is a deliberate posterisation: good on flat artwork, destructive on photographs.
2. Snap what is provably a shape
Acceptance is by chord bulge, not vertex distance. A regular polygon has its vertices exactly on a circle, so vertex fitting alone would turn true octagons into circles. Rings and annuli are skipped, because splitting a shape whose hole is encoded by winding would fill the hole.
3. Add identity, or strip it
--structure groups gives every element a stable id and a palette class. --flatten does the opposite, merging everything it safely can for the smallest possible file. They are mutually exclusive.
4. Activate theming deliberately
Elements keep their literal fill attribute, and the custom-property rules are scoped under a kurviq-theme class that Kurviq never sets. Add that class to the svg or an ancestor to theme it. Without it, renderers that do not support CSS custom properties are unaffected.
Flag reference
| Flag | Value | Why it is here |
|---|---|---|
--consolidate | bare, or 2-256 | Merge perceptually equal fills. Bare is safe; a low cap posterises. |
--flatten | bare | Merge same-paint elements. Render-identical. |
--snap | bare, or 0-0.2 | Emit real circle, rect and ellipse where the fit is provable. |
--structure | groups | Stable ids and palette classes. |
--theme | css-vars | Palette as CSS custom properties, scoped behind kurviq-theme. |