image-to-svg

name

image-to-svg

description

Convert a complex design image into a clearer, second-editable SVG composition by checking the available image generation model, defaulting to built-in image_gen when available, decomposing the confirmed design into separately generated image-to-image sub-elements, saving those element images beside the source image or output SVG, and assembling them as editable SVG layout primitives. Use when Codex is asked to turn generated overview images, design diagrams, paper mechanism figures, or research framework images into organized element image sets and editable SVG outputs.

Image To SVG

Use this skill to turn a dense or complex design image into a clearer, editable SVG-oriented production workflow:

1. Overview design: design or confirm the complete image first.
2. Image decomposition: split the confirmed design into clear reusable sub-images.
3. Image-model regeneration: generate each sub-image through the selected image generation model interface.
4. SVG assembly: compose the element image set into a high-quality editable SVG layout.
5. Second-pass editing: keep layout, arrows, title, panel order, colors, and element replacement editable.

Default to the built-in image_gen tool when it is available. If image_gen is unavailable or the user asks for an explicit model, endpoint, or external provider, use the best configured advanced image generation model after checking availability and requirements.

Image Model Check

Before the first image generation call in a project, identify the active image generation path:

1. Built-in path: if the built-in image_gen tool is available, use it by default. Record it as image_gen; if the tool does not expose a concrete model name, say that model selection is not exposed by the current tool.
2. Explicit OpenAI/API path: if the user asks for a named model or endpoint, check whether the required CLI/API script, endpoint, and credentials are configured before using it. Do not print secrets.
3. Other advanced model path: if image_gen is unavailable and another high-quality image generation provider is already configured, tell the user which provider/model will be used and why.
4. No model available: if no image generation path is available, stop before designing image prompts and ask the user to connect a generation model. Recommend connecting the built-in image_gen path first, or an OpenAI image API/CLI fallback if they need explicit model control.

Do not ask for confirmation when the default image_gen path is available and the user did not request a specific model. Do ask before switching to a lower-capability fallback, using a paid external endpoint, or changing from the user's requested model/provider.

Visual Input Requirement

This workflow requires a source image, confirmed overview image, or previously generated image visible in the conversation. If the user provides only text and no visual input, ask for or create a confirmed overview image first as a separate prerequisite; do not start element generation from text-only prompts. Once the overview image exists, all element generation must be image-to-image or image-plus-text-to-image.

Hard Gates

The final SVG workflow is invalid unless these gates are satisfied:

1. Do not embed only the whole overview image. A self-contained SVG that contains one full-size source PNG is not enough unless the user explicitly asks for a simple wrapper.
2. The decomposition output must be images. Confirm or infer the overview first, then create an element plan where every planned element maps to a concrete sub-image file to be generated. Text-only semantic decomposition is not sufficient.
3. Generation mode must be image-to-image. Every sub-image generation call must use the confirmed source/overview image as a visual reference input, optionally with text instructions. Do not use text-only prompting to create element images.
4. Generate each sub-image through the selected image generation model interface. Use the confirmed overview or source image as style/reference only. Do not treat raw crops from the source image as the generated element set.
5. Every element must have a visual image. Semantic descriptions, labels, and prompts may accompany an element, but they cannot replace the element PNG/sub-image.
6. Use SVG for layout and exact text. The SVG should own titles, Chinese/English labels, module text, arrows, panel frames, numbering, spacing, colors, and grouping whenever editability or spelling matters.
7. Keep assets co-located. All generated overview images, element PNGs, contact sheets, SVG outputs, and previews must be saved beside the source image or beside the requested output SVG, normally in a sibling <source_stem>_assets/ or <output_stem>_assets/ directory.

If a request would violate these gates, state the exception before proceeding.

Core Method

Treat the first image as an art-direction proof, not the final production asset. The confirmed overview establishes:

• panel structure and reading order
• visual style, palette, and density
• exact scientific labels and notation
• which parts should become independent elements
• final assembly rules for the SVG

Then generate each element as a separate sub-image through the image generation model interface so the final image becomes clearer and easier to revise. This must be image-to-image generation: the source/overview image is the visual input, and text is only an auxiliary constraint. The SVG should contain editable layout primitives such as title text, panel borders, arrows, legend, and positioning. Generated visual elements remain embedded raster PNGs; edit them by replacing, regenerating, or manually retouching the individual element image file.

Asset Locality

Choose the asset root before generating anything:

• If the user provides an output SVG path, put generated assets in <output_svg_stem>_assets/ next to that SVG.
• Else if the user provides a source image path, put generated assets in <source_image_stem>_assets/ next to that image.
• Else use the current project figure/output directory and create image_to_svg_assets/.

Copy or move selected generated outputs from $CODEX_HOME/generated_images/... into that asset root immediately after each generation. Never leave project-bound assets only under $CODEX_HOME, a temp directory, or an unrelated working directory.

Workflow

1. Gather Source Context

Read the user's requirement, manuscript, abstract, method section, figure captions, existing design image, or workflow description. Identify:

• input or starting state
• model, method, or transformation stages
• interaction, decomposition, or assembly core
• readout, final output, or editable result
• evaluation, evidence, or supporting panels

Keep the image claim bounded. Scientific mechanism images should explain what the paper claims mechanistically, not imply performance or causality beyond the paper text.

2. Design The Overview Image

Use the selected image generation path only with a visual input to refine or confirm a raster PNG overview that functions as the design proof. If no visual input exists, ask the user for a source/overview image before element generation. For a research paper image, default to:

• white background
• four horizontal panels unless the paper strongly suggests another structure
• restrained academic palette
• minimal visible text
• exact labels provided in the prompt
• no watermark, no logo, no decorative scene, no SVG

Use references/prompts.md for prompt templates. Inspect the generated image with the user. If text is misspelled, crowded, or the mechanism is unclear, iterate with less text and stronger label constraints before generating elements.

Save the overview image into the chosen asset root. Do not leave project assets only under $CODEX_HOME/generated_images.

3. Decompose Into An Element Set

After the user confirms an overview image, load it with view_image so it is available as the visual reference input. Generate one sub-image per conceptual element with the selected image generation path. Each generation call must be image-to-image, or image-plus-text-to-image; it must not be text-to-image. Each element image should be useful on its own and should not depend on being cropped from the overview. Save each generated element image into the asset root before assembling the SVG.

Recommended default elements:

• overview or source design panel
• decomposition or reusable element panel
• SVG assembly or layout panel
• editable final output panel

Save each element with stable filenames such as:

overview_element.png
decomposed_elements.png
svg_assembly.png
editable_output.png

Create a local contact sheet for inspection if there are multiple elements.

4. Assemble An Editable SVG Layout

Use scripts/assemble_svg_layout.py to compose the generated PNG elements into a self-contained SVG. The script embeds PNG data as base64, adds panel cards, arrows, optional title/subtitle, and optional preview PNG. It requires Pillow (PIL) for image sizing and whitespace cropping.

By default, the generated SVG is self-contained and portable. It is second-editable at the layout level: users can edit text, arrows, panel frames, colors, dimensions, spacing, and swap embedded element PNGs. It is not a full vector trace of the generated artwork.

Example:

python image-to-svg/scripts/assemble_svg_layout.py \
  --elements-dir paper/latex/figures/core_mechanism_elements \
  --out paper/latex/figures/core_mechanism_elements/core_mechanism_layout.svg \
  --title "Core Mechanism: Editable Research Figure" \
  --subtitle "Overview proof -> reusable generated elements -> editable SVG layout" \
  --preview

If the element filenames differ, pass explicit paths:

python image-to-svg/scripts/assemble_svg_layout.py \
  --element A:path/to/overview.png:#2563eb \
  --element B:path/to/elements.png:#0f766e \
  --element C:path/to/assembly.png:#d97706 \
  --element D:path/to/editable.png:#7e22ce \
  --out path/to/layout.svg

Quality Checks

Before finishing:

• open the overview and element contact sheet with view_image
• confirm outputs are PNG for generated elements and SVG for the assembled layout
• confirm there is more than one generated element when the source design has multiple conceptual parts
• confirm every planned element has a generated sub-image produced through the selected image generation path
• confirm sub-images were generated from a visual source/overview input, not text-only prompts
• confirm all generated assets are beside the source image or output SVG, not only under $CODEX_HOME/generated_images
• confirm the overview design, decomposition, and assembly all match the same mechanism chain
• confirm the SVG is self-contained if the user wants portability
• state which parts are editable as SVG primitives and which parts are embedded raster elements
• render the SVG to a preview PNG when a renderer is available
• report final paths, the selected image generation path, and any exposed model/provider name

Do not silently publish API-key or endpoint details. Report endpoint/model details only when the user specifically asks.