Documentation

Spryteo converts raster images and icons into clean, animateable SVG — traced, quantized, curve-fit, and semantically grouped, entirely offline. Install it, then reach for whichever surface fits your workflow.

Ways to use it

Same engine, same output, four entry points.

Install

Requires Node 18 or newer for the npm-distributed CLI/library/WASM builds. The Rust crates build with any current stable toolchain if you're working from source.

CLI

Point it at a raster file. It writes a grouped, animateable SVG next to the source, plus an optional JSON metadata sidecar.

Full flag reference:

A second subcommand, spryteo inspect, prints a human-readable summary of an SVG produced by convert — node/path counts, group tree, and (with --meta) centroids, bboxes and colours read back from the JSON sidecar.

$ spryteo inspect ./icon.svg --meta ./icon.json
  4 nodes · 2 groups · viewBox 0 0 64 64
  g-s-0
    #s-a1b2c3d4  circle  fill #e63946  area 812.4  bbox [12.0,12.0 52.0,52.0]

Modes

auto (the default) picks one of these for you; every heuristic is overridable with --mode.

Choosing a mode

Given an image in front of you, use this guide to select the right --mode:

How it works

Every surface runs the same eleven-stage pipeline over the same Rust engine — no surface has its own shortcuts or its own bugs.

A few of the pipeline's sharper edges, worth knowing if you're pushing tricky input through it:

Line-art binarization

Ink drawings first get a global Otsu threshold for solid strokes, then a capped Sauvola local threshold (computed over integral images, so it's O(n) not O(n·window²)) to rescue faint thin lines the global threshold would drop. Before committing to two layers, a duotone validation gate projects every pixel onto the ink↔paper axis in Lab space — if more than 2% of pixels fall too far off that axis, the image isn't actually two-tone and the pipeline falls back to full k-means colour quantization instead of flattening a colour photo into a black-and-white mess.

Straight-run recovery

Contour fitting doesn't force every edge through a cubic Bezier. Before fitting a run between two detected corners, a chord-straightness check (0.5px tolerance) tests whether every point on the run already lies within tolerance of the straight line between its endpoints — if so, it emits a plain LineTo instead of a curve, and a merge pass afterward collapses consecutive collinear LineTos into one. A traced square stays four straight edges at any smoothness setting, not four near-straight cubics with rounding error baked in.

True holes, correct paint order

Contour extraction (Suzuki-Abe border following over a marching-squares field) builds a real parent/child hole hierarchy per region. A letter "O" or a donut shape becomes one path with an inner subpath and fill-rule="evenodd" — not two overlapping opaque fills where the hole is really just a same-colour circle painted on top. Containment nesting also drives paint order in the scene graph, so a shape enclosed by another paints after its container rather than being silently occluded.

Determinism & testing

The same input and options produce byte-identical SVG on every run, on every machine. That's an engineering constraint, not a happy accident: no HashMap iteration reaches an output path anywhere in the pipeline, every sort is stable, and colour quantization's k-means++ seeding is fixed rather than time- or thread-seeded. You can verify it yourself — run the same conversion twice and diff the bytes.

Correctness is gated by a golden-corpus test harness (spryteo-cli/tests/corpus.rs) that renders every fixture's output back to a raster and compares it against the source with SSIM, alongside byte-budget and node-budget ceilings per fixture. Per-category SSIM gates: icons and pixel-art 0.92, line-art 0.90, photos 0.85, real-world mixed images 0.80. Goldens are regenerated with UPDATE_GOLDENS=1 cargo test -p spryteo-cli --release --test corpus and every regeneration is diffed by hand before it's trusted — an aggregate similarity score passing is necessary, never sufficient, so nothing gets accepted on the metric alone without a human looking at the rendered output.

Library (Node)

A native addon built with napi-rs — the real Rust engine in-process, no subprocess or WASM overhead. convert() is async; convertSync() blocks. Options are a JSON string merged against sensible defaults, so you only need to specify what you're overriding.

import { convert } from 'spryteo'

const { svg, meta } = await convert(
  buffer,
  JSON.stringify({ mode: 'icon', colors: 8, css: 'draw' })
)

// meta.nodes[i] = { id, bbox, centroid, area, fill, group, zOrder }
console.log(meta.stats) // { nodeCount, pathCount, byteCount }

Browser (WASM)

The same engine compiled to WebAssembly — this is what powers the live demo at the top of this site. Everything happens client-side; no image ever leaves the browser.

The WebAssembly build is not on npm yet. Build it from the repository with wasm-pack build bindings/wasm --target web --release, then import the generated bindings/wasm/pkg package.

import init, { convert_default } from 'spryteo-wasm'

await init('/spryteo_wasm_bg.wasm')
const bytes = new Uint8Array(await file.arrayBuffer())
const { svg, meta } = convert_default(bytes)

Use convert(bytes, optionsJson) instead of convert_default to pass the same JSON options object as the Node and CLI surfaces.

MCP server

Register Spryteo as an MCP server so AI agents can convert raster images and inspect vector output mid-conversation.

1. Install

cargo install spryteo-mcp

2. Configure

Add the server to your client configuration:

Config file locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux)
• Claude Code: ~/.claude.json (global) or .claude.json (project). Or add directly with one command:

  claude mcp add spryteo -- spryteo-mcp

• Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
• VS Code: .vscode/mcp.json (workspace) or user configuration in settings

3. Verify

Check that the server registered:

• Claude Desktop: Open a conversation and click the hammer icon; verify convert_image and inspect_svg appear under spryteo.
• Claude Code: Run claude mcp list; verify spryteo is listed with tools enabled.
• Cursor / VS Code: Open the agent panel; verify convert_image and inspect_svg appear in the active tool list.

4. Troubleshoot

• Command not found (spryteo-mcp): Cargo's bin directory is not on your PATH. It is ~/.cargo/bin by default; export it in your shell profile (export PATH="$HOME/.cargo/bin:$PATH"), or set "command" in your configuration file to the absolute path of spryteo-mcp.
• Server registers but tools do not appear: The client loads configuration only on startup. Completely quit and restart your editor or client application.
• No Rust toolchain (cargo: command not found): Install Rust from rustup.rs, open a new shell so ~/.cargo/bin is on PATH, then re-run cargo install spryteo-mcp.

Available tools

HTTP API

Planned, not yet shipped. spryteo-api exists in the workspace as a stub — until it lands, use the CLI, library, WASM build, or MCP server above.

Options reference

Every surface (CLI flags, library/WASM/MCP JSON options) shares the same underlying option set:

Colour & layering

colors targets a palette size for quantization — a ceiling, not a guarantee, since visually indistinguishable clusters are merged after quantization. layering (photo mode) chooses between stacked layers or cutout composition. gradients (auto | on | off) detects smooth colour gradients and emits an SVG <linearGradient>/<radialGradient> fill instead of a flat colour where the residual fits within a Lab-space tolerance — auto only attempts it in photo mode, since icons are almost always flat fills.

Geometry

tolerance is the curve-fit error budget in pixels — lower produces more path points and tighter fidelity. smoothness controls corner-preservation strength during Bezier fitting. turdsize discards regions below a minimum area (denoising). arcs allows emitting native SVG arc commands for near-circular/near-rectangular contours instead of Bezier approximations — this is what makes a traced circle come out as a real <circle> element.

Stroke / centerline mode

Setting stroke: true (or --stroke) bypasses colour quantization entirely and runs a dedicated centerline pipeline: binarize → skeletonize → build a stroke graph → prune spurious branches → traverse → smooth. Traversal looks for a true Eulerian path through the stroke graph via Hierholzer's algorithm — a graph with exactly two odd-degree nodes gets a virtual edge added between them to close it into a circuit first; graphs with more than two odd-degree junctions (genuine branching strokes) fall back to a greedy walk that emits separate paths per branch rather than one continuous stroke. Each path's width is the per-stroke median (variable-width splitting along a single stroke is not yet implemented). Output paths get pathLength="100" normalized for animation and are emitted with fill="none".

Semantic grouping

Shapes are grouped into a <g> tree two ways: containment-based (default — a shape nested inside another's bounding region becomes its child group under the smallest-area shape that fully contains it) and mask-guided, where you supply your own segmentation masks (e.g. from a model you're already running) and Spryteo groups traced contours by mask-overlap coverage. Spryteo does not bundle or run an ONNX/SAM model itself — mask-guided grouping is bring-your-own-masks by design: spryteo-semantic implements the grouping and assignment algorithm only, not segmentation inference.

Stable IDs

Every shape gets a content-derived ID (s-<8 hex chars>, a blake3 hash of the shape's geometry and fill) via id_style. Re-running on a slightly edited source keeps unchanged shapes' IDs identical — safe to reference a shape by ID across re-exports.

CSS presets

Three built-in animation presets bakeable via css / --css: draw (stroke-dashoffset reveal), fade (staggered opacity), pop (staggered scale-in). Or ignore them and animate the grouped output yourself — that's the point of shipping real groups instead of one flattened path.

Decode-time correctness

EXIF orientation is read and applied automatically — a photo shot sideways decodes upright, not rotated. Embedded ICC colour profiles are converted to sRGB before any other processing (via a pure-Rust colour-management stack, no LGPL dependency). Photos over 1600px on the long edge are automatically downscaled to a 1024px working size with Lanczos3 resampling before tracing, so a 4K upload doesn't blow the time budget — coordinates are still emitted against the correct output viewBox.

Limits

Decompression-bomb guards reject oversized input before allocating: max input bytes (8MB default), max pixel count (16MP default), and a hard 8192px dimension ceiling — all configurable, all enforced before the full decode where possible.

Recipes

Complete, runnable examples for common vectorization tasks:

$ spryteo convert logo.png -o logo.svg --mode icon --colors 4

$ spryteo convert icon.png -o icon.svg --mode icon --css pop --transform-origin centroid

$ spryteo convert player.png -o player.svg --mode pixel-art

$ spryteo convert signature.png -o signature.svg --mode line-art --stroke

$ spryteo convert photo.jpg -o photo.svg --mode photo --colors 16 --layering stacked --gradients auto

$ spryteo convert badge.png -o Badge.jsx --mode icon --jsx

$ spryteo sheet sheet.png -o ./icons/ --canonical-size 24 --name-prefix icon

$ spryteo convert glyph.png -o glyph.svg --mode icon --current-color

$ spryteo convert mark.png -o mark.svg --mode icon --json mark.json

Output & metadata

Every surface returns the same shape: an svg string and a meta sidecar built for programmatic and agent consumption, not just human eyeballing. meta.nodes is a flat list — one entry per shape — each with a stable id, bbox, centroid, area, resolved fill, its group key into the SVG's <g id=...> tree, zOrder, and a suggestedDrawOrder for animation sequencing. meta.stats gives node/path/byte counts for a quick sanity check without walking the tree.

Output anatomy

Spryteo produces structured vector scenes designed for CSS styling, animation, and programmatic inspection.

Group tree

The emitted SVG organizes paths into a semantic <g> hierarchy:

• Component grouping (--grouping component, default): Connected visual regions become groups (<g id="g-s-...">). Shapes nested entirely inside another shape's bounding contour (containment order) become child <g> elements under the enclosing shape.
• Semantic mask grouping (--grouping semantic): External segmentation masks group shapes under labeled containers (<g id="g-mask-<id>">).
• Flat structure (--grouping flat): Groups are omitted and all shapes render directly under <svg>.
• Paint order: Sibling groups and nodes follow document order (z-order), so background containers render first and nested details render on top.

ID scheme

Every shape element and group receives a deterministic identifier controlled by --id-style:

• Hash (--id-style hash, default): IDs format as s-<8 hex chars>, computed using blake3 over the shape's canonicalized coordinates (rounded to 3 decimals, -0.0 normalized to 0.0), primitive parameters, and fill color. Identical duplicate shapes append -2, -3 in document order. Unaltered shapes maintain identical IDs across re-runs.
• Sequential (--id-style sequential): Shapes are numbered monotonically in paint order (s-0, s-1, s-2).
• None (--id-style none): Omits id attributes entirely from elements and groups.
• Group IDs prefix the opening node ID (g-s-a1b2c3d4 or g-s-0) or the semantic mask ID (g-mask-<id>).

Metadata sidecar fields

When written via --json <path> or returned by the Node library, WASM build, or MCP server, the meta object contains:

Troubleshooting

Common symptoms, root causes, and CLI fixes:

Crate architecture

The engine is a Rust workspace of small, single-purpose crates — every surface (CLI, Node addon, WASM, MCP) links the same ones, so there's exactly one place each algorithm lives.

Built with