figure-generation

name	figure-generation
description	Generate all publication-quality PNG figures for the paper from figure prompts using Nano Banana Pro (Gemini 3 Pro Image). Use when user says "生成图", "generate figures", "画图", or after all upstream skills/agents have produced figure prompts.
argument-hint	["all / specific figure_id"]
allowed-tools	Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, WebFetch

Skill-7: Academic Figure Generation (Nano Banana Pro)

Generate publication-quality PNG figures for: $ARGUMENTS

Overview

This skill reads figure prompt files from output/figure_prompts/, polishes each prompt for academic quality, matches it with a reference example image, then calls Nano Banana Pro (Gemini 3 Pro Image, gemini-3-pro-image-preview) to directly generate publication-quality PNG figures.

Key features:

• Prompt polishing — Claude reviews and refines each prompt before sending to Gemini (serif font, academic color palette, clear arrows, no legend)
• Reference image matching — each figure type maps to an example PNG for style guidance, passed to Gemini as inline image input
• Direct PNG output — Gemini generates high-resolution PNG natively (1K/2K/4K)
• Academic style enforcement — consistent palette, serif typography, professional flowchart/architecture style
• REST API (urllib) — uses raw REST calls, NOT the Python SDK (SDK has known issues with proxy URLs)

Environment Setup

export GEMINI_BASE_URL="https://api.openai-proxy.org/google"
export GOOGLE_API_KEY="your-api-key-here"

Or configure in scripts/config.yaml:

api:
  base_url: "https://api.openai-proxy.org/google"
  key: "your-api-key"
  model: "gemini-3-pro-image-preview"

Inputs

Input	Path	Purpose
Figure prompts	output/figure_prompts/{review,methodology,results,paper}/*.md	Content descriptions for each figure
Reference examples	references/examples/{review,methodology,results,paper}/*.png	Style reference PNGs sent to Gemini as inline image
Style guide	references/academic_figure_style.md	Color palette, typography, layout rules
Config	scripts/config.yaml	API settings

Outputs

output/figures/
├── review/
│   ├── fig_prisma_flowchart.png         # Publication-quality PNG (2K default)
│   ├── fig_research_taxonomy.png
│   └── ...
├── methodology/
│   ├── fig_system_architecture.png
│   ├── fig_kg_pipeline.png
│   └── ...
├── results/
│   ├── fig_retrieval_comparison.png
│   ├── fig_llm_comparison.png
│   └── ...
├── paper/
│   ├── fig_introduction_overview.png
│   └── ...
└── figure_generation_report.json        # Per-figure success/failure log

Format: PNG only. No SVG/XML (Gemini outputs raster PNG natively; for publication this is sufficient at 2K/4K resolution).

References & Examples

Reference Example PNGs (User Provides)

Place PNG reference images in these folders. Each image is sent to Gemini as an inline image reference — Gemini matches the visual style but uses the content from the figure prompt.

references/examples/
├── review/
│   ├── prisma_flowchart_example.png
│   ├── research_taxonomy_example.png
│   ├── concept_trend_example.png
│   └── literature_positioning_example.png
├── methodology/
│   ├── system_architecture_example.png
│   ├── kg_pipeline_example.png
│   ├── retrieval_architecture_example.png
│   ├── ontology_schema_example.png
│   └── chatbot_interface_example.png
├── results/
│   ├── kg_visualization_example.png
│   ├── bar_chart_comparison_example.png
│   ├── radar_chart_example.png
│   └── table_figure_example.png
└── paper/
    └── graphical_abstract_example.png

Style Guide

Reference	Path	Purpose
Academic Figure Style	references/academic_figure_style.md	Palette (hex), serif typography, layout rules

Workflow

Phase 1: Pre-check

1. Verify output/figure_prompts/ exists and has .md files
2. Verify scripts/config.yaml has API key configured (or GOOGLE_API_KEY env var set)
3. If API key missing, ask user to configure
4. List all figure prompts and their matching reference images

Report to user:

Found [N] figure prompts:
  review/fig_prisma_flowchart.md        → ref: prisma_flowchart_example.png ✓
  review/fig_research_taxonomy.md       → ref: research_taxonomy_example.png ✓
  methodology/fig_system_architecture.md → ref: system_architecture_example.png ✓
  methodology/fig_kg_pipeline.md        → ref: (no reference) ⚠
  ...

Phase 2: Prompt Polishing (Claude Does This)

Before sending each prompt to Gemini, Claude MUST review and polish it. This is where prompt quality translates to figure quality.

For each figure prompt file:

1. Read the raw prompt from output/figure_prompts/.../*.md
2. Read the style guide from references/academic_figure_style.md
3. Polish the prompt to ensure these requirements (from the Nano Banana Pro template):
   • Language: All text labels in English
   • Font: Serif font (Times New Roman style)
   • Overall style: Professional academic architecture/flowchart
   • Colors: Primary blue and gray; accent colors (warm orange/teal/green) for innovation highlights
   • Data flow: Clear arrows indicating information flow. No legend.
   • Schematics: Include representative illustrative elements for each stage/component
   • Begin the prompt with "Create a..." — per Nano Banana Pro template
   • No meta-text: Prompt must not ask the image to include layout annotations or font specifications
4. Save the polished prompt back (overwrite or save as _polished.md)

Prompt polishing template (inspired by the Nano Banana Pro template):

Create a [figure type] for "[topic]".

Requirements:
- Language: All text labels in English
- Font: Serif font (Times New Roman style)
- Overall aesthetic: Professional academic architecture/flowchart
- Primary colors: clear blue and gray
- Accent colors for key innovations: warm orange / teal / green
- Data/information flow: clear directional arrows (NO legend)
- Schematics: AI generates representative illustrations for each stage
- Layout: [horizontal / vertical / grid], balanced composition
- Size: single-column (1000px) or double-column (2000px)

Content:
[detailed content description from the original figure prompt]

Reference context:
[any relevant data source or paper reference]

Polishing checklist per prompt:

• Starts with "Create a..."
• All text labels specified as English
• Serif font requirement stated
• Academic color palette specified
• Clear arrow direction described
• "No legend" explicitly mentioned
• Layout direction (vertical/horizontal) clear
• Size specified (single/double column)
• Data source file referenced (for data-driven figures)
• Reference image instruction included (if available)

Phase 3: Generate Figures

Run the generation script:

# Process all prompts
python scripts/generate_figure.py --all --output-dir output/figures --verbose

# Or process a single prompt
python scripts/generate_figure.py --prompt output/figure_prompts/review/fig_prisma_flowchart.md -o output/figures -v

What the script does for each figure:

1. Load polished prompt + frontmatter (aspect_ratio, image_size)
2. Find matching reference example PNG
3. Build API request: polished prompt + style guide + inline reference image (if exists)
4. Call Gemini via REST API (urllib) — not SDK (proxy compatibility)
5. Extract PNG from response (inlineData field, base64-decoded)
6. Save as .png to output/figures/{section}/{figure_id}.png

Phase 4: Quality Review

After generation, review each figure by opening the PNG:

1. Content matches prompt? All requested elements present?
2. Labels readable? All text rendered correctly in English?
3. Colors match academic palette? Blue/gray primary, warm accents?
4. Professional appearance? No artifacts, proper spacing?
5. Serif font used? Check text rendering.

If a figure is unsatisfactory:

• Refine the prompt with more specific instructions (add examples, clarify colors, specify layout)
• Regenerate that single figure (not the whole batch)
• Do NOT regenerate all figures — cost and time.

Phase 5: Generate Report

The script automatically creates output/figures/figure_generation_report.json.

Additionally, print a summary for the user:

## Figure Generation Summary

| Figure | Section | Aspect | Size | Reference Used | Status |
|--------|---------|--------|------|----------------|--------|
| fig_prisma_flowchart | Review | 16:9 | 2K | prisma_example.png | ✓ |
| fig_system_architecture | Methodology | 16:9 | 2K | system_arch_example.png | ✓ |
| ... | ... | ... | ... | ... | ... |

Total: [N] figures generated, saved as PNG to output/figures/

Phase 6: Update plan04.md

If figure generation is tracked in plan04.md, update task status per Auto-Update Protocol.

Figure Type → Reference Mapping

Figure ID Pattern	Reference Example	Category
fig_prisma*	review/prisma_flowchart_example.png	Review
fig_research_taxonomy*	review/research_taxonomy_example.png	Review
fig_concept*	review/concept_trend_example.png	Review
fig_*positioning*	review/literature_positioning_example.png	Review
fig_system_architecture*	methodology/system_architecture_example.png	Methodology
fig_kg_pipeline*	methodology/kg_pipeline_example.png	Methodology
fig_retrieval*	methodology/retrieval_architecture_example.png	Methodology
fig_ontology*	methodology/ontology_schema_example.png	Methodology
fig_chatbot*	methodology/chatbot_interface_example.png	Methodology
fig_kg_vis*	results/kg_visualization_example.png	Results
fig_*comparison*	results/bar_chart_comparison_example.png	Results
fig_*quality* / fig_*radar*	results/radar_chart_example.png	Results
fig_introduction*	paper/graphical_abstract_example.png	Paper

Nano Banana Pro API Details

• Model: gemini-3-pro-image-preview
• Endpoint: {BASE_URL}/v1beta/models/gemini-3-pro-image-preview:generateContent
• Method: REST (urllib), not SDK
• Response modalities: ["TEXT", "IMAGE"]
• Image config:
  • aspectRatio: 1:1, 3:2, 16:9 (default), 9:16, 21:9
  • imageSize: 1K (fast), 2K (balanced, default), 4K (highest quality)
• Timeout: 180s default (increase for 4K)
• Response format: candidates[0].content.parts[*].inlineData.data (base64 PNG)

Common Pitfalls (from Nano Banana Pro Reference)

Problem	Cause	Fix
Extra inputs are not permitted	Using Python SDK with proxy URL	Use REST API (urllib) — the bundled script does this
Empty/blocked response	Prompt triggered safety filter	Rephrase prompt, avoid restricted content
Timeout	Large image (4K) or slow network	Increase --timeout, try 2K first
Text labels in wrong language	Prompt didn't specify English	Add "Language: All text labels in English" to prompt
No serif font	Prompt didn't specify font	Explicitly state "Serif font (Times New Roman style)"
Legend appears uninvited	Prompt didn't explicitly forbid it	Add "No legend" to the prompt

Key Rules

1. Polish before generating: Claude MUST review every prompt before it goes to Gemini. Quality of input = quality of output.
2. PNG output only: Nano Banana Pro generates raster PNG natively. No SVG/XML — 2K/4K PNG is sufficient for publication.
3. REST API only: Use urllib (the bundled script), NEVER the google-genai SDK with proxy URLs.
4. Reference images guide style, not content: Gemini matches visual style but uses content from the prompt.
5. Academic palette enforced: All figures use the palette from academic_figure_style.md (blue + gray primary, warm accents).
6. Serif font mandatory: All text labels in serif font (Times New Roman style).
7. No legend by default: Unless specifically needed, prompt states "No legend" to keep figures clean.
8. Config-driven: API base_url, key, model in scripts/config.yaml. No hardcoded credentials.
9. One figure at a time if quality issues: Don't regenerate all — fix and retry the specific one.
10. Report missing references: If no reference PNG exists for a figure, warn the user before proceeding.
11. All output to output/figures/: Organized by category (review, methodology, results, paper).

Composing with Other Skills

skill-5 /review-writing            → output/figure_prompts/review/
@kg-graphrag-builder-agent         → output/figure_prompts/methodology/ + results/
@evaluation-agent                  → output/figure_prompts/results/
skill-6 /paper-writing             → output/figure_prompts/paper/
skill-7 /figure-generation         → output/figures/ (PNG)  ← YOU ARE HERE
skill-8 /paper-doc                 → embeds PNG figures into final_paper.docx