Vectormark idealize

Idealize a logo into SVG with vectormark

vectormark is a deterministic raster-logo → SVG idealizer. This skill takes a raster image — one the user supplies, or one you just generated — and produces a clean, editable, symmetric SVG by running the vectormark command-line tool.

The handoff is a file path, not image bytes: you save the raster to a file, then point the CLI at it. (A path is short text you can pass between steps; raw image bytes are not.)

Step 1 — Decide how to run vectormark

vectormark is published on PyPI. Pick the invocation that fits the environment; you will reuse it as <VM> in Step 3.

Preferred — uvx (no install, ephemeral). If uv is available (uv --version succeeds), run vectormark with no persistent install — uvx fetches and caches it on first use, later runs reuse the cache. Prefer the scoring extra, which enables render-ΔE candidate scoring for the best output:

# <VM> = full, with scoring (preferred)
uvx --from "vectormark[scoring]" vectormark
# <VM> = minimal (no resvg-py; cascade-priority pick, warns once)
uvx vectormark

Fallback — pip install (persistent). If uv is not available but Python ≥ 3.12 and pip are, install once, then call vectormark directly:

pip install "vectormark[scoring]"   # or: pip install vectormark   (minimal)
# <VM> = vectormark

If the scoring extra can't be fetched (a locked-down sandbox with no resvg-py wheel), drop [scoring] — vectormark still works, just with the cascade pick.

Notes

• Requires Python ≥ 3.12. vectormark's own wheel is pure-Python; its dependencies and the scoring extra ship prebuilt manylinux/musllinux/ macOS/Windows wheels, so this works in any networked environment.
• No PyPI? Install from the git source instead. Minimal: uvx --from "git+https://github.com/pradeepmouli/vectormark" vectormark. With scoring, use the PEP 508 form so the extra is carried: uvx --from "vectormark[scoring] @ git+https://github.com/pradeepmouli/vectormark" vectormark (same "<spec> @ git+…" form for pip install).

Step 2 — Get the raster onto disk

You need a PNG/JPG file path. Two cases:

• The user already gave you an image file → use that path; skip to Step 3.
• You are generating the logo (image-gen tool / model) → generate it, then save the bytes to a file, e.g. /tmp/vm-logo.png. Some hosts already expose the generated image as a file in the working sandbox; if so, use that path. Otherwise write the bytes out explicitly before Step 3.

The CLI reads the file from disk, so the generator and vectormark must share a filesystem — true when both run locally, or both run inside the same sandbox.

Step 3 — Run vectormark

Use the <VM> invocation you chose in Step 1:

# preferred (uvx + scoring):
uvx --from "vectormark[scoring]" vectormark /tmp/vm-logo.png -o /tmp/vm-logo.svg --colors 16
# or, after a pip install:
vectormark /tmp/vm-logo.png -o /tmp/vm-logo.svg --colors 16

The SVG is written to -o; omit -o to print it to stdout (handy when you want to read the SVG back to the user directly).

Useful flags (all optional):

Flag	Default	Meaning
-o, --output	stdout	write the SVG to this path
--colors	16	maximum palette colors
--epsilon	1.5	primitive/polygon recognition tolerance, px
--max-error	1.0	Bézier fit tolerance, px
--flatten	off	emit plain paths instead of native primitives + <use>
--no-symmetry	off	disable symmetry detection

Guidance: start with defaults. Raise --colors for richer marks; lower it to force a flatter palette. Raise --epsilon if curves are coming out too busy. Use --flatten only if the consumer can't handle <use>/native primitives.

Step 3b — Explore looks across the geometry space (optional)

When the user wants to compare options or pick a look, --variants idealizes the mark across an epsilon × max_error grid and writes the set to a directory — no need to hand-tune flags one run at a time:

# 3×3 default grid -> ./<stem>-variants/
<VM> /tmp/vm-logo.png --variants --out-dir /tmp/vm-looks
# custom axes (any grid):
<VM> /tmp/vm-logo.png --variants --out-dir /tmp/vm-looks --epsilons 0.5,2,4 --max-errors 0.5,2
# also overlay the detected symmetry axis on each tile (a diagnostic view):
<VM> /tmp/vm-logo.png --variants --axes --out-dir /tmp/vm-looks

It writes one variant-e<ε>-m<max_error>.svg per cell, a manifest.json (each variant's params and the fitter strategies it actually used), and — when the scoring extra is installed — an annotated contact-sheet.png. Show the user the contact sheet (or summarize the manifest); let them pick a cell; then deliver that variant's SVG as the result.

The contact-sheet.png here is a real artifact the tool produced — that is exactly what Step 4's "don't fabricate a contact sheet" rule does NOT forbid. Show vectormark's real sheet; never invent one.

Step 4 — Deliver the result

• For a single run, the deliverable is the SVG itself — report it and its output path, nothing more. vectormark emits one SVG string; do not fabricate optimization stats, file-size tables, color-swatch grids, "production ready" checklists, or a multi-panel contact sheet around it. Those are invented, not produced by the tool, and only add noise. (The real contact-sheet.png from --variants is a different thing — it's an actual tool output; show that.)
• If you can't run vectormark, do not try to draw the SVG yourself. Never hand-author, guess, or hallucinate an output. If the tool didn't actually run (not installed, no network, an error, or you only have the input image), say so and stop — a fabricated SVG is worse than none, and only vectormark's real output is meaningful here.
• To preview, open the file (open /tmp/vm-logo.svg on macOS, xdg-open on Linux) or read the SVG text back to the user — an <svg> document renders directly in any browser or markdown preview.

Tips

• vectormark is deterministic: same input + flags → same SVG every time.
• It targets flat-color logos/icons/emblems. Photographic or heavily-gradient images are out of scope and will produce poor results.
• If you generated the image, keep the prompt simple and the mark flat — that is what idealizes cleanly.