svgsmith

Agent-native, self-verifying raster→SVG vectorizer.

pip install svgsmith

svgsmith turns PNG/JPG images into editable SVG. It is built to be driven by an AI agent without a human in the loop: it picks the right tracing engine for the input, post-processes the result into clean editable layers, and verifies its own output by re-rasterizing the SVG and comparing it to the original — re-tuning until a quality threshold is met. Every run returns a structured JSON report so a calling agent can decide whether to accept, retry, or escalate.

It does not reinvent tracing. It wraps proven engines (VTracer for color, Potrace for line art) and adds the layer that is missing for agent use: routing, editable output, and a self-verification loop.

Status: released — svgsmith 0.1.0 is on PyPI. Engine routing, editable post-processing, the self-verify loop, the CLI + JSON report, SVG→PNG rasterization, and the vectorize skill are all in.

System dependencies

The line-art engine shells out to the Potrace binary (svgsmith does not bundle a Potrace Python binding). Install it from your package manager before use:

The self-verify loop rasterizes SVGs with CairoSVG, which needs the Cairo system library. Install both:

# Debian / Ubuntu
sudo apt-get install -y potrace libcairo2 libcairo2-dev
# macOS (Homebrew)
brew install potrace cairo

The color engine (VTracer) ships as a pinned PyPI wheel and needs no system package.

Installation

Requires Python 3.11+. Install the system dependencies above first, then svgsmith:

pip install svgsmith

From source

git clone https://github.com/realproject7/svgsmith
cd svgsmith
pip install .          # add ".[dev]" for the test/lint extras

Verify the install:

svgsmith --version
svgsmith convert path/to/image.png --out out.svg --report json

What makes it different

• Auto-routing — classifies the input (logo/icon vs illustration vs pixel art) and selects the engine + preset automatically. No tracer-flag expertise required.
• Low-res cartoon cleanup — low-resolution, JPEG/anti-aliased flat cartoon art is detected and supersampled before tracing, then snapped to a small fixed-K palette with a pure-black outline anchor — clean flat colors and smooth outlines instead of a scratchy, near-duplicate-color trace. Applied only to that input class (with an output-complexity fallback), so other art is unaffected.
• Editable output — instead of one monolithic <path>, output is grouped into <g> layers with simplified paths and a consolidated color palette.
• Self-verifying — converts, re-rasterizes, diffs against the original (SSIM), and re-tunes parameters until it converges on a quality target.
• Structured report — emits JSON (mode, engine, iterations, similarity score, warnings) so agents can branch programmatically.
• Local & private — runs fully offline; images never leave the machine.

Gallery

Each pair is the original raster (left) and the actual svgsmith SVG output (right), rendered at the same size.

	Original (PNG)	svgsmith (SVG)
Mascot · --detail high
Portrait · --detail high
Painterly · --detail clean

Usage

svgsmith convert input.png \
  --mode auto \         # auto | binary | color | pixel
  --quality 0.9 \       # target similarity (0–1), drives the verify loop
  --max-iters 4 \
  --editable \          # editable layered output (default on; --no-editable for raw)
  --out output.svg \
  --report json

Flags

For AI agents — mapping a user's request to flags

svgsmith is meant to be driven by an agent: the user describes what they want in plain language, and the agent translates that into flags. The flags compose — pick a mode (or let auto decide), then add refinements for what the user asked for.

Always pass --report json so the agent can read the result (mode used, similarity, warnings) and decide whether to accept, retry with a different flag, or tell the user why (e.g. a photo warning). The bundled vectorize skill encodes this exact mapping and the accept/retry logic.

Rasterize (SVG → PNG)

The inverse command renders an SVG back to a PNG (preview, thumbnail, round-trip):

svgsmith rasterize input.svg --out out.png        # intrinsic (viewBox) size
svgsmith rasterize input.svg --width 512           # fixed width
svgsmith rasterize input.svg --scale 2 --background white

Output

The SVG is responsive and scalable: it carries a viewBox and no fixed pixel dimensions (style="width:100%;height:100%", preserveAspectRatio="xMidYMid meet"), so it fits any container or browser window with its aspect ratio preserved — no overflow or scrollbars.

Exit codes

JSON report

{
  "output": "output.svg",
  "mode_used": "color",
  "engine": "vtracer",
  "preset": "illustration",
  "iterations": 2,
  "similarity": 0.93,
  "passed_threshold": true,
  "svg": { "paths": 84, "groups": 6, "colors": 12, "bytes": 14820 },
  "warnings": []
}

How the self-verify loop works

svgsmith doesn't trust a single trace. After producing an SVG it:

1. re-rasterizes the SVG back to a bitmap (via cairosvg) at the original resolution,
2. scores it against the source with SSIM — that score is similarity,
3. if it's below --quality, re-tunes the trace/post-process parameters and retries, up to --max-iters, and
4. returns the best-scoring result with the score in the report.

That closed loop is what lets an agent run svgsmith unsupervised: it gets a converged result and a confidence number, not a guess. For an end-to-end agent wrapper, see the vectorize skill.

License

MIT — see LICENSE.