codex-visio-paper-figure-skill

Codex Visio Paper Figure Skill

Skill by ara.so — Codex Skills collection.

Overview

The Codex Visio Paper Figure Skill transforms reference images (screenshots, AI-generated diagrams, paper figures) into editable Microsoft Visio .vsdx files composed of native shapes, text boxes, connectors, and groups. It's designed for academic paper workflows where you need to:

• Rebuild model architecture diagrams, flowcharts, and multi-panel scientific figures
• Replace embedded images with true vector graphics
• Maintain consistent styling across paper figures
• Export the same source .vsdx to PNG, SVG, PDF, and PPTX

Core principle: The final .vsdx must use Visio native primitives (rectangles, circles, lines, text), NOT just embed the original reference image as a background.

Installation

Clone this skill repository into your Codex skills directory:

# Windows
git clone https://github.com/pengjunchi0/codex-visio-paper-figure-skill.git "$env:USERPROFILE\.codex\skills\codex-visio-paper-figure-skill"

Restart Codex or start a new session to load the skill.

Requirements

• Windows (Visio COM automation requires Windows)
• Microsoft Visio (for full drawing automation)
• PowerShell (for scripting)
• Microsoft PowerPoint (optional, for PPTX export)
• Codex Desktop or any Codex environment with local file access

Key Scripts

1. visio_rebuild_scaffold.ps1

Main scaffolding script for rebuilding diagrams with native Visio shapes.

Parameters:

• -VsdxPath - Output .vsdx file path
• -PageW, -PageH - Visio page dimensions (inches)
• -RefW, -RefH - Reference image pixel dimensions
• -PreviewPath - Path to save PNG preview
• -ExportFormats - Comma-separated: png, svg, pdf, pptx
• -OutputDir - Directory for exported files

Basic usage:

powershell -ExecutionPolicy Bypass -File scripts\visio_rebuild_scaffold.ps1 `
  -VsdxPath "C:\work\model.vsdx" `
  -PageW 16 `
  -PageH 9 `
  -RefW 1600 `
  -RefH 900 `
  -PreviewPath "C:\work\preview.png" `
  -ExportFormats svg,pdf,pptx `
  -OutputDir "C:\work\exports"

2. visio_page_tools.ps1

Utility for exporting existing .vsdx files and inspecting package structure.

Parameters:

• -VsdxPath - Input .vsdx file
• -ExportFormats - Formats to export
• -OutputDir - Export destination
• -OutputBaseName - Base name for exported files
• -InspectPackage - Check for embedded images (validation)

Example:

powershell -ExecutionPolicy Bypass -File scripts\visio_page_tools.ps1 `
  -VsdxPath "C:\work\diagram.vsdx" `
  -ExportFormats svg,pdf,pptx `
  -OutputDir "C:\work\exports" `
  -InspectPackage

3. visio_export_formats.ps1

Reusable export functions (PNG, SVG, PDF, PPTX). Sourced by other scripts.

Core Drawing Functions

The scaffold provides coordinate mapping helpers to prevent panel overlap in complex multi-panel figures:

Global Coordinate Mapping

# Convert reference image pixel coordinates to Visio page inches
$x_inch = Ref2Page $x_pixel "x"
$y_inch = Ref2Page $y_pixel "y"

Panel-Local Coordinates (v1.1.1+)

For complex diagrams with multiple panels, define panel boundaries and use relative coordinates:

# Define panel A boundaries (in reference pixel coordinates)
$panelA = @{ X0=50; Y0=50; X1=750; Y1=450 }

# Draw rectangle at 10% from panel left, 20% from top, 30% wide, 25% tall
RectRel -Panel $panelA -RelX 0.1 -RelY 0.2 -RelW 0.3 -RelH 0.25 `
  -Fill "rgb(200,220,240)" -Line "rgb(80,100,120)" -LineW 1.5 `
  -Label "Module A"

# Draw text at relative position within panel
TextRel -Panel $panelA -RelX 0.5 -RelY 0.1 `
  -Text "Panel A Title" -FontSize 16 -Bold

# Draw oval
OvalRel -Panel $panelA -RelCX 0.5 -RelCY 0.8 -RelW 0.2 -RelH 0.1 `
  -Fill "rgb(255,200,200)"

# Draw line within panel
LineRel -Panel $panelA -RelX1 0.3 -RelY1 0.5 -RelX2 0.7 -RelY2 0.5 `
  -Arrow "End" -LineW 2

Validation Helpers

# Assert a bounding box stays within panel
Assert-RelBox -Panel $panelA -RelX 0.1 -RelY 0.2 -RelW 0.3 -RelH 0.25 `
  -ElementName "Module A"

# Assert a point stays within panel
Assert-RelPoint -Panel $panelA -RelX 0.5 -RelY 0.9 -PointName "Label"

These helpers throw errors if elements exceed panel boundaries, preventing overlap and misalignment.

Real-World Example: Multi-Panel Architecture Diagram

Suppose you have a 1600×900px reference image with three panels:

# scripts/rebuild_architecture.ps1
param(
  [string]$VsdxPath = "C:\papers\architecture.vsdx",
  [string]$OutputDir = "C:\papers\exports"
)

# Dimensions
$pageW = 16
$pageH = 9
$refW = 1600
$refH = 900

# Define panels (in reference pixel coordinates)
$panelA = @{ X0=50;   Y0=50;   X1=750;  Y1=450 }  # Input Processing
$panelB = @{ X0=800;  Y0=50;   X1=1550; Y1=450 }  # Model Architecture
$panelC = @{ X0=50;   Y0=500;  X1=1550; Y1=850 }  # Output & Metrics

# Start Visio
$visio = New-Object -ComObject Visio.Application
$visio.Visible = $true
$docs = $visio.Documents
$doc = $docs.Add("")
$page = $doc.Pages.Item(1)
$page.PageSheet.CellsSRC(1,1,0).FormulaU = "$pageW in"
$page.PageSheet.CellsSRC(1,1,1).FormulaU = "$pageH in"

# Helper functions
function Ref2Page($val, $dim) {
  if ($dim -eq "x") { return $val / $refW * $pageW }
  else { return $pageH - ($val / $refH * $pageH) }
}

function RectRel {
  param($Panel, $RelX, $RelY, $RelW, $RelH, $Fill, $Line, $LineW, $Label)
  
  Assert-RelBox -Panel $Panel -RelX $RelX -RelY $RelY -RelW $RelW -RelH $RelH -ElementName $Label
  
  $px0 = $Panel.X0 + $RelX * ($Panel.X1 - $Panel.X0)
  $py0 = $Panel.Y0 + $RelY * ($Panel.Y1 - $Panel.Y0)
  $pw = $RelW * ($Panel.X1 - $Panel.X0)
  $ph = $RelH * ($Panel.Y1 - $Panel.Y0)
  
  $x = Ref2Page $px0 "x"
  $y = Ref2Page $py0 "y"
  $w = $pw / $refW * $pageW
  $h = $ph / $refH * $pageH
  
  $shp = $page.DrawRectangle($x, $y - $h, $x + $w, $y)
  $shp.CellsSRC(1,3,0).FormulaU = """$Fill"""
  $shp.CellsSRC(1,2,0).FormulaU = """$Line"""
  $shp.CellsSRC(1,2,1).FormulaU = "$LineW pt"
  if ($Label) { $shp.Text = $Label }
}

function Assert-RelBox {
  param($Panel, $RelX, $RelY, $RelW, $RelH, $ElementName)
  if ($RelX -lt 0 -or $RelY -lt 0 -or ($RelX + $RelW) -gt 1 -or ($RelY + $RelH) -gt 1) {
    throw "Element '$ElementName' exceeds panel bounds"
  }
}

# Panel A: Input Processing
RectRel -Panel $panelA -RelX 0.1 -RelY 0.1 -RelW 0.35 -RelH 0.2 `
  -Fill "rgb(220,240,255)" -Line "rgb(80,120,160)" -LineW 1.5 `
  -Label "Image Input"

RectRel -Panel $panelA -RelX 0.55 -RelY 0.1 -RelW 0.35 -RelH 0.2 `
  -Fill "rgb(220,255,220)" -Line "rgb(80,160,80)" -LineW 1.5 `
  -Label "Preprocessor"

# Panel B: Model Architecture
RectRel -Panel $panelB -RelX 0.1 -RelY 0.15 -RelW 0.25 -RelH 0.3 `
  -Fill "rgb(255,240,220)" -Line "rgb(200,120,80)" -LineW 1.5 `
  -Label "Encoder"

RectRel -Panel $panelB -RelX 0.4 -RelY 0.15 -RelW 0.25 -RelH 0.3 `
  -Fill "rgb(255,220,240)" -Line "rgb(200,80,120)" -LineW 1.5 `
  -Label "Transformer"

RectRel -Panel $panelB -RelX 0.7 -RelY 0.15 -RelW 0.25 -RelH 0.3 `
  -Fill "rgb(240,220,255)" -Line "rgb(120,80,200)" -LineW 1.5 `
  -Label "Decoder"

# Panel C: Output
RectRel -Panel $panelC -RelX 0.3 -RelY 0.3 -RelW 0.4 -RelH 0.4 `
  -Fill "rgb(255,255,220)" -Line "rgb(160,160,80)" -LineW 1.5 `
  -Label "Output Layer"

# Save
$doc.SaveAs($VsdxPath)
Write-Host "Saved: $VsdxPath"

# Export formats
$formats = @("png", "svg", "pdf", "pptx")
foreach ($fmt in $formats) {
  $outPath = Join-Path $OutputDir "architecture.$fmt"
  # Call export function (from visio_export_formats.ps1)
  # Implementation details in actual script
  Write-Host "Exported: $outPath"
}

$visio.Quit()

Common Patterns

1. Rebuild from Reference Image

# User provides reference.png at 1920x1080
powershell -ExecutionPolicy Bypass -File scripts\visio_rebuild_scaffold.ps1 `
  -VsdxPath "C:\work\figure1.vsdx" `
  -PageW 16 `
  -PageH 9 `
  -RefW 1920 `
  -RefH 1080 `
  -PreviewPath "C:\work\figure1_preview.png" `
  -ExportFormats svg,pdf `
  -OutputDir "C:\work\exports"

Inside the scaffold, customize the drawing logic to match the reference layout.

2. Update Existing .vsdx Styling

Open existing file, modify colors/fonts, re-export:

$visio = New-Object -ComObject Visio.Application
$doc = $visio.Documents.Open("C:\work\existing.vsdx")
$page = $doc.Pages.Item(1)

# Change all rectangles to new color
foreach ($shp in $page.Shapes) {
  if ($shp.CellExists("FillForegnd", 0)) {
    $shp.CellsSRC(1,3,0).FormulaU = """rgb(200,220,240)"""
  }
}

$doc.Save()
$visio.Quit()

3. Check for Embedded Images

powershell -ExecutionPolicy Bypass -File scripts\visio_page_tools.ps1 `
  -VsdxPath "C:\work\diagram.vsdx" `
  -InspectPackage

Looks for large PNG/JPG files in /visio/media/ inside the .vsdx ZIP. Warns if the diagram is just an embedded image.

Acceptance Criteria

A correctly rebuilt .vsdx should:

• ✅ Match the reference layout
• ✅ Use native Visio shapes (rectangles, circles, lines, text)
• ✅ Have editable text and shapes
• ✅ NOT embed the entire reference image as the final content
• ✅ Use consistent colors, fonts, and line weights
• ✅ For multi-panel figures: no panel overlap, no elements crossing boundaries
• ✅ Export cleanly to SVG, PDF, PNG, PPTX from the same source .vsdx

Troubleshooting

"Visio COM object not found"

Install Microsoft Visio. The COM automation API requires a licensed Visio installation on Windows.

Exported files are empty

Check that the .vsdx saved successfully before export. Verify the page has visible shapes:

$page.Shapes.Count  # Should be > 0

Panels overlap in multi-panel figures

Use panel-local coordinates with Assert-RelBox and Assert-RelPoint:

Assert-RelBox -Panel $panelA -RelX 0.1 -RelY 0.2 -RelW 0.8 -RelH 0.6 `
  -ElementName "BigModule"

This throws an error if the box exceeds panel boundaries.

Text is cut off

Increase relative width/height, or use multi-line text:

$shp.Text = "Line 1`nLine 2`nLine 3"

Colors don't match reference

Use a color picker on the reference image and convert to RGB:

$shp.CellsSRC(1,3,0).FormulaU = """rgb(123,210,98)"""

Export Format Details

Format	Method	Notes
PNG	$page.Export($path)	Raster, good for previews
SVG	FixedFormat = 4	Vector, editable in Illustrator/Inkscape
PDF	FixedFormat = 2	Vector, for paper submission
PPTX	PowerPoint COM	Creates slide with embedded SVG

PPTX export example:

$ppt = New-Object -ComObject PowerPoint.Application
$ppt.Visible = $true
$pres = $ppt.Presentations.Add()
$slide = $pres.Slides.Add(1, 12)  # 12 = ppLayoutBlank

# Export Visio page to SVG first
$svgPath = "C:\temp\diagram.svg"
$page.Export($svgPath)

# Insert SVG into slide
$slide.Shapes.AddPicture($svgPath, $false, $true, 0, 0, 720, 405)
$pres.SaveAs("C:\work\diagram.pptx")
$ppt.Quit()

Version History

• v1.1.1 - Panel calibration, local coordinates, anti-overlap validation
• v1.1 - Multi-format export (PNG, SVG, PDF, PPTX)
• v1.0 - Initial release with Visio COM scaffolding

References

• SKILL.md - Main workflow and rules
• references/rebuild-guidelines.md - Detailed drawing strategies for complex scientific figures
• scripts/visio_export_formats.ps1 - Export function library
• scripts/visio_page_tools.ps1 - Inspection and export utilities
• scripts/visio_rebuild_scaffold.ps1 - Drawing scaffolding with coordinate helpers

---

When to use this skill:

• User wants to convert a paper diagram to editable Visio
• User needs SVG/PDF/PPTX exports from a single source
• User wants to verify a .vsdx isn't just an embedded image
• User needs consistent styling across multiple paper figures

When NOT to use this skill:

• User just wants to embed an image in a slide deck (use PowerPoint directly)
• User needs pure raster image editing (use Photoshop/GIMP)
• User doesn't need Visio-native editability