vtracer/docs/design

VTracer 1.0 Design Documents

VTracer is being rearchitected from a single hardcoded pipeline into a vectorization framework. These documents describe the target design.

Document	Contents
architecture.md	Workspace layout, core IR, stage traits, pipeline driver, optimizer & SVG writer, CLI
mosaic.md	The seam-free cutout/mosaic mode: boundary-graph tracing and shared-edge curve fitting
bindings.md	Python (PyPI), wasm, and the new Node.js (npm) package
roadmap.md	Milestones and verification strategy

Motivation

VTracer today (0.6.x) is a thin driver around the visioncortex crate: one pipeline (color clustering → per-cluster tracing → SVG string), a CLI, a pyo3 binding, and a web demo that duplicates the pipeline. The rewrite turns it into a framework with pluggable stages:

1. Frontend — any algorithm that produces clusters/segmentation from a raster image
2. Curve fitting backend — pluggable polyline→curve fitters (pixel, polygon, spline, future potrace-style)
3. Color fitting — mapping cluster colors to final paints, including custom fixed palettes
4. Optimizer — a pass pipeline that shrinks output (relative path syntax, shorthand commands, precision reduction)
5. True mosaic cutout — a perfect, gapless tessellation with shared boundary geometry, replacing today's fake cutout (which re-clusters a re-rendered image and shows seams)

The project stays backend/CLI focused, and everything except image file I/O compiles to wasm32-unknown-unknown.

Decisions

• visioncortex remains a dependency, wrapped behind traits. Development uses a path/[patch] dependency on the local checkout; API additions are committed to visioncortex directly and published as 0.8.x releases. Verified that everything the new design needs is already public: the fitting primitives (fit_points_with_bezier, find_corners, subdivide_keep_corners, reduce, PathSimplify::*) and cluster pixel access via ClustersView.
• In-repo rewrite, clean break. New workspace layout, new API, version bump. Old CLI flags are kept only where they map naturally.
• Python binding stays (ported to the new API). The webapp GUI is dropped; a wasm library crate replaces it.
• New Node.js library published to npm, using the wasm build internally plus a native image reader (sharp).

Pipeline at a glance

             ┌───────────┐   ┌──────────────┐   ┌─────────────────────────────┐
 raster ───▶ │ Frontend  │ ─▶│ ColorFitter* │ ─▶│ Compositing                 │
  image      │ (segment) │   │ (palette,    │   │  Stacked: closed outlines   │
             └───────────┘   │  quantize,   │   │  Mosaic:  boundary graph +  │
                             │  merge)      │   │           shared-edge fit   │
                             └──────────────┘   └──────────────┬──────────────┘
                                                               │  CurveFitter
                                                               ▼  (pixel/polygon/spline)
                                                ┌──────────────────────────────┐
                                     SVG  ◀──── │ VectorDoc ─ OptimizerPass* ─ │
                                                │            SvgWriter         │
                                                └──────────────────────────────┘