research-figures-by-drawio

name

research-figures-by-drawio

description

Create cleaner editable research figures with draw.io / diagrams.net, including academic diagrams, scientific workflow diagrams, method architecture figures, thesis figures, and PPT-ready visuals. Use when Codex needs to generate or improve publication-style scientific figures with editable labels, shapes, arrows, connector routing, visual planning, validation, and export checks, especially when direct draw.io generation causes cluttered connectors, text overlap, poor layout, or unattractive composition.

Research Figures by Draw.io

Create polished editable draw.io figures by using a raster reference image for composition, then reconstructing the figure as layered draw.io cells plus bounded foreground assets on a pure white canvas.

Workflow

1. Inventory the figure content and final medium.
   • List modules, labels, data blocks, assets, legends, feedback loops, and stage relationships.
   • Determine the canvas from content structure and label density. Do not start from a fixed ratio unless the user requires one.
   • Record final-use assumptions such as thesis Word width, PPT slide size, web placement, poster size, or unknown target.
2. Load only the references needed for the task.
   • Read references/composition_rules.md for layout, readability, connector routing, export padding, and boundary-planning rules.
   • Read references/visual_plan_format.md before writing or editing visual_plan.json.
   • Read references/provider_config.md only when generating GPT Image assets or changing image-provider settings.
3. Build or accept a whole-figure reference image.
   • If the user supplies an image, inspect it and store it under sources/.
   • If the user supplies only a brief, generate a composition reference with scripts/generate_gpt_image_asset.py.
   • Use the reference for spacing and hierarchy only; do not rely on generated text.
4. Decompose the figure into editable and bitmap layers.
   • Keep titles, labels, modules, containers, connector labels, arrows, legends, tables, data labels, and axes editable in draw.io.
   • Use generated image assets only for foreground scientific visuals that are hard to draw cleanly as cells.
5. Write visual_plan.json.
   • Include explicit coordinates, content-derived canvas dimensions, target_output, boundary_checks, and connector points.
   • Prefer fewer high-level routed connectors over many crossing micro-edges.
6. Generate auxiliary assets when needed.
   • Write prompts to image_prompts/all_asset_prompts.json.
   • Run scripts/generate_gpt_image_asset.py <package_root>.
   • Request isolated foreground assets on transparent or plain white backgrounds.
7. Render editable draw.io output.
   • Use draw.io MCP tools when available.
   • Otherwise run scripts/render_visual_plan_to_drawio.py visual_plan.json --out-dir drawio.
8. Validate and iterate.
   • Run scripts/validate_visual_plan.py visual_plan.json.
   • Fix overlap, connector crossing, boundary, font-size, stroke-width, and export-readiness warnings before final delivery.
9. Export and inspect the preview.
   • Use diagrams.net CLI when available.
   • Inspect PNG/SVG at the planned insertion or viewing size, not only at full pixel size.

Output Package

Create a package folder in the current workspace:

research_figures_by_drawio_package_<slug>_<YYYYMMDD>/
  visual_plan.json
  assumptions.md
  sources/
  image_prompts/
  assets/generated/
  drawio/
  exports/
  insertion/validation_report.md

Copy bundled scripts into the package only when the user needs a self-contained handoff.

Design Invariants

• Use a pure white canvas and no decorative background assets.
• Keep all important text, arrows, legends, axes, and diagram structure editable in draw.io.
• Keep bitmap assets bounded in explicit foreground slots; never place them behind dense text.
• Route connectors with explicit waypoints around node rectangles and keep connectors behind nodes.
• Use content-derived canvas dimensions unless the user explicitly specifies the ratio.
• Make readability, export resolution, and export padding pass the configured target_output checks.

Bundled Resources

• references/composition_rules.md: layout, decomposition, routing, readability, export, and boundary rules.
• references/visual_plan_format.md: JSON shape and examples for visual_plan.json.
• references/provider_config.md: GPT Image environment variables and provider modes.
• scripts/generate_gpt_image_asset.py: generate GPT Image assets from all_asset_prompts.json.
• scripts/render_visual_plan_to_drawio.py: render visual_plan.json into .drawio and .mxgraph.xml.
• scripts/validate_visual_plan.py: detect overlap, connector crossings, boundary overflow, and readability/export issues.

Acceptance Criteria

• validate_visual_plan.py reports no errors and no unresolved high-impact warnings.
• The exported preview is readable at the planned insertion or viewing size.
• Important labels and diagram structure remain editable after opening the .drawio file in diagrams.net.
• Every generated asset has a prompt, output path, and placement metadata.
• The final package contains no required generated background asset.