| name | vectorize |
| description | Convert a raster image (PNG/JPG) into clean, editable SVG using the svgsmith CLI. Use when the user wants to vectorize, trace, or turn a bitmap/logo/icon/illustration/pixel-art image into SVG. Picks the engine by intent, self-verifies the output quality, and retries before reporting. |
vectorize
Turn a raster image into an editable SVG by driving the local svgsmith CLI, then
verify the result and decide whether to accept, retry, or report a limitation — without
asking the user to tune tracer flags.
Prerequisite
svgsmith must be installed and on PATH (svgsmith --help should work). If it is not,
tell the user to install it (pip install svgsmith, plus the Potrace system binary for
line-art mode: brew install potrace / apt-get install -y potrace) and stop.
Step 1 — Map intent to flags
Choose --mode and --quality from what the user asked for. When unsure, use auto.
| User intent | Flags |
|---|
| "clean logo", "crisp icon", line art, black & white | --mode binary --quality 0.95 |
| "trace this illustration", colorful flat art, graphic | --mode color |
| "pixel art", sprite, low-res blocky image | --mode pixel |
| anything unspecified / "vectorize this" | --mode auto |
Then add refinement flags based on what the user wants out of it (these compose):
| User wants | Add flag |
|---|
| "clean / flat / solid background", "remove the background texture", "just the subject on a plain color", "isolate the cat/logo/person" | --solid-background |
"make the background white / <color>", "change / swap the background color" | --background white |
| "cut it out", "transparent background", "remove the background entirely", "just the subject, no background" | --transparent-background |
| "maximum detail", "keep every detail / texture / shading" | --detail high |
| "cleaner / tidier", "less noise / grain", "smooth it out a bit" | --detail clean |
| "poster / flat / bold graphic", "simple flat colors", "minimalist" | --detail poster |
| "it looks scratchy / shattered / broken", "glossy or shiny art isn't clean", "flatten the shading" | --flatten-shading |
| "even / consistent outline", "uniform line weight" (only for art that already has a dark outline) | --uniform-outline |
| "keep the raw / rough / hand-drawn look", "don't smooth it" | --no-smooth |
--detail is the dial between fidelity and a clean/flat look; default normal is balanced.
Flags compose, e.g. "a detailed cat on a clean solid background" → --detail high --solid-background.
Always pass --report json and a sensible --out (default: input path with .svg).
Step 2 — Run the CLI
svgsmith convert <input> --mode <mode> [--quality <q>] --out <output.svg> --report json
stdout is a single JSON object (the only thing on stdout). Parse it. Exit codes:
0 = success (similarity >= quality), 2 = SVG produced but below the quality target,
1 = hard error.
The report fields: output, mode_used, engine, preset, iterations, similarity, passed_threshold, svg:{paths,groups,colors,bytes}, warnings[].
Step 3 — Decide: accept / retry / report
passed_threshold: true (exit 0) → accept. Report the output path and the
similarity score to the user.- Below threshold (exit 2), first attempt → retry once, escalating effort:
- if
mode_used was auto, re-run with the explicit mode that fits the image
(binary for sharp/flat, color for many colors);
- otherwise raise
--max-iters (e.g. to 8) and/or lower --quality toward a realistic
target for the content. If the report warnings mention photographic gradients, do
not chase a high score — photos vectorize poorly by nature.
- Still below threshold after the retry → report honestly. Give the user the SVG
anyway (it is still produced), the achieved
similarity, and the reason from warnings.
Do not silently present a poor result as good.
- Exit 1 (hard error) → surface the stderr message; check the prerequisite (missing
potrace binary is the most common cause).
Step 4 — Visual self-check
Before declaring success, look at the output: open/render the produced SVG and compare
it to the source image. Confirm the shapes, colors, and proportions match; note any obvious
defects (lost detail, wrong colors, broken paths). If the SVG looks wrong despite a passing
score, say so — the score is a guide, not a guarantee.
Notes
--editable is on by default (grouped <g> layers, simplified paths, consolidated
palette). Only pass --no-editable if the user explicitly wants the raw traced output.- Everything runs locally; the image never leaves the machine.
