/image-to-svg

name: image-to-svg
description: Convert raster images (photos, paintings, illustrations, line art) into SVG vector reproductions. Use when the user uploads an image and asks to reproduce, vectorize, trace, or convert it to SVG. Also use when asked to decompose an image into shapes, create an SVG version of a picture, or faithfully reproduce artwork as vector graphics. Handles graphic/line-art inputs (Kandinsky, architectural drawings, ink work) via a compositional pipeline that extracts lines as SVG strokes. Do NOT use for creating original SVG illustrations from text descriptions — only for converting existing raster images.
metadata:
  version: 1.9.0

Image to SVG Reproduction

Convert raster images into faithful SVG reproductions using data-driven color quantization and contour extraction. **Never hand-draw shapes from visual interpretation** — always extract geometry from the actual pixel data.

Core Principle

**Trust the data, not your imagination.** Claude's visual interpretation of images is unreliable for precise color matching, shape positioning, and spatial relationships. Every shape, color, and position must come from computational analysis of the source pixels.

Quick Start

pip install opencv-python-headless scikit-image scipy scikit-learn --break-system-packages -q
apt-get install -y librsvg2-bin -qq

import sys
sys.path.insert(0, '/mnt/skills/user/image-to-svg/scripts')
from pipeline import image_to_svg

svg, flow = image_to_svg("source.jpg", mode="painting")

with open("output.svg", "w") as f:
    f.write(svg)

flow.summary()  # timing + status per step

Mode Selection

**Look at the image** and ask: "Does this have smooth gradients or hard edges?" Gradients → higher K. Hard edges → lower K.

| Mode | K | Best for | Dark shape gating | |------|---|----------|-------------------| | `"graphic"` | 28 | Logos, icons, Kandinsky, flat design | Loose (keeps thin lines) | | `"illustration"` | 40 | Comics, editorial, digital art | Moderate | | `"painting"` | 56 | Renaissance, Impressionist, watercolor | Standard | | `"photo"` | 64 | Portraits, landscapes, still life | Standard (prevents woodcut artifacts) |

Default is `"painting"`. When uncertain, start there.

**Tradeoffs**: K=64 produces ~2300 shapes (~1.2MB SVG) vs K=28's ~1000 shapes (~550KB), measured before v1.9.0's compact output, which is about 2.6x smaller (see Output Format). Processing time roughly doubles with K. The quality gain in tonal gradation is substantial for photos but wasted on graphic art.

All mode defaults (K, dark_lum, compactness_min, etc.) can be overridden via `**kwargs`:

svg, flow = image_to_svg("source.jpg", mode="graphic", K=12, min_area=20)

Compositional Pipeline (Line Art)

For images dominated by lines, strokes, and geometric shapes (Kandinsky, architectural drawings, technical illustrations, comic ink work), the standard fill-only pipeline produces jagged filled polygons instead of clean strokes. The compositional pipeline solves this with two passes:

**Pass 1 — Line Extraction**: Isolate thin features via morphological erosion → skeletonize to 1px centerlines → Hough line detection → merge collinear fragments → measure stroke width → sample color. Emits SVG `<line>` elements with `stroke-width`.

**Pass 2 — Fill Extraction**: Suppress line regions from image (replace with local background estimate via median blur) → run standard K-means quantization on the cleaned image → contour extraction → `<path>` fills.

**Composition**: Fills render behind strokes in layered `<g>` groups.

# Auto-detect: classifies input and routes automatically
svg, flow = image_to_svg("kandinsky.jpg", mode="graphic")

# Force compositional pipeline
svg, flow = image_to_svg("technical_drawing.png", mode="graphic", pipeline="compositional")

# Force fill-only (previous default behavior)
svg, flow = image_to_svg("photo.jpg", mode="painting", pipeline="fill")

**Pipeline selection** (`pipeline` parameter): | Value | Behavior | |-------|----------| | `"auto"` (default) | Classify input via edge density + luminance bimodality + Hough line count. Route to compositional for graphic art, fill-only for photos. | | `"fill"` | Force fill-only pipeline. Use for photos, paintings, or when compositional produces unwanted results. | | `"compositional"` | Force two-pass pipeline. Use for line art, technical drawings, or ink work where you know lines are present. |

**Auto-classification heuristics**: An image is classified as graphic when it has high edge density (>5% edge pixels) combined with bimodal luminance distribution (>0.35 bimodality coefficient), or high straight-line density (>3 Hough lines per 10k pixels).

**SVG output structure** (compositional):

<svg ...>
  <rect ... />        <!-- background -->
  <g id="fills" stroke-width="1" stroke-linejoin="round">  <!-- filled regions (painter's algorithm) -->
    <path class="c3" d="m12 40l5-2..z"/>
  </g>
  <g id="strokes">    <!-- line strokes (on top) -->
    <line x1="..." y1="..." x2="..." y2="..." stroke="#000" stroke-width="2.5" stroke-linecap="round"/>
  </g>
</svg>

**Stroke width control**: Measured perpendicular to each detected line, then scaled by 0.65x and capped at 4.5 SVG units. This prevents thick features from rendering as bloated strokes while keeping thin lines crisp.

**Current limitation — straight lines only**: Hough transform detects straight segments. Curved strokes (arcs, spirals) are not yet extracted as strokes — they fall through to the fill pass. Future work: `cv2.fitEllipse` or spline fitting on skeleton branches.

Palette Remapping (Warhol Effects)

Separate structure from color: K-means finds regions, palette remapping assigns bold colors. This produces screen-print / pop art effects.

# Named preset
svg, flow = image_to_svg("photo.jpg", mode="graphic", K=4, palette="pop")

# Custom hex list (darkest → lightest mapping order)
svg, flow = image_t