DOCSEARCHbyAlgolia
Submit Docs

VTracer

repository·master·Indexed 27 days ago

https://github.com/visioncortex/vtracer

A high-performance raster-to-vector graphics converter that transforms images (JPG, PNG, etc.) into compact SVG files. VTracer 1.0 features a modular architecture with pluggable frontends, curve-fitting backends, and color fitting. It is available as a CLI tool, a Rust library, and provides language bindings for Python and Node.js (via WebAssembly).

Tokens
13.9K
Snippets
19
Records
82
Agent score
85%

What's inside vtracer

  1. Overview of VTracer 1.0 Architecture

    master

    VTracer 1.0 is a vectorization framework designed to be more modular than previous versions. It moves from a hardcoded pipeline to a pluggable architecture consisting of several distinct stages:

    1. Frontend: Algorithms that produce clusters or segmentation from a raster image.
    2. Curve fitting backend: Pluggable polyline-to-curve fitters (supporting pixel, polygon, spline, and future formats).
    3. Color fitting: Mapping cluster colors to final paints, supporting custom fixed palettes, quantization, and merging.
    4. Optimizer: A pass pipeline that reduces output size using relative path syntax, shorthand commands, and precision reduction.
    5. Compositing: Supports two modes:
      • Stacked: Closed outlines.
      • Mosaic: A true, gapless tessellation using boundary-graph tracing and shared-edge curve fitting.

    Everything except image file I/O is designed to compile to wasm32-unknown-unknown.

  2. Understand the difference between Stacked Mode and Cutout Mode

    master

    In vtracer, there is a distinction between the legacy 'hierarchical cutout' and the new 'cutout' algorithm:

    • Hierarchical Cutout (Legacy): A 'fake' cutout that re-renders the clustered image, re-clusters it, and then re-traces it.
    • Cutout (New): A topological mosaic approach.

    Note that these two algorithms are deliberately different and are not expected to produce identical results. If you are looking for the behavior of the 0.6.x pipeline, you should use Stacked Mode.

  3. Understand the vtracer Workspace Layout and Dependencies

    master

    The vtracer project is organized into several crates to separate core logic from platform-specific bindings:

    • vtracer-core: The core framework. It is WASM-safe and contains no file/image I/O or CLI/Python dependencies. It houses the IR, stage traits, and the pipeline driver.
    • vtracer: The main publishable crate. It re-exports vtracer-core and provides image I/O (via the image crate), a clap 4 CLI, and Python bindings (via the python-binding feature).
    • vtracer-wasm: WASM-bindgen bindings over vtracer-core.
    • nodejs/: An npm package providing a TypeScript wrapper, embedded WASM, and a sharp reader.

    Note for library users: You only need to depend on the vtracer crate, as it re-exports vtracer-core.

  4. Understand Mosaic Mode for seam-free vectorization

    master

    Mosaic Mode is a topological pipeline designed to produce seam-free vector cutouts. Unlike standard tracing where neighbors are smoothed independently (which can cause gaps or overlaps), Mosaic Mode ensures that every boundary curve exists exactly once. Adjacent regions reference the same fitted geometric object, one traversed forward and the other reversed. This guarantees that the serialized coordinates are identical on both sides, preventing T-junction cracks and gaps.

    The pipeline follows these stages:

    1. Boundary-graph extraction: Extracts nodes, shared segments, and rings using integer arithmetic.
    2. Face assembly: Assembles per-region contours as cycles of segments.
    3. Fitting: Fits each segment exactly once using a pluggable backend (Pixel, Polygon, or Spline), with endpoints pinned to lattice nodes.
    4. Composition: Composes per-region SVG paths from the shared fitted segments.

  5. Build and run the VTracer Web App in development mode

    master

    To run the VTracer web application locally for development, follow these steps:

    1. Navigate to the app directory and install npm dependencies.
    2. Build the WebAssembly component using wasm-pack.
    3. Start the development server.

    The application will be available at http://localhost:8080/.

    cd app
npm install
wasm-pack build
npm run start

  7. Use the VTracer CLI

    master

    The CLI tool converts raster images to SVG. You can provide input and output paths as positional arguments or via named flags (--input, --output).

    Common usage patterns:

    • Simplest form: ./vtracer input.jpg output.svg
    • Black & white line art: Use --preset bw
    • Scanned art with uneven lighting: Use --clustering bw --adaptive
    • Seam-free mosaic (gapless tessellation): Use --hierarchical cutout
    • Watershed region forming: Use --clustering watershed --watershed-detail <0..=255>
    • Fixed color palette: Use --palette '#hex1,#hex2,...'
    # simplest form
./vtracer input.jpg output.svg

# black & white line art
./vtracer input.jpg output.svg --preset bw

# scanned/photographed line art with uneven lighting
./vtracer scan.jpg output.svg --clustering bw --adaptive

# seam-free mosaic (gapless tessellation)
./vtracer input.jpg output.svg --hierarchical cutout

# watershed region forming, cut to taste
./vtracer photo.jpg output.svg --clustering watershed --watershed-detail 192

# constrain to a fixed palette
./vtracer input.jpg output.svg --palette '#1b1b1b,#e0c088,#5a7d3c,#8fb0d0'

  8. Use vtracer in Python via PyPI

    master

    The Python bindings are available via the vtracer package on PyPI. You can convert images to SVG using two primary functions. Note that hierarchical='cutout' now produces a true mosaic.

    Key Functions:

    • convert_image_to_svg_py(image_path, out_path, **config): Converts an image file at image_path and saves the result to out_path.
    • convert_raw_image_to_svg(img_bytes, img_format=None, **config) -> str: Converts raw image bytes directly to an SVG string.

    New Configuration Options (kwargs):

    • palette: A list[str] of hex color strings.
    • optimize: An integer for optimization level.
    • hierarchical: Set to 'cutout' for true mosaic output.

  9. Reproduce vtracer 0.6.x vs 1.0 equivalence testing

    master

    To reproduce the equivalence verification between the 0.6.x cmdapp and the new vtracer-cli:

    1. Ensure cmdapp/Cargo.toml uses matched dependencies (image = "0.25" and visioncortex = { version = "0.9", path = "../../visioncortex").
    2. Build both binaries:
      cargo build --release --manifest-path cmdapp/Cargo.toml
cargo build --release -p vtracer-cli
    3. Run both binaries in stacked mode using --path-precision 8. For the new version, also use --optimize 0.
    4. Harness Caveats for 0.6.x:
      • Use --mode (do not use the shorthand -m).
      • Use --colormode bw for black and white (the value binary may fall through to color in 0.6.x).
      • In 0.6.x, spline mode with pixel maps to PathSimplifyMode::None.
    cargo build --release --manifest-path cmdapp/Cargo.toml
cargo build --release -p vtracer-cli

  12. Install dependencies for VTracer Web App

    master

    Before building the web application, ensure you have the following system dependencies and tools installed:

    1. System Tools: git and build-essential (on Debian/Ubuntu-based systems).
    2. Rust: Install via the official Rust installer.
    3. wasm-pack: Required for building WebAssembly modules.
    4. Node.js (via nvm): Use nvm to manage Node.js versions.
    sudo apt install git build-essential
# Follow official installers for Rust and wasm-pack
nvm install --lts