研究圖表:TikZ 流程圖與 Blender 3D 渲染生成器
透過精簡的對話流程來生成符合出版標準的圖表:了解視覺化需求、確認結構、生成代碼(TikZ 或 Blender Python)、渲染,然後迭代修改。
先決條件
- TikZ 路徑:
pdflatex需包含 TikZ 套件(在 macOS 上可透過brew install --cask mactex-no-gui安裝) - Blender 路徑:Blender 3.x 或更新版本(設定環境變數
BLENDER_PATH,或在 macOS 上安裝至/Applications/,或將其加入 PATH)
階段 0:路由
根據使用者的請求,判斷這應是 TikZ 還是 Blender 圖表。
選擇 TikZ 當使用者需要:
- 方法流程圖 / 流程圖 / 架構圖
- 2D 方框與箭頭圖
- 任何主要由文字、方框和箭頭組成的圖表
選擇 Blender 當使用者需要:
- 3D 渲染網格(SMPL, FBX, OBJ)
- 包含多個 3D 角色的預覽圖
- 使用 3D 網格的並排方法比較圖
- 骨架視覺化(3D 關鍵點 + 肢體)
- 3D 物體周圍的邊界框視覺化
- 任何需要 3D 渲染的圖表
選擇混合模式(TikZ + Blender) 當:
- 流程圖中的某個模組需要 3D 渲染的插圖
- 例如,一個「3D 姿態估計」模組方塊中應包含一個渲染後的網格圖像
如果模稜兩可,請詢問使用者。
TikZ 路徑
設計原則
以下原則源自學術圖表設計的最佳實務:
- 卡片式佈局:每個模組都包含在一個圓角矩形(卡片)內。卡片之間用箭頭連接。這能讓流程結構一目了然。
- 低飽和度色彩:使用柔和、粉彩的顏色。切勿使用鮮豔或高飽和度的顏色。圖表應看起來專業,而不是像 PowerPoint。
- 緊湊佈局:最小化空白區域。水平和垂直對齊元素。圖表應緊湊、密集,而非分散。
- 無襯線字體:全程使用
\sffamily,以呈現現代、簡潔的外觀。 - 凸顯貢獻:使用者創新的模組應在視覺上與標準模組有所區別(使用較粗的邊框、不同的背景色)。
- 2D 視覺化元素:盡可能用風格化的視覺元素取代純文字(例如,用堆疊的矩形表示特徵圖,用帶標籤的方框表示網路區塊等)。這些元素應保持簡單且為 2D 樣式——無需 3D 渲染。
TikZ 階段 1:理解方法
當使用者提供描述(摘要、方法摘要,甚至只是粗略的想法)時:
- 仔細閱讀描述,並提取流程結構作為一個鏈:
Input → Module1 → Intermediate1 → Module2 → ... → Output - 對於每個模組,確定:
- 名稱:一個簡短的描述性名稱
- 類型:資料處理、神經網路、最佳化、推理、損失等
- 是否創新?:這是否是使用者貢獻的一部分
- 內部元素:內部發生什麼(卷積、注意力、MLP 等)
- 確定整體流程模式:
- 線性(最常見)
- 循環/迭代
- 多分支(並行處理)
- 兩階段(訓練 + 推理,或兩個子問題)
TikZ 階段 2:與使用者確認(1-2 輪)
使用 AskUserQuestion 或直接對話,以清晰、結構化的格式向使用者展示提取出的結構。保持簡潔——目標是確認,而非從頭設計。
第 1 輪(必須): 顯示流程結構並詢問:
- 模組劃分是否正確?
- 哪些模組是關鍵貢獻?
- 佈局偏好:水平(預設)、垂直、循環、兩階段或多分支?
- 色彩方案偏好?(若未指定,則預設為藍灰色)
清晰地格式化流程,例如:
提取的流程:
Image Input → Feature Encoder → [YOUR METHOD: Adaptive Fusion Module] → Decoder → Output Mesh
佈局:線性水平(從左到右)
凸顯:"Adaptive Fusion Module"(創新貢獻)
色彩方案:藍灰色(預設)
第 2 輪(僅在需要時): 如果流程複雜或使用者對模組內部細節有特殊要求,則詢問:
- 模組內部的特定視覺化元素
- 特殊的註解或標籤
- 要顯示的損失函數或訓練信號
如果方法很直接,則跳過第 2 輪,直接進入生成階段。
TikZ 階段 3:生成 TikZ 代碼
閱讀參考檔案來組合圖表:
-
閱讀
references/layout_templates.md— 選擇與佈局類型(線性水平、垂直、循環、雙模組、多分支)相符的範本。將此範本作為結構骨架。 -
閱讀
references/color_schemes.md— 選擇使用者選擇的色彩方案(或預設的藍灰色)。將\definecolor區塊複製到前言中。 -
閱讀
references/tikz_elements.md— 選擇所需元素樣式:- 模組方塊樣式(標準、創新、可選、輸入輸出、群組、損失)
- 箭頭樣式(標準、帶標籤、正交、虛線、雙向)
- 2D 元素(特徵圖、網路區塊、網格、圖像佔位符)
- 註解(大括號、標註、尺寸標籤)
-
組合最終的
.tex檔案,遵循以下規則:- 使用
\documentclass[border=5pt]{standalone}以獲得裁切後的輸出 - 包含所有必要的套件和 TikZ 庫
- 在前言中定義所有顏色
- 在前言中使用
\tikzset定義所有樣式 - 使用
positioning庫放置節點(例如,right=1.0cm of nodeA) - 保持間距一致:節點之間通常為 0.8–1.2 公分
- 確保所有文字都適合在其方塊內(必要時使用
\\進行換行) - 使用
\textbf作為模組標題,使用\footnotesize\color{textLight}作為副標題 - 為重要的資料流(特徵、潛在碼等)添加箭頭標籤
- 對符號使用數學模式:
$\mathbf{z}$,$\mathcal{L}$等
- 使用
-
將
.tex檔案 寫入工作目錄(例如,figure.tex或使用者指定的名稱)。
TikZ 階段 4:編譯與自我檢查
-
編譯 使用內建腳本:
bash .claude/skills/research-figure/scripts/compile_tikz.sh <path-to-tex-file> -
如果編譯失敗:讀取錯誤輸出,修正 LaTeX 代碼,然後重試。常見問題:
- 缺少套件 → 添加
\usepackage{...} - 未定義顏色 → 檢查
\definecolor定義 - 節點定位錯誤 → 檢查節點名稱和
of引用 - 數學模式錯誤 → 檢查
$...$匹配
- 缺少套件 → 添加
-
查看結果:使用讀取工具查看生成的 PNG 圖片。
-
根據以下清單自我檢查圖表:
- 所有文字都可讀(無重疊)
- 箭頭指向正確方向
- 水平和垂直對齊整潔
- 佈局緊湊(無大面積空白區域)
- 色彩方案一致且和諧
- 創新貢獻模組在視覺上被凸顯
- 模組名稱與使用者的協議一致
- 全程使用無襯線字體
-
如果發現問題:修正 TikZ 代碼並重新編譯。請勿向使用者展示有缺陷的圖表。
TikZ 階段 5:展示與迭代
- 向使用者展示編譯後的圖表(PNG 圖片)。
- 簡要說明結構。
- 詢問是否需要任何更改。
- 根據反饋,修改 TikZ 代碼,重新編譯,然後再次展示。
- 重複直到使用者滿意為止。
- 提供最終的
.tex檔案路徑,以便使用者可以:- 使用
\input{}直接包含在論文中 - 或者獨立編譯並透過
\includegraphics{}包含
- 使用
Blender 路徑
Blender 階段 1:理解視覺化需求
確定用例:
| 用例 | 描述 | 範本 |
|---|---|---|
| 預覽圖 | N 個角色沿 X 軸排列,漸層材質,地面 + 霧 + 軌跡 | templates/blender/template_teaser.py |
| 流程圖模組 | 單一網格,透明背景,用於包含在 TikZ 中 | templates/blender/template_single_render.py |
| 比較圖 | 2 個或更多角色,不同顏色(藍色=我們的,紅色=基線) | templates/blender/template_comparison.py |
| 骨架圖 | 3D 關鍵點球體 + 肢體圓柱體 | references/blender_recipes.md 中的配方 D |
| 邊界框 + 網格 | 網格周圍的線框邊界框 | references/blender_recipes.md 中的配方 E |
從使用者的請求中提取:
- 資料檔案路徑(FBX, OBJ, NPZ)
- 幀索引(要顯示哪些動畫幀)
- 角色 / 實例數量
- 樣式偏好(顏色、攝影機角度、是否包含地面)
Blender 階段 2:與使用者確認
展示結構化摘要:
圖表類型:多角色預覽圖
資料:motion.fbx,幀 [1, 30, 60, 90, 120, 150]
佈局:6 個角色沿 X 軸排列,間距 1.5m
攝影機:廣角,焦距 85mm
照明:工作室三點式照明
材質:漸層藍色黏土
地面:棋盤格帶反射
霧:是(藍灰色)
軌跡:是(漸層曲線帶箭頭)
輸出:2048x1024 JPEG
通常一輪就足夠。然後進行生成。
Blender 階段 3:生成 Blender 腳本
- 閱讀
references/blender_api.md了解函數簽名。 - 閱讀
references/blender_recipes.md了解相符的配方模式。 - 生成一個完整的 Python 腳本,該腳本從
blender_utils.*匯入(而不是從myblender.*匯入)。 - 腳本必須支援
--preview標誌,用於在快速預覽和最終渲染模式之間切換(見下文)。 - 將腳本寫入工作目錄(例如,
render_teaser.py)。
腳本必須是自包含的,並可透過以下方式執行:
bash .claude/skills/research-figure/scripts/render_blender.sh <script.py> -- [args]
兩階段渲染設計
每個生成的 Blender 腳本都必須支援由 --preview CLI 標誌控制的兩種渲染模式:
import argparse
def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("--preview", action="store_true",
help="Fast low-res Eevee preview")
# ... 其他參數 ...
if '--' in sys.argv:
args = parser.parse_args(sys.argv[sys.argv.index('--') + 1:])
else:
args = parser.parse_args([])
return args
在渲染部分,根據 args.preview 進行分支:
scene = bpy.context.scene
if args.preview:
# 快速預覽:Eevee,低解析度,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:
# 最終渲染:Cycles,全解析度
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()
預覽模式設定:
- 引擎:Eevee (
set_eevee_renderer) — 比 Cycles 快數個數量級 - 解析度:最終解析度的 1/2 到 1/4(例如,對於 2048x1024 的預覽圖使用 800x400)
- 格式:PNG(為了快速查看)
- 輸出路徑:在副檔名前添加
_preview後綴
最終模式設定:
- 引擎:Cycles (
set_cycles_renderer) — 光線追蹤,出版級品質 - 解析度:完整目標解析度
- 採樣數:256+ 以獲得最終品質
Blender 階段 4:預覽渲染與自我檢查
始終先進行快速預覽渲染。 不要直接進行 Cycles 渲染。
-
執行預覽渲染:
bash .claude/skills/research-figure/scripts/render_blender.sh <script.py> -- --preview -
如果渲染失敗:讀取錯誤輸出,修正 Python 腳本,然後重試。常見問題:
ModuleNotFoundError→ PYTHONPATH 問題(render_blender.sh 會自動處理)KeyError在節點輸入上 → Blender 版本相容性(使用 try/except)- 黑色/空白渲染 → 攝影機未設定,或物體不可見
- GPU 錯誤 → 在 set_cycles_renderer 中設定
prefer_gpu=False
-
查看預覽圖像:使用讀取工具查看生成的
*_preview.png。 -
自我檢查預覽:
- 物體可見且位置正確
- 攝影機角度清晰顯示主體
- 照明合理(Eevee 照明與 Cycles 略有不同,但構圖應正確)
- 材質已套用(不是預設的灰色)
- 背景乾淨整潔
- 角色間距和佈局看起來正確
-
如果發現問題:修正腳本並重新執行預覽。請勿向使用者展示有缺陷的圖表。
Blender 階段 5:展示預覽並獲得批准
- 向使用者展示預覽圖片。
- 說明這是用於檢查佈局/構圖的 快速 Eevee 預覽 — 最終的 Cycles 渲染將具有更好的照明、材質和抗鋸齒效果。
- 請使用者確認預覽看起來正確,然後再進行完整渲染。使用 AskUserQuestion 並提供類似選項:
- "看起來不錯,渲染最終版本" — 進入階段 6
- "調整攝影機 / 照明 / 間距" — 迭代修改腳本並重新渲染預覽
- "更改幀 / 角色" — 修改並重新渲染預覽
- 如果使用者請求更改,則修改腳本,重新執行預覽(非完整渲染),然後再次展示。
- 重複直到使用者批准預覽。
Blender 階段 6:最終渲染
僅在使用者批准預覽後才進行此步驟。
-
執行最終的 Cycles 渲染(不帶
--preview):bash .claude/skills/research-figure/scripts/render_blender.sh <script.py>注意:這將比預覽花費更長的時間。這是預期的。
-
查看結果:使用讀取工具查看最終渲染圖像。
-
向使用者展示最終圖片。
-
如果使用者想要進一步調整,請回到階段 5(預覽迭代),而不是每次調整都重新執行緩慢的 Cycles 渲染。
混合模式:TikZ + Blender 遞迴調用
當 TikZ 流程圖需要 3D 渲染的模組插圖時,請使用此模式。