png2svg

Files (21)

• SKILL.md
• conventions.md · references/
• examples.md · references/
• model.md · references/
• build_template.py · scripts/
• measure_template.py · scripts/
• __init__.py · scripts/png2svg/
• analyse.py · scripts/png2svg/
• cli.py · scripts/png2svg/
• compare.py · scripts/png2svg/
• curves.py · scripts/png2svg/
• geom.py · scripts/png2svg/
• measure.py · scripts/png2svg/
• model.py · scripts/png2svg/
• outline.py · scripts/png2svg/
• paint.py · scripts/png2svg/
• primitives.py · scripts/png2svg/
• render.py · scripts/png2svg/
• residuals.py · scripts/png2svg/
• svggen.py · scripts/png2svg/
• png2svg_cli.py · scripts/

SKILL.md (first lines)

# png2svg: geometry-first PNG -> SVG reconstruction

You are the editor in this loop. Deterministic commands measure, render, and
score; you make the design judgments; shape decomposition, layering, paint
model; and iterate until the metrics converge.

This is reconstruction, not tracing. The output is the handful of shapes a
designer would have drawn, not a contour fitted to pixels.

The visual loop is deliberate. `check` renders the current SVG and writes a
50/50 reference/render `overlay.png`; inspect that together with the edge and
colour residuals, change the decomposition or constraints, and repeat. The
library makes measurements reproducible. It cannot decide whether a meeting
of two edges is a fillet, an overlap, or a coincidence.

## 0. Triage; is this image suitable?

**Look at the image first.** Proceed when it reads as designer-built
geometry: flat or gradient fills, crisp edges, shapes decomposable into
lines, arcs and Béziers.

Rule of thumb: **if it could have been built in Figma from shapes and
gradients, it is recoverable.** There are three outcomes, and picking the
right one up front decides which targets you are aiming at:

| the source | aim for | judge by |
|---|---|---|
| flat or gradient fills, crisp edges | an exact reconstruction | IoU, edge distance, ΔE |
| a render with grain, brushed metal, shadows, glow | **structure and shading; drop the texture** | IoU and `deltaE_lowfreq` |
| photos, painterly art, anything under ~100px | decline |; |

The middle case is the one to get right rather than refuse. A textured
source disagrees with **itself** by more than any vector can match, so
per-pixel ΔE will report failure for a reconstruction that reads correctly
at a glance. `check` reports `texture_std`; around 1-2 for clean vector
art, 10+ for a textured render. When it is high, reconstruct the structure
and the large-scale shading, drop grain and fine detail deliberately, say so
in the model notes, and judge by the low-frequency figures.

For the third case say so plainly and suggest `vtracer` or `potrace`, which
do the different job of fitting contours to pixels.

## 1. Setup

Everything runs through one entry point: `scripts/png2svg_cli.py` in this
skill's directory. On first run uv builds a cached environment from the
script's own dependency block; there is nothing to install.

Check for uv before starting:

```bash
command -v uv
uv --version
```

If uv is missing, stop and ask the user to install it from
https://docs.astral.sh/uv/getting-started/installation/. Do not require a
separate Python installation; uv provisions a compatible interpreter.

Below, `$SKILL` stands for this skill's directory (the folder containing this
file). **Substitute the literal path**: each command may run in a fresh
shell, so an assignment made in one will not survive to the next.

```bash
uv run --no-project "$SKILL/scripts/png2svg_cli.py" init INPUT.png --project work/<name>
uv run --no-project "$SKILL/scripts/png2svg_cli.py" analyse work/<name>
```

`init` copies the source and estimates the background from a 2px border
median. `analyse` writes `analysis/features.json` and `analysis/overlay.png`:
components with bboxes, boundary segments (line / arc / corner / curve with
fitted params and errors), and a paint probe per component:

- `flat`; solid colour
- `linear`; gradient, dominant direction given
- `angular`; conic sweep, centre given
- `complex`; layered or occluded paint; your judgment needed

Each component also carries a `structure` block, and `analyse` prints its
`hint` line if it found anything: repeated spacings between parallel edges,
exact 180°/mirror symmetry with its centre, and corners far tighter than the
shape's usual radius. **Read that line first**; it is the fastest available
answer to the route question in §2, and every number in it is one you would
otherwise derive by hand. A repeated spacing or a tight corner means
overlapping primitives; a symmetry centre means parameters you can delete
rather than fit.

It reports only what it measured. Silence means nothing was found, not that
the mark is simple.

**Treat every coordinate in features.json as a ±0.5px proposal**, and read
`overlay.png` next to the source before deciding anything. `analyse` is
fooled by watermarks and compression artefacts.

## 2. Decompose; and pick your route

Decide the structure before measuring anything: how many overlapping
primitives, what occludes what, where the paint seams are.

A hard colour boundary **inside** one silhouette usually means two
overlapping shapes; the seam is the top shape's edge, not a gradient stop,
and it often passes through an arc centre. Getting this right is most of the
work; everything downstream is arithmetic.

This decision also picks which of **two routes** you measure with. They are
siblings, not a default and a fallback; reaching for the wrong one costs you
either a pile of nodes or an afternoon:

| what you are looking at | route | §  |
|---|---|---|
| one silhouette whose boundary **is** the design; a letterform, a swoosh, an organic blob | **trace it** | 3a |
| overlapping filled primitives; bars, rects, discs, capsules; where the union's boundary is a *by-product* of where they landed | **fit the primitives** | 3b |

`analyse`'s `structure` hint checks the first two of these for you. Three
tells, any one of which is enough:

- **A corner that is an intersection, not a fillet.** Walk the silhouette and
  ask of each corner: did a designer round this, or did it appear because two
  shapes crossed? Sharp spikes and tiny radii next to generous ones mean

From iannuttall/skills, MIT.

More from iannuttall/skills