vectors

Topics: svg, vectorization, rust, cli, wasm, mcp

Live demo: https://hieudoanm.github.io/vectors/

Turn PNG and JPEG images into clean SVG paths — and rasterize SVG back to PNG at any size — entirely offline.

vectors is a classical raster-to-vector tracer written from scratch in Rust. It quantizes an image into a palette, segments pixels into regions, walks their boundaries, simplifies the result, fits Bézier curves, and emits SVG. No machine-learning models, no network calls, no service dependency — and the same input always produces byte-identical output.

The tracer ships as a CLI, an HTTP API, an MCP server, a Rust library (compiled to WebAssembly for the web app), and a Next.js landing page with an in-browser converter.

Table of Contents

• vectors
  • Table of Contents
  • The Problem
  • The Solution
  • Features
    • Tracing
    • Surfaces
    • SVG → PNG
    • Quality harness (optional)
  • Key Benefits
  • Get Started
    • Prerequisites
    • Build the CLI
    • Convert your first image
    • Build everything
  • CLI
    • Examples
  • How It Works
  • Measuring Quality
  • Crates and Packages
  • Use Cases
  • Why This Project?
  • Project Status and Trust
  • Community and Contributions
  • Call to Action
  • License

The Problem

Turning a raster logo back into usable vector paths is usually either an online upload form, a heavyweight design tool, or a black box that changes its output between runs. A practical tracer needs to:

• Accept ordinary PNG and JPEG input without a pre-processing step.
• Handle colour palettes, transparency, holes, and anti-aliasing.
• Produce editable SVG — path elements with fill, not an embedded bitmap.
• Be deterministic, so a committed fixture or baseline does not churn.
• Work offline as a single binary, a library, and a server, from the same code.
• Go the other way too: render an SVG to a sized PNG for icons and previews.

vectors is built around those constraints.

The Solution

vectors runs one linear pipeline — raster → preprocess → segment → contour → simplify → Bézier → vector model → SVG — where each stage consumes the previous stage's type and knows nothing about how the next one is rendered. The tracer is deterministic by construction (no RNG, no hash-order dependence), and is measured by rasterizing its own SVG output with an independent renderer rather than by eyeballing the paths.

The inverse direction, SVG → PNG, parses the document with resvg, draws it straight into a straight-alpha buffer, and encodes it with image. Width and height are explicit flags, so the same binary can produce a 512 px icon or a 4096 px comparison raster.

Features

Tracing

• Palette and binary modes — median-cut colour quantization (default 8 colours) or a single luminance threshold for black-and-white output.
• 8-connected segmentation — flood fill per region, with an area filter for anti-aliasing specks.
• Proper holes — outer contour plus holes per path, emitted with fill-rule="evenodd".
• Douglas–Peucker simplification — fewer points without moving the shape.
• Least-squares Bézier fitting — fit–measure–split, tunable per pixel.
• Debug artefacts — --debug-dir writes the quantized image, regions, curves, and curve SVG so you can see which stage went wrong.

Surfaces

• CLI — one command for a single file; omit the output path to stream SVG to stdout.
• HTTP API — vectors serve exposes /health, /info, and POST /vectors (multipart or URL-safe base64), with per-request overrides.
• MCP server — vectors mcp serve speaks newline-delimited JSON-RPC on stdio and advertises a vectors_trace tool for agent clients.
• Library — trace, to_svg, Raster, TraceConfig, and SvgOptions; VectorImage is SVG-independent so another serializer is additive.
• Web app — a Next.js landing page with an in-browser converter that runs the same tracer compiled to WebAssembly; conversion happens entirely client-side.

SVG → PNG

• Exact or proportional sizing — --width alone preserves the aspect ratio; --width and --height together set the exact grid.
• Transparent by default — add --background '#ffffff' to composite an opaque backdrop.
• No extra tooling — resvg comes from the module's raster feature, not from a system package.

Quality harness (optional)

• Measured accuracy — --features eval adds eval, baseline, golden, and sweep subcommands that rasterize the emitted SVG, compare it to the source, and score MAE, PSNR, SSIM, edge agreement, primitives, and bytes.
• Committed baselines — one row per image, so a regression names the image that broke instead of hiding in an average.
• Parameter sweeps — explore colors, threshold, tolerances, and area limits across the golden suite.

This is the beginning of the README. Read the rest at the original. Read the full README ↗