Yingqi-Han/reconstruct-scientific-svg-skill

Reconstruct Scientific SVG

Rebuild reference figures as deterministic SVG source rather than disguising a bitmap inside an SVG container. Preserve live text whenever editability matters, and validate both document structure and rendered appearance.

Establish the Deliverable Contract

Before drawing, resolve these requirements from the request and source:

• Decide whether every element must be vector, or only text and annotations.
• Treat “editable text” as native SVG <text>, not paths.
• Record the reference pixel dimensions and requested output dimensions.
• Record any explicit ban on image generation, network services, embedded rasters, GUI control, or proprietary software.
• Convert a requested similarity percentage into named checks. Never claim “90% accuracy” from visual intuition alone.
• Keep unpublished or sensitive figures local unless upload is authorized.

Use the user's latest explicit requirement when editability and pixel identity conflict.

Select the Primary Mode

Choose and state one primary mode before implementation. Individual components may use the other technique, but do not blur the overall optimization target.

Mode A: Structure-First Semantic Redraw

结构优先的语义重绘 rebuilds the figure from meaningful SVG objects.

Use it when the user prioritizes:

• clean groups and descriptive IDs;
• low or controlled node count;
• easy movement, recoloring, relabeling, and future redesign;
• correct scientific relationships over pixel-level identity;
• publication figures that will continue to evolve.

Judge it primarily by semantic completeness, correct geometry and layer relationships, text editability, object organization, and practical editing in the target application. Raster similarity is secondary evidence.

Mode B: Similarity-First Trace Plus Semantic Correction

相似度优先的矢量追踪＋语义修正 traces complex artwork for visual fidelity, then repairs the parts that must carry editable meaning.

Use it when the user prioritizes:

• close reproduction of an existing reference;
• a stated similarity threshold;
• preservation of subtle silhouettes, colors, and painted shading;
• native labels and corrected occlusion despite a high path count.

Judge it primarily by equal-size render comparison plus explicit checks of labels, layer order, embedded rasters, and remaining editability. Report that traced artwork may contain thousands of paths and is less convenient to reshape.

Read references/method-selection.md for the mode comparison and hybrid boundary.

Distinguish the Four Representations

Do not conflate these:

1. Native text: <text> with a real installed font. It remains editable and looks like the standard font.
2. True font outlines: glyph curves produced from a font. They look standard but are no longer editable as text.
3. Pixel-traced lettering: paths fitted to rasterized glyph pixels and antialiasing. It often looks rough or malformed and is not a font conversion.
4. Embedded raster: <image href="data:image/..."> or a linked bitmap. It is not native vector artwork.

Read references/text-and-fonts.md whenever the figure contains labels.

Workflow

1. Inspect the Reference

• View the original at native resolution.
• Inventory shapes, labels, gradients, shadows, transparency, masks, repeated motifs, and occlusion relationships.
• Sample key coordinates and colors rather than guessing them.
• Identify text bounding boxes separately from anatomical or scientific shapes.
• Check whether the source already contains usable vector objects before tracing a raster preview.

2. Choose a Reconstruction Strategy

Apply the selected primary mode:

• In Mode A, use hand-authored SVG paths, groups, and reusable shapes. Treat tracing only as a temporary positional aid or a bounded exception.
• In Mode B, use a high-quality trace for complex painted regions, preferably from artwork without text, then add semantic groups and native <text>.
• Use true font-to-path conversion only when appearance portability is more important than text editing.
• Never use pixel-traced lettering as the recommended editable-text deliverable.

If the trace combines multiple disconnected regions into one <path>, treat each M...Z subpath independently before deleting traced labels. Removing the whole path can erase unrelated artwork. See references/traced-text-cleanup.md.

3. Reconstruct the Artwork

• Set a stable viewBox matching the reference coordinate system.
• Build back-to-front layer order deliberately.
• Reproduce visible occlusion with ordering, opacity, gradients, clipping paths, masks, or localized shadows.
• Preserve partially visible vessels, ducts, and organs instead of covering them with opaque foreground shapes.
• Use groups and descriptive IDs for objects that users are likely to edit.
• Avoid unnecessary clipping and filters when ordinary layered paths suffice.
• Report high path counts honestly: native vector does not automatically mean convenient object-level editing.

For CLI-only work, use Inkscape or another renderer without taking control of the user's desktop. Tool choice does not change the fact that the source of truth is SVG/XML.

4. Rebuild Labels as Native Text

• Use the actual font family when available; otherwise declare a deliberate fallback stack.
• Match x, baseline y, font-size, font-weight, and letter-spacing.
• Prefer real bold faces over strokes around text.
• Keep labels in one named group, such as native-editable-labels.
• Do not distort glyphs merely to match antialiasing pixels from another renderer.

Use scripts/compose_native_text.py to append labels from a JSON manifest after the traced lettering has been removed. Start from references/label-manifest.example.json and retain SVG attribute names such as font-family and letter-spacing.

5. Render and Iterate

Render at the reference dimensions first. Compare:

• global silhouette and proportions;
• organ or component boundaries;
• layer order and partial visibility;
• shadows and transparency;
• label content, font, weight, baseline, spacing, and placement;
• ordinary-size appearance before extreme-zoom edge pixels.

Change one hypothesis at a time. If a cleanup method damages artwork, stop and return to the last intact SVG rather than stacking compensating patches.

6. Validate Structure and Appearance

In Mode A, make structural and practical-editability gates primary. In Mode B, make the equal-size render gate primary while still requiring the structural gate.

Run the structural gate:

python -X utf8 scripts/validate_svg.py figure.svg `
  --forbid-image --require-viewbox --min-text 1

Render with Inkscape without GUI interaction:

inkscape figure.svg --export-type=png `
  --export-width=3508 --export-filename=figure-preview.png

Run the visual proxy gate:

python -X utf8 scripts/compare_renders.py reference.png figure-preview.png `
  --report comparison.json --comparison comparison.png --minimum 0.90

Treat pixel metrics as evidence, not semantic proof. Inspect the comparison image manually. Read references/quality-gates.md for the full acceptance checklist.

7. Export Derivatives

Keep the editable SVG as the authoritative source. Export PNG or PDF only as derivatives.

inkscape figure.svg --export-type=pdf --export-filename=figure.pdf
pdffonts figure.pdf

To preserve text in PDF, omit --export-text-to-path. Do not pass --export-text-to-path=false; some CLI versions treat the presence of the boolean option as enabling conversion. Verify the PDF with pdffonts.

Failure Gates

Stop and revise when any of these occur:

• A “pure vector” SVG contains <image> or data:image.
• An “editable text” SVG contains no <text>.
• Replacing text removes unrelated shapes.
• A high metric hides wrong labels, wrong layer order, or distorted glyphs.
• The renderer substituted a missing font.
• The preview was compared at a different size without an explicit resize.
• A PDF expected to retain text reports no fonts.

Deliverables

Provide:

• the authoritative editable SVG;
• the selected primary mode and why it was selected;
• a native-size or 2K preview PNG;
• a comparison report and image when fidelity was requested;
• an optional 4K PNG and PDF;
• the script or manifest used to generate labels;
• a concise statement of what is native text, what is path artwork, whether any raster remains, which font is required, what visual differences remain, and how practical the traced artwork is to edit.

Do not recommend a traced-text-outline variant when the user asked for standard editable typography.