Research Figure: TikZ Pipeline & Blender 3D Render Generator
Generate publication-quality figures through a streamlined conversation: understand the visualization need, confirm structure, generate code (TikZ or Blender Python), render, and iterate.
Prerequisites
- TikZ path: pdflatex with TikZ packages (install via
brew install --cask mactex-no-guion macOS) - Blender path: Blender 3.x+ (set
BLENDER_PATHenv var, or install to/Applications/on macOS, or add to PATH)
Phase 0: Route
Decide whether this is a TikZ or Blender figure based on the user's request.
Choose TikZ when the user wants:
- Method pipeline / flowchart / architecture diagram
- 2D box-and-arrow figures
- Any figure that is primarily text, boxes, and arrows
Choose Blender when the user wants:
- 3D rendered mesh (SMPL, FBX, OBJ)
- Teaser figure with multiple 3D characters
- Side-by-side method comparison with 3D meshes
- Skeleton visualization (3D keypoints + limbs)
- Bounding box visualization around 3D objects
- Any figure requiring 3D rendering
Choose Hybrid (TikZ + Blender) when:
- A pipeline figure has modules that need 3D-rendered illustrations
- E.g., a "3D Pose Estimation" module box should contain a rendered mesh image
If ambiguous, ask the user.
TikZ Path
Design Principles
These principles come from best practices in academic figure design:
- Card-based layout: Every module is enclosed in a rounded rectangle (card). Cards are connected by arrows. This makes the pipeline structure immediately clear.
- Low-saturation colors: Use muted, pastel colors. Never use vivid/saturated colors. The figure should look professional, not like a PowerPoint.
- Compact layout: Minimize whitespace. Align elements horizontally and vertically. The figure should be tight and dense, not scattered.
- Sans-serif fonts: Use
\sffamilythroughout for a modern, clean look. - Highlight contributions: The user's novel contribution modules should be visually distinct (thicker border, different background color) from standard modules.
- 2D visualization elements: Replace plain text with stylized visual elements where possible (feature maps as stacked rectangles, network blocks as labeled boxes, etc.). Keep these elements simple and 2D — no 3D rendering needed.
TikZ Phase 1: Understand the Method
When the user provides a description (abstract, method summary, or even a vague idea):
- Read the description carefully and extract the pipeline structure as a chain:
Input → Module1 → Intermediate1 → Module2 → ... → Output - For each module, identify:
- Name: a short descriptive name
- Type: data processing, neural network, optimization, inference, loss, etc.
- Is novel?: whether this is part of the user's contribution
- Internal elements: what happens inside (convolution, attention, MLP, etc.)
- Identify the overall flow pattern:
- Linear (most common)
- Loop/iterative
- Multi-branch (parallel processing)
- Two-stage (train + inference, or two sub-problems)
TikZ Phase 2: Confirm with User (1-2 rounds)
Present the extracted structure to the user in a clear, structured format using AskUserQuestion or direct conversation. Keep this brief — the goal is to confirm, not to design from scratch.
Round 1 (required): Show the pipeline structure and ask:
- Is the module breakdown correct?
- Which modules are the key contributions?
- Layout preference: horizontal (default), vertical, loop, two-stage, or multi-branch?
- Color scheme preference? (If not specified, default to Blue-Gray)
Format the pipeline clearly, for example:
Extracted pipeline:
Image Input → Feature Encoder → [YOUR METHOD: Adaptive Fusion Module] → Decoder → Output Mesh
Layout: Linear horizontal (left to right)
Highlight: "Adaptive Fusion Module" (novel contribution)
Color scheme: Blue-Gray (default)
Round 2 (only if needed): If the pipeline is complex or the user has special requests for internal module details, ask about:
- Specific visualization elements inside modules
- Special annotations or labels
- Loss functions or training signals to show
If the method is straightforward, skip Round 2 and proceed directly to generation.
TikZ Phase 3: Generate TikZ Code
Read the reference files to assemble the figure:
-
Read
references/layout_templates.md— pick the template matching the layout type (linear horizontal, vertical, loop, two-module, multi-branch). Use the template as the structural skeleton. -
Read
references/color_schemes.md— pick the user's chosen color scheme (or Blue-Gray default). Copy the\definecolorblock into the preamble. -
Read
references/tikz_elements.md— select element styles needed:- Module box styles (standard, novel, optional, io, group, loss)
- Arrow styles (standard, labeled, orthogonal, dashed, bidirectional)
- 2D elements (feature maps, network blocks, grids, image placeholders)
- Annotations (braces, callouts, dimension labels)
-
Compose the final
.texfile following these rules:- Use
\documentclass[border=5pt]{standalone}for a cropped output - Include all necessary packages and TikZ libraries
- Define all colors in the preamble
- Define all styles with
\tikzsetin the preamble - Place nodes using
positioninglibrary (e.g.,right=1.0cm of nodeA) - Keep spacing consistent: typically 0.8–1.2cm between nodes
- Ensure all text fits within its box (use
\\for line breaks if needed) - Use
\textbffor module titles,\footnotesize\color{textLight}for subtitles - Add arrow labels for important data flows (features, latent codes, etc.)
- Use math mode for symbols:
$\mathbf{z}$,$\mathcal{L}$, etc.
- Use
-
Write the
.texfile to the working directory (e.g.,figure.texor a user-specified name).
TikZ Phase 4: Compile and Self-Check
-
Compile using the bundled script:
bash .claude/skills/research-figure/scripts/compile_tikz.sh <path-to-tex-file> -
If compilation fails: read the error output, fix the LaTeX code, and retry. Common issues:
- Missing packages → add
\usepackage{...} - Undefined color → check
\definecolordefinitions - Node positioning errors → check node names and
ofreferences - Math mode errors → check
$...$matching
- Missing packages → add
-
View the result: Use the Read tool to view the generated PNG image.
-
Self-check the figure against this checklist:
- All text is readable (no overlapping)
- Arrows point in the correct direction
- Horizontal and vertical alignment is clean
- Layout is compact (no large empty areas)
- Color scheme is consistent and harmonious
- Novel contribution modules are visually highlighted
- Module names match what was agreed with the user
- Font is sans-serif throughout
-
If issues found: fix the TikZ code and recompile. Do NOT show a broken figure to the user.
TikZ Phase 5: Present and Iterate
- Show the compiled figure to the user (the PNG image).
- Explain the structure briefly.
- Ask if any changes are needed.
- Based on feedback, modify the TikZ code, recompile, and show again.
- Repeat until the user is satisfied.
- Provide the final
.texfile path so the user can:- Include it directly in their paper with
\input{} - Or compile it standalone and include via
\includegraphics{}
- Include it directly in their paper with
Blender Path
Blender Phase 1: Understand the Visualization
Identify the use case:
| Use Case | Description | Template |
|---|---|---|
| Teaser | N characters along X-axis, gradient materials, ground + fog + trajectory | templates/blender/template_teaser.py |
| Pipeline Module | Single mesh with transparent bg, for inclusion in TikZ | templates/blender/template_single_render.py |
| Comparison | 2+ characters, different colors (blue=ours, red=baseline) | templates/blender/template_comparison.py |
| Skeleton | 3D keypoint spheres + limb cylinders | Recipe D in references/blender_recipes.md |
| Bbox + Mesh | Wireframe bbox around a mesh | Recipe E in references/blender_recipes.md |
Extract from the user's request:
- Data file paths (FBX, OBJ, NPZ)
- Frame indices (which animation frames to show)
- Number of characters / instances
- Style preferences (colors, camera angle, with/without ground)
Blender Phase 2: Confirm with User
Present a structured summary:
Figure type: Multi-character teaser
Data: motion.fbx, frames [1, 30, 60, 90, 120, 150]
Layout: 6 characters along X-axis, spacing 1.5m
Camera: Wide shot, focal 85mm
Lighting: Studio three-point
Material: Gradient blue clay
Ground: Checkerboard with reflections
Fog: Yes (blue-gray)
Trajectory: Yes (gradient curve with arrow)
Output: 2048x1024 JPEG
One round is usually sufficient. Proceed to generation.
Blender Phase 3: Generate Blender Script
- Read
references/blender_api.mdfor function signatures. - Read
references/blender_recipes.mdfor the matching recipe pattern. - Generate a complete Python script that imports from
blender_utils.*(NOT frommyblender.*). - The script MUST support a
--previewflag that switches between fast preview and final render mode (see below). - Write the script to the working directory (e.g.,
render_teaser.py).
The script must be self-contained and runnable via:
bash .claude/skills/research-figure/scripts/render_blender.sh <script.py> -- [args]
Two-Pass Render Design
Every generated Blender script MUST support two rendering modes controlled by a --preview CLI flag:
import argparse
def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("--preview", action="store_true",
help="Fast low-res Eevee preview")
# ... other args ...
if '--' in sys.argv:
args = parser.parse_args(sys.argv[sys.argv.index('--') + 1:])
else:
args = parser.parse_args([])
return args
In the render section, branch on args.preview:
scene = bpy.context.scene
if args.preview:
# Fast preview: Eevee, low resolution, PNG
set_eevee_renderer(scene, camera)
preview_path = output_path.rsplit('.', 1)[0] + '_preview.png'
set_output_properties(scene, output_file_path=preview_path,
res_x=800, res_y=400, format='PNG')
else:
# Final render: Cycles, full resolution
set_cycles_renderer(scene, camera, num_samples=256,
use_transparent_bg=False)
set_output_properties(scene, output_file_path=output_path,
res_x=2048, res_y=1024, format='JPEG')
render_with_progress()
Preview mode settings:
- Engine: Eevee (
set_eevee_renderer) — orders of magnitude faster than Cycles - Resolution: 1/2 to 1/4 of final (e.g., 800x400 for a 2048x1024 teaser)
- Format: PNG (for quick viewing)
- Output path: append
_previewsuffix before the extension
Final mode settings:
- Engine: Cycles (
set_cycles_renderer) — ray-traced, publication quality - Resolution: full target resolution
- Samples: 256+ for final quality
Blender Phase 4: Preview Render and Self-Check
Always render a fast preview first. Do NOT go straight to a Cycles render.
-
Run the preview render:
bash .claude/skills/research-figure/scripts/render_blender.sh <script.py> -- --preview -
If rendering fails: read the error output, fix the Python script, and retry. Common issues:
ModuleNotFoundError→ PYTHONPATH issue (render_blender.sh handles this automatically)KeyErroron node inputs → Blender version compatibility (use try/except)- Black/empty render → camera not set, or objects not visible
- GPU errors → set
prefer_gpu=Falsein set_cycles_renderer
-
View the preview image: Use the Read tool to view the generated
*_preview.png. -
Self-check the preview:
- Objects are visible and properly positioned
- Camera angle shows the subject clearly
- Lighting is reasonable (Eevee lighting differs slightly from Cycles but composition should be correct)
- Materials are applied (not default gray)
- Background is clean
- Character spacing and layout look correct
-
If issues found: fix the script and re-run the preview. Do NOT show a broken figure to the user.
Blender Phase 5: Present Preview and Get Approval
- Show the preview image to the user.
- Explain that this is a fast Eevee preview for layout/composition check — the final Cycles render will have better lighting, materials, and anti-aliasing.
- Ask the user to confirm the preview looks correct before proceeding to the full render. Use AskUserQuestion with options like:
- "Looks good, render final version" — proceed to Phase 6
- "Adjust camera / lighting / spacing" — iterate on the script and re-render preview
- "Change frames / characters" — modify and re-render preview
- If the user requests changes, modify the script, re-run the preview (not full render), and show again.
- Repeat until the user approves the preview.
Blender Phase 6: Final Render
Only proceed here after the user has approved the preview.
-
Run the final Cycles render (without
--preview):bash .claude/skills/research-figure/scripts/render_blender.sh <script.py>Note: this will take significantly longer than the preview. This is expected.
-
View the result: Use the Read tool to view the final rendered image.
-
Show the final image to the user.
-
If the user wants further adjustments, go back to Phase 5 (preview iteration) rather than re-running the slow Cycles render for each tweak.
Hybrid: TikZ + Blender Recursive Call
When a TikZ pipeline figure needs 3D-rendered module illustrations (e.g., a box in the pipeline showing a 3D mesh), generate the Blender render first, then include the output image in the TikZ figure. The workflow is:
- Route to Blender for the 3D component(s).
- Generate and render the Blender image(s) following the Blender Path above.
- Route to TikZ for the pipeline figure, using
\includegraphics{...}to embed the Blender renders into the pipeline boxes. - The final output is a single TikZ figure containing both 2D boxes/arrows and embedded 3D renders.
Clean Up
At the end of a successful session, offer to place the final outputs (.tex, .py, rendered .png/.jpg) in a directory of the user's choosing.