Morphēa

Reveal the shape within.

Morphēa turns bitmap artwork into clean, editable SVG geometry. It is for the moment after conversion, when you open the file and still want to understand what you are looking at. Icons, logos, illustrations, UI captures, and technical graphics should come out as shapes a person can inspect, select, adjust, and reuse.

Most vectorizers trace the edge of colored pixels. That can make a picture look roughly right, but the SVG often turns into a pile of tiny, awkward paths. It looks converted, not understood. Morphēa tries to recover the form behind the pixels: circles stay circles, strokes stay strokes, perspective tiles stay quads, and repeated structures become coherent scene groups instead of noisy fragments.

The idea in plain language

Imagine taking a screenshot of a simple icon and asking for an SVG. A normal tracer may outline every jagged edge it sees. The first preview can look fine. Then you try to edit it. A circle is dozens of curve points. A straight line is a filled blob. One simple shape is split across several layers.

Morphēa takes a different bet. It asks: "What shape was probably intended here?" If the evidence points to a circle, it prefers an SVG circle. If the image shows a clean stroke, it prefers an editable stroke. If a table or perspective grid is visible, it tries to keep that structure instead of flattening it into random polygons.

That is the useful part. Morphēa is not chasing a pretty preview at any cost. It is trying to produce an SVG that still makes sense after it is generated.

Why this is different

AI-generated artwork and screenshots often look simple enough to vectorize, but common tracing output is hard to work with:

• simple circles become lumpy Bezier paths;
• clean strokes become filled blobs;
• white cut-outs become unstructured holes;
• perspective grids become many unrelated polygons;
• antialiasing and palette drift create too many layers.

Morphēa treats those cases as shape-reconstruction problems. Pixel fidelity still matters, but it is balanced against editability, primitive quality, layer fragmentation, and scene semantics.

This makes Morphēa strongest when the image contains deliberate graphic structure: icons, diagrams, UI controls, technical drawings, clean illustration regions, and generated artwork with simple shape language. It is not the best tool for every image. For photos or painterly detail, a pure tracer can still be the better choice because matching the pixels matters more than editing the result.

How it works

At a high level, Morphēa does four things:

1. It analyzes the bitmap: colors, transparency, connected regions, and likely shape boundaries.
2. It searches for simple editable primitives before falling back to generic paths.
3. It scores candidates by both visual similarity and editability, so a slightly cleaner circle can beat a pixel-perfect but uneditable outline.
4. It writes inspectable artifacts: SVG, scene manifest, previews, configs, and reports that explain what was recognized, skipped, refined, or gated.

The project also includes a learning loop. Morphēa can generate synthetic training data, train its own primitive classifier, harvest high-confidence examples from its own runs, ask for human review, and retrain from accepted labels. The model is there to help the shape reconstruction, not to replace the evidence. If a label is going to teach the system, the run should be reviewable.

For a fuller explanation, see AI in Morphēa.

What works today

The current baseline implements:

• primitive detection for circles, dots, rings, strokes, arcs, rectangles, rounded rectangles, perspective quads, and grid-like tile groups;
• editable white cut-out strokes, with an optional negative-mask SVG export strategy;
• real-image runtime controls for alpha handling, palette quantization, analysis resizing, component deferral, and timeouts;
• timestamped run directories with SVG, manifest, preview, config, palette, mask summaries, and Markdown/HTML reports;
• synthetic dataset generation and primitive classifier training, including an optional MLX path when the local environment supports it;
• curated real-image checks, snapshots, and profile reports;
• reviewed pseudo-label harvesting, review/apply-review, retraining gates, and self-learning cycles;
• structure-preserving local and soft-raster refinement.

See docs/milestones.md for the implemented baseline and the longer roadmap.

When to use it

Use Morphēa when you want:

• an SVG you can edit without fighting hundreds of accidental points;
• simple shapes to remain simple;
• local, inspectable outputs instead of a black-box answer;
• reports that explain quality, failures, and review decisions;
• a research workflow for improving recognition with reviewed examples.

Do not expect it to be a universal image-to-vector replacement. It is designed around structured artwork first, and it deliberately rejects or defers cases when the evidence is not strong enough.

Compared with other vectorizers

Morphēa sits closer to "shape reconstruction" than classic pixel tracing. Illustrator Image Trace, Vectorizer.AI, Potrace, and Morphēa can all turn bitmaps into vectors, but they make different tradeoffs around editability, automation, pricing, local control, and explainability.

See Vectorizer comparison for a practical side-by-side comparison.

AI, but with receipts

Morphēa uses AI-assisted pieces for primitive classification, raster-target classification, optional MLX/SAM segmentation experiments, and reviewed self-learning. The important part is the audit trail: model output is connected to manifests, quality reports, training gates, and human-reviewed labels.

See AI in Morphēa for the current AI surface and why it matters for editable SVG reconstruction.

Quickstart

Morphēa is a Python package with a CLI entrypoint. The project currently targets Python 3.12 or newer.

python -m pip install -e .

Recommended MLX quality runtime for model-backed development:

uv pip install --python .venv/bin/python -e '.[mlx]'

The non-MLX fallback paths are useful for diagnostics and schema checks, but they are not equivalent model-backed quality evidence. See MLX quality runtime for the current stance. The morphea status report writes quality_runtime_audit, which is ready only when the primitive MLX classifier and raster-target MLX runtime are both available.

Optional live MLX/SAM adapter runtime, which currently needs a Python 3.14+ environment for the mlx-sam package:

uv venv .venv-mlx-sam --python 3.14
uv pip install --python .venv-mlx-sam/bin/python -e '.[mlx,sam]'

See docs/mlx-sam-runtime.md for runtime status checks, checkpoint handling, and the difference between a package-installed SAM adapter and a proven real-image SAM segmentation run.

Run the test suite:

python -m unittest discover -s tests

Run the primitive round-trip quality gate:

morphea primitive-check -o runs/primitive-quality.json \
  --output-dir runs/primitive-quality \
  --markdown runs/primitive-quality.md

morphea primitive-check -o /tmp/square.json --case filled_square

Vectorize an image into editable SVG primitives:

morphea vectorize input.png -o output.svg

For near-flat or antialiased images, group close colors before component detection:

morphea vectorize input.png -o output.svg --color-tolerance 18

Write a full run directory with input copy, SVG, preview, manifest, config, and reports:

morphea vectorize input.png -o output.svg --run-dir runs

Run the curated real-image suite metadata and bounded local cases:

morphea curated-check docs/real-images/suite.json \
  -o runs/curated-report.json \
  --output-dir runs/curated \
  --run

Profile the curated suite:

morphea profile-curated docs/real-images/suite.json \
  -o runs/curated-profile.json \
  --markdown runs/curated-profile.md \
  --repeats 3

The old curve command remains available as a compatibility alias during the rename. New docs and scripts should use morphea.

Common workflows

Generate labeled synthetic samples:

morphea generate -o runs/synthetic --count 10 --seed 1

Generate the deterministic chart target corpus:

morphea synthetic-corpus \
  --config docs/synthetic-corpus/chart-basic/synthetic-corpus.json

Train and evaluate the chart raster-target model with the quality MLX runtime:

morphea train-raster-targets \
  --config docs/synthetic-corpus/chart-basic/train-raster-targets.json

morphea eval-raster-targets \
  --config docs/synthetic-corpus/chart-basic/eval-raster-targets.json

Generate the deterministic typography grouping corpus:

morphea synthetic-corpus \
  --config docs/synthetic-corpus/typography-basic/synthetic-corpus.json

This corpus models glyphs, words, and text lines as grouped vector geometry. It does not perform OCR or reconstruct live text.

Generate the deterministic synthetic brand-mark corpus:

morphea synthetic-corpus \
  --config docs/synthetic-corpus/brand-basic/synthetic-corpus.json

This corpus uses project-generated abstract marks for counters, strokes, accents, and wordmark lockups. It does not copy third-party logos or publish trademarked brand assets.

Audit a third-party source candidate before fixture promotion:

morphea source-candidate-audit \
  assets/source-candidates/streamline/<set-name> \
  --require-dual-tone \
  --require-multicolor \
  --output /tmp/morphea-source-candidate-audit.json \
  --markdown /tmp/morphea-source-candidate-audit.md

Candidate audits check local metadata and PNG/SVG sanity. They do not replace license, attribution, or trademark review before assets are promoted.

Train the primitive-classifier baseline:

morphea train runs/synthetic/dataset.json -o runs/model.json

Use a trained classifier as an optional vectorize ranking prior:

morphea vectorize input.png -o output.svg --classifier-model runs/model.json

Harvest high-confidence pseudo-labels from run manifests:

morphea harvest runs -o runs/pseudo-labels.json \
  --min-editability-score 0.8 \
  --max-fragmentation-penalty 0.2

Create and apply a human review queue:

morphea review runs/pseudo-labels.json -o runs/review.json
morphea apply-review runs/review.json -o runs/accepted-labels.json

Run a reviewed-label self-learning cycle:

morphea self-learn runs/synthetic/dataset.json \
  --reviewed-labels runs/accepted-labels.json \
  -o runs/self-learn

Run structure-preserving refinement:

morphea refine runs/manifest.json -o runs/refined-manifest.json

Run a config-driven vectorize sweep:

morphea sweep sweep.json -o runs/sweep --markdown runs/sweep.md

Documentation

• Brand strategy: naming, positioning, voice, and launch motions.
• Plan: semantic-first vectorization direction.
• Milestones: implemented baselines and roadmap.
• Vectorizer comparison: how Morphēa relates to Illustrator Image Trace, Vectorizer.AI, and Potrace.
• AI in Morphēa: where model-assisted recognition is used and how reviewable evidence keeps it grounded.
• AI evidence gallery: artifact-backed examples for synthetic corpora, curated fixtures, runtime stance, and local comparisons.
• MLX quality runtime: expected runtime for model-backed quality evidence and the fallback boundary.
• Primitive quality roadmap: step-by-step gates for primary forms and primitive compositions.
• Real-image primitive family map: curated expectations mapped back to primitive fixture families.
• Schema: manifests, reports, status files, and command schemas.
• Sweeps: config-driven experiment comparisons.
• ADRs: accepted architecture decisions.
• Real-image notes: curated local image metadata and observations. The source images stay outside git.

GitHub Pages

The static project homepage lives in site/. It is dependency-free HTML and CSS. The Pages workflow uploads that site plus a temporary copy of the repo docs so the published documentation links resolve without duplicating docs in the repository.

To enable deployment, set the repository Pages source to GitHub Actions in GitHub repository settings.

Development notes

• Keep tests bounded. When running long checks locally, wrap subprocesses with an explicit timeout.
• Do not use local real-image files as checked-in assets. Curated suite entries may point at local paths, but the files themselves stay outside git.
• Morphēa prefers simple parametric shapes over generic paths unless fidelity would break materially.