bitmap-to-vector

The SVG is a flat icon-ready vector. The paths trace the subject (the dark ink, the logo shape, the silhouette) as filled regions. The background is transparent. fill="currentColor" means the icon inherits whatever CSS color is set on its parent — white text context = white icon, dark text context = dark icon.

This is the same format as any standard inline SVG icon (GitHub, Twitter, etc.). It works at any size, in any color, in light or dark themes.

Workflow

1. Find the image

The user will upload an image, reference a file on disk, or paste one inline. Locate it — check uploads, the working directory, or ask if you can't find it.

2. Run the tracer

python3 SKILL_DIR/scripts/trace.py INPUT_IMAGE OUTPUT.svg --preview 512

Replace SKILL_DIR with the actual path to this skill directory. The --preview 512 flag renders a PNG alongside the SVG so you can visually verify the result.

For most images, the defaults work well. The script auto-detects:

• Threshold via Otsu's method (adaptive to the image's histogram)
• Polarity by checking border pixels (figures out light-on-dark vs dark-on-light)
• Bounding rectangle removal — potrace sometimes wraps output in a full-image rectangle that inverts the fill. The script detects and strips this automatically.

3. Check the preview

Read the generated preview PNG and look at it. The preview always renders black shapes on a white background — it shows exactly what the traced paths look like as a dark icon on a light page. The JSON output also includes a polarity field describing how the script decided what to trace.

You're checking for:

• The black shapes in the preview ARE the subject (the icon, logo, figure) — not a filled rectangle with the subject cut out as a hole
• All the important features came through (nothing missing)
• No noise or texture artifacts crept in

If you see a filled rectangle with the subject as negative space, something went wrong with the bounding rect detection — see "Adjust if needed" below.

4. Adjust if needed

If the first pass isn't right, tune with flags:

5. Place the SVG

Put it where the user expects:

• Their project's asset directory (src/assets/, public/icons/, etc.)
• The working directory / Desktop
• Wherever they tell you

Clean up the preview PNG after you've verified the trace — the user only needs the SVG.

6. Using the SVG in code

The SVG uses fill="currentColor" — it only works correctly when the browser can resolve that value. This is critical for getting the icon to render as expected.

How to use it:

Do NOT use <img> or framework image components for currentColor SVGs. This is the most common mistake. If you need to use <img>, re-run the tracer with --fill black or --fill white to bake in a fixed color.

For React/Next.js, the CSS mask pattern is clean and minimal:

.icon {
  width: 24px;
  height: 24px;
  background: currentColor;
  mask: url('/icon.svg') center / contain no-repeat;
  -webkit-mask: url('/icon.svg') center / contain no-repeat;
}

Script Options

python3 trace.py INPUT OUTPUT.svg [options]

  --threshold N      Brightness cutoff 0-255 (default: auto)
  --invert           Trace dark regions instead of light
  --detail LEVEL     "high" / "medium" / "low" — presets for detail vs cleanliness
  --turdsize N       Suppress features < N pixels (default: 50)
  --smoothing N      Curve smoothness 0.0-1.34 (default: 1.0)
  --blur N           Gaussian blur kernel size (default: 5)
  --no-crop          Keep original image dimensions
  --padding N        Content padding in px (default: 10)
  --preview N        Render a PNG preview at width N
  --fill VALUE       SVG fill attribute (default: "currentColor")

Notes on the Output

• fill="currentColor" — the SVG inherits whatever text color is set in CSS context. Perfect for icons that need to work in light and dark themes. Override with --fill black or --fill "#e00" for a fixed color.
• Single <path> element with fill-rule="evenodd" — holes (eye sockets, letter counters, cutouts) render correctly without extra markup.
• No bounding rectangle — the script auto-strips any full-viewBox rectangle that potrace generates, so the paths are just the subject with transparent background.
• Scalable — viewBox is set to content dimensions, so the SVG works at any size from favicon to billboard.
• ~5-15KB for typical icons. Complex illustrations will be larger but still much smaller than the source bitmap.

Dependencies

The script installs these automatically on first run:

• opencv-python-headless — image loading and preprocessing
• potracer — Python bindings for potrace
• cairosvg — PNG preview rendering (only needed with --preview)

If auto-install fails: pip install opencv-python-headless potracer cairosvg --break-system-packages