paper-illustration-image2 skill

Paper Illustration Image2

Generate publication-quality paper figures using Claude as the planner/reviewer and a local Codex app-server MCP bridge as the raster renderer.

Core Design Philosophy

┌──────────────────────────────────────────────────────────────────────────┐
│                    MULTI-STAGE ITERATIVE WORKFLOW                        │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   User Request                                                           │
│       │                                                                  │
│       ▼                                                                  │
│   ┌─────────────┐                                                        │
│   │   Claude    │ ◄─── Step 1: Parse request, create initial prompt     │
│   │  (Planner)  │      - Extract components, labels, and data flow       │
│   │             │      - Write a paper-ready figure brief                │
│   └──────┬──────┘                                                        │
│          │                                                               │
│          ▼                                                               │
│   ┌─────────────┐                                                        │
│   │Claude/Codex │ ◄─── Step 2: Optimize layo

Constants

per shared-references/integration-contract.md §2 (Policy A — skill-local gate). Phase 3.2 (Arch C) moved the canonical implementation into skills/paper-illustration-image2/scripts/; tools/paperillustrationimage2.py remains as an os.execv shim so legacy resolver layers keep working without a re-install. Resolve via the Codex-side chain:

• RENDERER = codex-image2 — Native image generation bridge exposed through local Codex app-server
• OPTIONALTEXTCRITIC = spawnagent** — Optional text-only second opinion for layout/style checks
• MAXITERATIONS = 5** — Maximum refinement rounds
• TARGETSCORE = 9** — Minimum acceptable score (1-10)
• OUTPUTDIR = figures/aigenerated/ — Output directory
• TEXTLANGUAGE = English** — Default figure text language unless the user requests otherwise
• NATIVEIMAGEREQUIREMENT = strict — Accept only native imageGeneration output; reject shell/Python fallbacks
• IMAGE2HELPER — canonical name paperillustration_image2.py, resolved

IMAGE2_HELPER=""
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
  fi
  [ -f ".agents/skills/paper-illustration-image2/scripts/paper_illustration_image2.py" ] && IMAGE2_HELPER=".agents/skills/paper-illustration-image2/scripts/paper_illustration_image2.py"
  [ -z "$IMAGE2_HELPER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/skills/paper-illustration-image2/scripts/paper_illustration_image2.py" ] && IMAGE2_HELPER="$ARIS_REPO/skills/paper-illustration-image2/scripts/paper_illustration_image2.py"
  [ -z "$IMAGE2_HELPER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/paper_illustration_image2.py" ] && IMAGE2_HELPER="$ARIS_REPO/tools/paper_illustration_image2.py"
  [ -z "$IMAGE2_HELPER" ] && [ -f tools/paper_illustration_image2.py ] && IMAGE2_HELPER="tools/paper_illustration_image2.py"
  [ -z "$IMAGE2_HELPER" ] && [ -f ~/.codex/skills/paper-illustration-image2/scripts/paper_illustration_image2.py ] && IMAGE2_HELPER="$HOME/.codex/skills/paper-illustration-image2/sc

All invocations below use python3 "$IMAGE2_HELPER" .

CVPR/ICLR/NeurIPS Top-Tier Conference Style Guide

What "CVPR Style" Actually Means:

Visual Standards

• Clean white background — No decorative patterns or gradients unless extremely subtle
• Sans-serif fonts — Arial, Helvetica, or similarly clean paper-friendly typography
• Subtle color palette — Use 3-5 coordinated colors, not rainbow colors
• Print-friendly — Must remain understandable in grayscale
• Professional borders — Thin to medium, clean, and consistent

Layout Standards

• Horizontal flow — Left-to-right is the default for pipelines
• Clear grouping — Use spacing or subtle grouping boxes for related modules
• Consistent sizing — Similar components should have similar sizes
• Balanced whitespace — Avoid both cramped and overly sparse layouts

Arrow Standards (MOST CRITICAL)

• Thick strokes — Arrows must remain visible after paper scaling
• Clear arrowheads — Large, unmistakable arrowheads
• Dark colors — Prefer black or dark gray arrows
• Labeled — Important arrows should show what flows through them
• No crossings — Reorganize the figure to avoid crossings where possible
• CORRECT DIRECTION — Arrows must point to the right target

Visual Appeal (Academic Professional Style)

目标：既不保守也不花哨，找到平衡点

✅ Should have

• Subtle gradients — Gentle same-family gradients are acceptable
• Rounded corners — Modern but restrained rounded blocks
• Clear hierarchy — Main modules larger, secondary modules smaller
• Consistent color coding — Stable mapping between module types and colors
• Professional typography — Clean labels with readable size hierarchy

❌ Avoid

• ❌ Rainbow gradients
• ❌ Heavy drop shadows
• ❌ 3D perspective effects
• ❌ Glowing effects
• ❌ Decorative clip-art icons
• ❌ Slide-deck styling that feels flashy rather than paper-ready

✓ Ideal effect

• Looks intentional, professional, and immediately readable
• Has moderate visual appeal without becoming decorative
• Feels appropriate for a top-tier conference paper figure
• Survives PDF scaling and grayscale printing

What to AVOID (CRITICAL)

• ❌ Thin, hairline arrows
• ❌ Unlabeled or ambiguous connections
• ❌ Tiny unreadable text
• ❌ Flat, boring box soup with no hierarchy
• ❌ Over-decorated figures with shadows/glows/icons
• ❌ Wrong arrow directions

Scope

Not for: Statistical plots (use /paper-figure), deterministic vector topology figures (prefer /figure-spec), photo-realistic scenes

Workflow: MUST EXECUTE ALL STEPS

Step 0: Pre-flight Check

Render this checklist explicitly before starting:

📋 paper-illustration-image2 integration checklist:
   [ ] 1. python3 "$IMAGE2_HELPER" preflight --workspace <cwd> --json-out figures/ai_generated/preflight.json
   [ ] 2. Confirm preflight JSON says ok=true before rendering
   [ ] 3. Render via mcp__codex-image2__generate_start + generate_status
   [ ] 4. Finalize via python3 "$IMAGE2_HELPER" finalize --workspace <cwd> --best-image <best_png>
   [ ] 5. Verify artifacts via python3 "$IMAGE2_HELPER" verify --workspace <cwd> --json-out figures/ai_generated/verify.json

1. Create figures/ai_generated/ if it does not exist.
2. Confirm the request is suitable for a raster illustration:

• architecture diagram
• conceptual method figure
• workflow illustration

1. Prefer English figure text unless the user asked otherwise.
2. Run:

python3 "$IMAGE2_HELPER" preflight \
  --workspace <cwd> \
  --json-out figures/ai_generated/preflight.json

1. If preflight is not ok=true, stop and say so clearly.

Step 1: Claude Plans the Figure

Turn the user request into a fully specified image prompt. Include:

• figure type
• exact modules / stages
• flow direction
• labels to show
• data-flow arrows
• style constraints
• what to avoid

When the input is a method note or a paper section, summarize it first into a clean figure brief before writing the final image prompt.

Step 2: Layout Optimization

This step is required. Before rendering, refine the prompt into a concrete layout plan:

• exact module order
• spacing and grouping
• relative module prominence
• arrow routing and likely collision points

If spawn_agent is available, you may ask it for a short second-opinion layout critique here, but Claude should still complete this step even without Codex.

Use Codex layout critique for:

• missing components
• confusing layout
• weak flow hierarchy
• likely arrow-direction ambiguity or clutter

Step 3: Style Verification

This step is also required. Check the prompt against the intended paper style before rendering:

• palette is restrained and academic
• arrows are thick, dark, and readable
• labels are concise and in English unless requested otherwise
• the figure will read clearly in grayscale / print
• no glow, rainbow gradient, or slide-deck decoration slips in

If spawn_agent is available, you may ask it for a short text-only style audit, but do not block on it.

Step 4: Generate Through the Bridge

Call mcpcodex-image2generate_start with:

• prompt: the final image prompt
• cwd: current project root or paper workspace
• outputPath: figures/aigenerated/figurev1.png
• system: a short instruction like Academic paper figure. Prefer crisp English labels.
• timeoutSeconds: a bounded render timeout such as 180

Then call mcpcodex-image2generate_status with bounded waits until:

• done=true and status=completed, or
• done=true and status=failed

If generation fails, report the bridge error directly instead of hiding it.

Step 5: Review the Output

Review the generated image with a strict checklist: