Morphea is a research and engineering project for rebuilding editable SVG structure from raster images.

The goal is not just to convert pixels into paths. The goal is to infer the vector artwork that most likely produced the pixels: shapes, layers, primitives, strokes, repeated elements, and narrow gated material cases first, with broad effects and local raster fallbacks handled in later phases where vector reconstruction is the wrong tradeoff.

The initial focus is vector-like raster sources: icons, logos, badges, simple illustrations, UI graphics, marks, and flat graphics with a manageable number of colors. Drawings and photos matter, but they are secondary to high-quality reconstruction of sources that were likely vector artwork before they were flattened into pixels.

English is the working language for durable project artifacts: architecture notes, implementation plans, code comments, issue descriptions, PR descriptions, ADRs, and technical documentation.

1. Shape fidelity: the rendered SVG should match the source raster as closely as possible.
2. Editability: the SVG should remain understandable and editable, with sensible primitives, grouping, and a manageable number of nodes.
3. Broader support: drawings and photos should be supported through appropriate local strategies, not by weakening the core logo/icon use case.

Most vectorizers trace visible pixels. Morphea should reconstruct a scene.

Raster image
  -> normalization
  -> low-level segmentation
  -> segment graph
  -> AI-assisted segment/group proposals
  -> per-segment style/material classification
  -> per-segment vectorization strategy
  -> cross-segment shape and layer inference
  -> renderer-verified optimization
  -> editable SVG scene graph

The key distinction is between a visible raster region and an inferred vector shape. If a circle is partially covered by another shape, a simple tracer emits a partial contour. Morphea should try to recover the full circle plus the covering shape as separate editable layers.

Morphea is intentionally different from a conventional tracing tool.

• Segment locally, do not classify the whole image globally.
• Treat AI as a hypothesis layer, not as the final SVG authority.
• Keep deterministic geometry and rendering checks in the loop.
• Prefer primitives when fidelity is comparable: circles, ellipses, rectangles, rounded rectangles, polygons, strokes, and symbols.
• Learn from existing tools and research without copying their assumptions blindly.
• Preserve ambiguity until the renderer, topology checks, and editability cost can decide between candidates.
• Optimize for fewer cleanup steps in real vector editors.
• Make intermediate data inspectable: segments, groups, shape candidates, inferred layers, render errors, and editability metrics.

AI should help propose and classify structure:

• segment and mask proposals
• semantic grouping
• strategy selection per segment group
• primitive and occlusion priors
• error-guided repair suggestions

AI should not directly own final SVG output. Final decisions should be validated through geometry, SVG rendering, topology checks, and measurable comparison against the source image.

Morphea should eventually support multiple export profiles:

• faithful: maximize visual match, even with more nodes.
• editable: prefer primitives, fewer nodes, and clearer groups.
• semantic: preserve named groups, symbols, patterns, repeated instances, and inferred layers.
• tiny: minimize file size and SVG verbosity.
• hybrid: allow embedded raster islands where local vectorization would create misleading or uneditable output.

The default target is faithful-editable, meaning a policy that balances the faithful and editable profiles rather than a sixth export-profile enum value.

• Working document: evolving architecture notes and design direction.
• ADRs: durable architecture decisions.
• Product scope: target users, delivery form, success criteria, and release gates.
• Glossary: canonical terminology and boundary-object spelling.
• Open questions: central tracker for unresolved planning questions.
• Competitor landscape: broad competitor and baseline overview.
• AI models and methods: research on segmentation, grounding, grouping, amodal reconstruction, SVG-specific VLMs, and Morphea-specific training procedures.
• Research branches: broader method map for segmentation, shape understanding, primitive detection, amodal layering, differentiable optimization, and synthetic training data.
• Evaluation strategy: metrics, corpora, reports, ablations, and CI tiers for measuring vectorization quality.
• Implementation milestones: engineering roadmap from fixtures and evaluation through vectorization, AI proposals, and robustness.
• Implementation progress: current implementation status mapped to milestones M0-M7.
• Region-graph reconstruction roadmap: salvaged region-first reconstruction roadmap, aligned to current commands and milestones.
• Synthetic test graphics: plan for generating SVG/raster fixtures with full ground truth.
• Synthetic fixture corpus RFC: scope, commit policy, and first Golden fixture batch for regression testing.
• Shape recognition and AI pipeline: candidate generation, primitive fitting, AI proposal providers, and scoring architecture.
• Tracing algorithms and preprocessing: Potrace, mkbitmap, VTracer, contour formulas, and evidence-preserving preprocessing strategy.
• Competitor gap analysis: quality differentiators and uncovered competitor-inspired planning gaps.
• People and research lineage: public founder, academic, paper, and company lineage behind relevant competitors.
• Competitor research index: grouping by implementation idea and research queue.
• Planning documentation audit: gaps, problems, and proposed solutions across the planning corpus, with a verification pass.
• Takeover from old Morphea: selective salvage plan from the older Python morphea workspace.

High-priority baselines and references:

• Vectorizer.AI: closest direct commercial benchmark.
• VTracer: most useful open-source color-vectorization baseline.
• Potrace: foundational binary contour tracing baseline.
• Inkscape Trace Bitmap: free editor workflow and UX baseline.
• AmodalSVG: strong research alignment for occluded shape reconstruction.
• SAMVG: segmentation-first vectorization research.
• StarVector: semantic SVG code/primitives research.
• DiffVG: differentiable-rendering reference for vector optimization.

The first useful MVP should focus on flat icons, logos, and shape reconstruction, not broad photo conversion or gradient/shadow reconstruction.

MVP scope:

• PNG input with alpha.
• Palette extraction with antialias modeling.
• Connected components and segment graph.
• Path extraction for flat-fill segments.
• Primitive fitting according to the canonical MVP primitive set in ADR 0009.
• Layer-mask bundle output before final SVG export.
• Basic layer ordering.
• Render/compare loop using resvg as the primary visual evaluation renderer.
• SVG export with faithful and editable profiles.
• MVP metrics summarized here; the full canonical metric set lives in Evaluation strategy.

Next stages:

• AI-assisted grouping.
• Occlusion reconstruction.
• Stroke reconstruction.
• Broader gradients, shadows, highlights, and texture material-reconstruction phases.
• Text handling.
• Hybrid raster/vector export.
• Interactive correction of segments, groups, layers, and primitives.

The implementation is now a small but runnable M0-M7 seed with 221 Golden fixtures, smoke gates, and vectorization reports that expose construction decision traces for selected constructions and rejected alternatives:

cargo fmt --check
cargo clippy --workspace --all-targets --all-features
cargo test --workspace
cargo run -- version
cargo run -- fixtures generate --force
cargo run -- fixtures check --report target/fixtures/check-report.json
cargo run -- fixtures qualitative-check --report target/fixtures/qualitative-check-report.json
cargo run -- eval fixtures/golden/primitive-circle-solid
cargo run -- eval fixtures/golden/primitive-circle-solid --artifacts target/eval/primitive-circle-solid --output target/eval/primitive-circle-solid/report.json
cargo run -- eval smoke --artifacts --output target/eval/smoke
cargo run -- eval --baseline-vectorize fixtures/golden/primitive-circle-solid --artifacts target/eval/baseline-circle --output target/eval/baseline-circle/report.json
cargo run -- eval smoke --baseline-vectorize --artifacts --output target/eval/baseline-smoke
cargo run -- analyze fixtures/golden/primitive-circle-solid/input-512.png --output target/analyze/primitive-circle-solid
cargo run -- analyze fixtures/golden/primitive-circle-solid/input-512.png --output target/analyze/primitive-circle-solid --ground-truth fixtures/golden/primitive-circle-solid/ground_truth.json
cargo run -- analyze fixtures/golden/background-ignore-white-circle/input-512.png --background '#ffffff' --output target/analyze/background-ignore-white-circle
cargo run -- analyze smoke --output target/analyze/smoke
cargo run -- analyze region-graph fixtures/golden/layer-cutout-circle-in-square/input-512.png --output target/analyze/region-graph/layer-cutout-circle-in-square.json
cargo run -- vectorize fixtures/golden/primitive-circle-solid/input-512.png --output target/vectorize/primitive-circle-solid.svg --artifacts target/vectorize/primitive-circle-solid-artifacts
cargo run -- vectorize fixtures/golden/primitive-rectangle-solid/input-512.png --profile editable --output target/vectorize/primitive-rectangle-editable.svg --artifacts target/vectorize/primitive-rectangle-editable-artifacts
cargo run -- vectorize fixtures/golden/primitive-circle-solid/input-512.png --profile editable --output target/vectorize/primitive-circle-editable.svg --artifacts target/vectorize/primitive-circle-editable-artifacts
cargo run -- vectorize fixtures/golden/background-ignore-white-circle/input-512.png --profile editable --background '#ffffff' --output target/vectorize/background-ignore-white-circle.svg
cargo run -- vectorize smoke --profile editable --output target/vectorize/editable-smoke
cargo run -- demo html --output target/demo/html
cargo run -- test deterministic --output target/test/deterministic
python3 research/python/empty_proposal_provider.py --input-id fixtures/golden/primitive-circle-solid/input-512.png --output target/ai/empty-proposals.json
cargo run -- ai validate-proposals target/ai/empty-proposals.json
python3 research/python/ablation_proposal_provider.py --input-id fixtures/golden/mark-same-color-repeat-blocks/input-512.png --output target/ai/ablation-proposals.json
cargo run -- eval fixtures/golden/mark-same-color-repeat-blocks --ai-proposals target/ai/ablation-proposals.json --output target/ai/ablation-report.json

Current eval validates fixture metadata, renders source.svg with resvg, compares it against the first fixture raster, records render and topology metrics, evaluates available metric gates, attaches deterministic RegionGraph summary metadata, and emits a schema-valid EvaluationReport. With --artifacts, it writes rendered-source, heatmap, edge-diff, and region_graph.json artifacts. With --baseline-vectorize, it evaluates the current faithful contour baseline and enforces baseline-specific render/editability/topology gates from expected_metrics.json.

fixtures check regenerates the deterministic Golden corpus into target/fixtures/check-generated, compares it byte-for-byte against fixtures/golden, writes a machine-readable drift report, and is the CI gate for committed fixture determinism. fixtures qualitative-check validates the real-world qualitative review manifest and reports whether approved, licensed samples are present for a release gate.

Smoke commands write one machine-readable batch_report.json in their output directory in addition to per-fixture reports/artifacts, so CI and API-style consumers can read the whole batch result from a stable path. Each smoke summary includes an artifact index plus per-family pass/fail/skip counts. vectorize smoke also records batch-level SVG compatibility, construction-decision, primitive/group/instance/stroke/symmetry/cutout recovery, same-color ambiguity/export-policy, lettering, stroke-detail, stroke-fallback, compatibility-sample, artifact-index, review-index, and demo-gallery summaries, writes compatibility_sample.html with a small pass/fail summary plus direct SVG/report links for manual SVG compatibility inspection, writes demo_gallery.html, a curated input-raster versus generated-SVG gallery with selected/pass/family context, a selected-sample index, core smoke metrics, per-sample failed gates, selected construction names, input/SVG/report links, visible engine/producer provenance, and selected real degraded 64/128px robustness inputs, and writes index.html as the linked review entry point for the vectorize smoke artifacts with status, family-coverage details, gate-summary details, SVG compatibility check details, reconstruction/policy health details, timing details, failed-case report links, and pass/fail counts. After running cargo run -- vectorize smoke --profile editable --output target/vectorize/editable-smoke, target/vectorize/editable-smoke/index.html is the current HTML smoke review entry point and target/vectorize/editable-smoke/demo_gallery.html is the current HTML demo pass-through. cargo run -- demo html --output target/demo/html is the product-through shorthand for the same editable HTML demo/review artifact set, labels the generated index as a product-through HTML demo while preserving the smoke-gated artifact links, writes target/demo/html/demo_summary.json as the compact schema-versioned product-through summary with engine/producer provenance, review-index context, family, gate, construction, compatibility, core recovery, reconstruction, export-equivalence, and same-color policy summaries, compatibility-sample counts/status/links, demo-gallery counts, selected demo sample status/links, and a compact artifact index, and prints a compact stdout summary containing the key artifact links and top-level counts; a standalone interactive review UI remains later product work. test deterministic bundles fixture drift checking, qualitative manifest checking, baseline eval smoke, analyze smoke, and editable vectorize smoke behind one deterministic local/product verification command and writes deterministic_test_report.json with phase timings, phase report paths, top-level phase pass/fail counts plus failed phase names, a top-level artifact index for report and HTML entry-point paths, mirrored smoke phase counts, failed-case lists, timing summaries, compatibility summaries, compatibility-sample summaries, construction summaries, primitive/group/instance/stroke/symmetry/cutout recovery summaries, reconstruction, lettering, stroke-detail, stroke-fallback, same-color ambiguity, gate, review-index, and family summaries, compatibility sample path, demo gallery path plus summary, and a top-level qualitative release-gate summary. It also writes deterministic_test_report.html as the current linked HTML entrypoint for the bundled deterministic run, including visible engine/producer metadata, qualitative release-gate set and missing-artifact metrics, phase pass/fail metrics, a top-level artifact-index link strip, mirrored compatibility-sample and demo-gallery top metrics, direct compatibility-sample SVG/report links, direct demo-sample input/SVG/report links, compact demo selected-construction and failed-gate chips, mirrored review-index context in the phase artifact details, plus expandable per-phase failed cases, timing, compatibility, construction, recovery, reconstruction/lettering/stroke-detail/stroke-fallback, same-color ambiguity, and gate-check details.

Current analyze emits an initial LayerMaskBundle with exact palette evidence, antialias/coverage evidence, dominant color-family segments, deferred material evidence for smooth linear/radial gradient-like, soft-shadow-like, transparency-heavy, and raster-unsuitable island regions, segment masks, segment/background/uncertainty/artifact-risk/deferred-material overlays, ignored-background evidence when a configured background color is supplied, uncertainty annotation operations, and optional visible IoU when fixture ground truth is provided. analyze smoke runs that evidence pass over the Golden corpus and fails if a normal fixture with visible masks falls below the configured best-visible-IoU threshold or if a material fixture does not produce deferred-material evidence.

Current analyze region-graph emits a deterministic RegionGraph JSON artifact with positive regions, negative holes/cutouts, relationships, packaging decisions, and a summary. It is the current morphea2 landing path for the salvaged region-first roadmap; the old Python region-graph command and benchmark command are not part of this repository.

Current vectorize emits a first faithful contour baseline from visible-alpha masks or per-color masks, reports path/node counts plus render/topology metrics, writes scene_graph.json and region_graph.json artifacts describing the selected construction and input-region evidence, and compares the rendered SVG back against the input raster. vectorize smoke also reports primitive, group, instance-candidate, stroke, stroke-fallback, cutout, amodal, layer-order, same-color ambiguity, same-color split-candidate, export-equivalence, and basic SVG compatibility recovery from fixture expectations versus SceneGraph nodes/groups and generated SVG, including checks for the SVG root, raster embeds, scripts, style elements, live text elements, animation elements, filter effects, clipping/mask elements, pattern elements, inline event handlers, foreignObject, and external references, while running simple gradient, gradient-with-foreground-shape, transparency, and soft-shadow material fixtures through normal gates and still skipping raster-unsuitable material fixtures. --profile editable currently adds conservative exact rectangle, disconnected same-color rectangle, circle, ellipse, and polygon components with a simple repetition group plus SVG <symbol>/<use> instance export when size and spacing are uniform in a line or grid for supported families, renderer-verified SVG linear/radial gradient reconstruction for high-coverage rectangular gradient inputs, linear-gradient base plus single or multiple foreground rectangle/circle/ellipse layer reconstruction, uniform-alpha rectangle/rounded-rectangle transparency reconstruction, simple radial-alpha ellipse shadow reconstruction with foreground shape recovery, and deferred-material placeholders for raster-unsuitable full-region material inputs, per-color rectangle, rounded rectangle, pill, circle, ellipse, concentric ring cutout, rectangle-with-circle/ellipse/rounded-rectangle/line/cross/single- or multi-rectangle/mixed-shape compound cutout, centered, offset, and small foreground-circle-over-rectangle, foreground-ellipse-over-rectangle, foreground-rectangle-over-rectangle, foreground-triangle-over-rectangle, foreground-diamond-over-rectangle, foreground-pentagon-over-rectangle, foreground-hexagon-over-rectangle, foreground-star-over-rectangle, and scalene/left-scalene/right-scalene/skew/trapezoid/narrow-quadrilateral/irregular/notched foreground-polygon-over-rectangle layer reconstruction with an amodal base rectangle, foreground-circle/ellipse/rectangle/triangle/pentagon/star-over-ellipse layer reconstruction with an amodal base ellipse, foreground-circle/ellipse/rectangle/triangle/pentagon/star-over-circle layer reconstruction with an amodal base circle, current same-color overlap visible-union ambiguity fallback plus gated report-only verified two-/three-primitive split candidates, export-blocking rationale, and report-only export-policy checks for rectangle, circle, ellipse, and all six scale-stable bridge-separated orthogonal polygon overlap masks, lettering-counter compound components, axis-aligned and diagonal strokes, clean horizontal/vertical semicircle and quadrant quarter arc strokes, narrow round-join and miter-join polyline stroke templates, and an unsupported freeform centerline-stroke fallback fixture that exports a filled outline with warning metadata, triangle, upright pentagon, upright hexagon, upright star, transformed quadrilaterals, configured-background ignore for clean white and dark backdrop cases, and circle/ellipse occlusion layer cases across rectangle, circle, and ellipse foreground occluders, and otherwise falls back to the faithful contour, color-segment baseline, or visible-remainder occlusion output with uncertainty metadata. Logo-normalized vectorization now applies conservative 0.5px contour simplification before generated-logo smoke gates, keeping the committed 10-logo corpus under the default max_node_count = 8000 budget while preserving normalized render and edge gates. Generated-logo smoke reports also include structure_summary coverage from the emitted SceneGraph, logo-normalized generic color-family paths are grouped as logo_path_segments, and conservative layout evidence now emits generated-logo icon_group plus lettering_like_group candidates for all 10 committed generated-logo cases while keeping ocr_text: null. The material foreground path now preserves foreground fill color rather than assuming white-only overlays.

Current AI work is a schema and file-boundary seed, not model execution. AiProposalBundle artifacts can be generated by the empty Python boundary provider or the non-empty ablation proposal provider, validated through the Rust CLI, and imported into evaluation reports as report-only evidence or renderer-scored candidate SVG evidence with an ai_ablation metadata block comparing deterministic-only metrics to deterministic-plus-AI proposal metrics plus an ai_proposal_decisions trace for per-proposal acceptance, rejection, or harmfulness. Reports also expose scoring_status and required_scoring fields so the renderer-verified acceptance boundary is explicit.

• Do not build a black-box AI-to-SVG generator as the core system.
• Do not optimize first for arbitrary photos.
• Do not treat all output as generic paths when meaningful SVG primitives are available.
• Do not collapse the problem into a single global image mode such as logo, icon, drawing, or photo.
• Do not use visual fidelity alone as the only quality metric; editability and structure matter.

This repository contains research notes, ADRs, competitor dossiers, early architecture direction, and an early Rust implementation. The current runnable scope covers M0 plus active M1/M2/M3/M4/M5 work, an M6 boundary/ablation seed, twenty M7a degradation slices, seven M7b material/deferred/raster-fallback slices, and first M7c batch-report, deterministic-fixture-check, deterministic-test, qualitative-release-summary, compatibility-check, compatibility-sample, demo-gallery, smoke-review-index, and deterministic HTML report slices: schema validation, CLI scaffolding, evaluation reports, stable smoke batch_report.json artifacts with per-family, SVG compatibility, construction-decision, primitive/group/instance/stroke/cutout recovery, lettering, stroke-detail, stroke-fallback, symmetry, same-color ambiguity, and demo-gallery summaries, a 221-fixture Golden set including forty-six centerline stroke cases across horizontal, vertical, short, wide, diagonal, upward, offset, horizontal/vertical semicircle arc, quadrant quarter arc, round-join polyline, miter-join polyline, mirrored step/C polyline, checkmark variants, and one expected freeform fallback case, two-color mark, horizontal and vertical same-color repeated block, dot, ellipse, triangle, hexagon, pentagon, and star cases, grid repeated block, dot, ellipse, triangle, hexagon, and star cases, same-color nonuniform repeated-block, repeated-ellipse, repeated-triangle, repeated-hexagon, repeated-pentagon, and repeated-star cases, symmetric, offset, three-shape, circle-overlap, ellipse-overlap, T-overlap, and L/step/zigzag/U/C/stair orthogonal polygon-overlap same-color ambiguity, horizontal, vertical, uneven, three-source, four-source, tiled, and grid abutting same-color export equivalence, lettering-like grouping, lettering-counter grouping, icon/wordmark separation, white and dark background-ignore, real white-shape background distinction, centered/offset circle plus centered ellipse, single-rectangle, rounded-rectangle, line, cross, double-rectangle, and mixed ellipse/rectangle region-graph cutouts, centered/offset/small foreground-circle-over-rectangle, centered/offset foreground-ellipse-over-rectangle, foreground-rectangle-over-rectangle, foreground-triangle-over-rectangle, foreground-diamond-over-rectangle, foreground-pentagon-over-rectangle, foreground-hexagon-over-rectangle, foreground-star-over-rectangle, and scalene/left-scalene/right-scalene/skew/trapezoid/narrow-quadrilateral/irregular/wide-irregular/notched foreground-polygon-over-rectangle layering, foreground-circle/ellipse/rectangle/triangle/pentagon/star-over-ellipse layering, foreground-circle/ellipse/rectangle/triangle/pentagon/star-over-circle layering, low-resolution, noisy, blurred, palette-reduced, and JPEG-compressed circle, ellipse, rectangle, and polygon degradation, hexagon, linear-gradient material reconstruction, radial-gradient material reconstruction, transparency material reconstruction, soft-shadow material reconstruction, raster-unsuitable island material, and circle/ellipse occlusion cases across rectangle, circle, and ellipse foreground occluders cases, raster evidence smoke checks, faithful contour/color-segment vectorization baselines, conservative editable primitive, stroke arc and symmetry metadata, deferred-material placeholder export, and SVG <symbol>/<use> instance export, initial SceneGraph output, topology actuals for connected components and holes, deterministic RegionGraph extraction in normal reports/artifacts, basic SVG compatibility gates plus HTML compatibility, review index, and demo galleries in vectorize smoke, M4a/M4b amodal/layer-order/export-equivalence gates, and AI proposal-bundle validation/import plus concrete report-only and candidate-SVG ablation inputs without model execution.