CAD 工作室渲染

將 CAD 組裝檔轉換成產品頁面所需的元素：寫實的產品照片、透明去背圖、旋轉展示影片，以及一個可自託管的 3D 檢視器（含手機 AR）。整個流程只需一個指令，且全在本機執行。GPU 負責渲染；不涉及 AI 圖像生成，因此像素即為真實幾何。

python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --name "產品名稱"

${CLAUDE_SKILL_DIR} 是此技能所在的資料夾（Claude Code 會自動填入）。在其他代理中，請使用此 SKILL.md 所在的資料夾。以下所有腳本路徑皆相對於該資料夾。

使用時機

「渲染這個 STEP 檔案」、「從 CAD 製作產品照片/產品精修圖」、「寫實渲染這個零件」
「將此 3D 模型放到我們的網站上」、「讓它可以旋轉」、「產品的 AR 檢視」
「產品的透明 PNG」、「目錄用的去背圖」、「旋轉展示影片」
3D 藝術家想要一個可編輯的 Blender 場景以便手動完成細節

不屬於此技能：從頭開始建模（請使用 CAD 工具）、從文字提示生成圖像，或渲染非產品的場景（例如室內、角色）。

安裝此技能

Claude Code，終端機： claude plugin install cad-studio-renders --marketplace abchiaravalle/cad-studio-renders
Claude Code，桌面應用程式： 請 Claude 將 https://github.com/abchiaravalle/cad-studio-renders 複製到 ~/.claude/skills/cad-studio-renders（桌面應用程式和終端機都會讀取該資料夾）。
任何其他代理： 將此資料夾放置於該代理載入 SKILL.md 資料夾的路徑中。

需求（請先檢查）

blender --version       # 4.2 或更新版本。若缺少：https://www.blender.org/download/
uv --version            # 讀取 CAD 檔案。若缺少：https://docs.astral.sh/uv/
ffmpeg -version         # 僅在需要 --turntable 影片時需要

如果 Blender 已安裝但不在 PATH 中，請設定 BLENDER=/path/to/blender。GPU（Apple Silicon、NVIDIA、AMD）可將渲染速度提升 5-20 倍；CPU 也可執行，但較慢。首次執行會下載 CAD 函式庫（約 60 MB）和一個工作室 HDRI（24 MB，CC0 授權）到 ~/.cache/cad-studio-renders/。

工作流程

在渲染任何東西之前，先對應材質。 CAD 檔案很少帶有真實的表面處理。
```
python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --map-only
```
閱讀表格。每個零件都會顯示其預設和原因。結尾帶有 （需審閱） 的行是推測值。使用規則檔案（下一節）修正錯誤的項目，並重新執行 --map-only 直到正確為止。
預覽（約 10 秒）：--preview 會渲染一張 1000 像素的草稿。在耗費數分鐘渲染最終版本之前先檢視它。檢查：方向正確、零件組裝到位（無漂浮物）、構圖、材質。
最終渲染：移除 --preview。預設會產生一張在背景上的 2400 像素主視覺圖、同一張圖的透明 PNG、一個可編輯的 .blend 檔案，以及網頁嵌入套件。
檢查輸出：在原始尺寸下（放大到最繁忙的區域）檢查，然後再交付。

修正材質：規則檔案

{"rules": [
  {"match": "frame|base",    "preset": "powder_coat",  "color": "#2b2f33"},
  {"match": "^Cover",        "preset": "plastic_textured"},
  {"match": "motor",         "preset": "motor_housing"},
  {"match": "logo plate",    "preset": "anodised_color", "color": "#c8102e"},
  {"match": "spindle",       "preset": "steel_polished", "params": {"roughness": 0.05}},
  {"match": "safety guard",  "hide": true},
  {"match": "gantry",        "offset_mm": [0, 0, 80]}
]}

match 是一個不區分大小寫的正規表示式，會對零件名稱、實例名稱和組裝路徑進行測試。第一個符合的規則優先。params 會覆寫任何預設值（粗糙度、金屬感、塗層、各向異性、倒角、凹凸...）。offset_mm 設定該零件在爆炸視圖中的位置。預設值位於 assets/presets/materials.json；您可以在該處新增規則。

如果沒有規則，自動對應器將依序使用：零件名稱關鍵字（緊固件、軸承、線性滑軌、滾珠螺桿、馬達、橡膠、玻璃...），然後是 CAD 顏色（高飽和度顏色變為油漆，共享同一顏色的零件共享同一種表面處理），最後是尺寸。

重要的選項

標誌	功能
`--shots hero,front,side,top,iso,back,square,hero_low,detail`	選擇攝影機角度（`assets/presets/shots.json`）
`--lighting studio_soft / high_key / dramatic / hdri_only`	燈光配置（`assets/presets/lighting.json`）
`--backdrop 0.42` 或 `--backdrop "#1d1f22"`	背景灰色或顏色
`--size 4000 --aspect 16:9`	輸出尺寸和比例
`--samples 768`	更多樣本 = 更清晰的反射細節，更長的渲染時間
`--exposure 0.3`, `--light-scale 1.2`, `--env-scale 0.8`	亮度
`--hdri photo_studio_01` 或 `--hdri my.exr`, `--hdri-rotation 40`	反射環境
`--dof 0` / `--dof 2`	關閉背景模糊 / 減少模糊
`--bevel-scale 0`	關閉邊緣圓角（圓角是讓 CAD 看起來真實的關鍵）
`--detail-target "spindle	chuck"`搭配`--shots detail`
`--no-transparent`, `--no-backdrop`, `--no-embed`, `--no-blend`	跳過特定輸出項目
`--clay`	灰色黏土渲染（用於檢查光線/形狀、設計審查）
`--passes`	多圖層 EXR：深度、法線、環境光遮蔽、霧氣、Cryptomatte（物件 + 材質 ID）
`--exploded 0.4`	爆炸視圖（零件從中心向外推；`offset_mm` 規則會覆寫）
`--turntable [--turntable-transparent]`	360° MP4 + WebM（可選 Alpha）+ PNG 幀
`--up y`	如果自動方向偵測錯誤，則強制指定 Y 軸為向上方向

輸出內容

<model>_studio/
  hero.png                    16 位元，放在工作室背景上
  hero_transparent.png        16 位元 RGBA，保留柔和的接觸陰影（使用 --shadow none 可移除）
  hero_clay.png, hero_exploded.png, hero_passes.exr       （若指定）
  <slug>_turntable.mp4 / .webm, turntable_frames/          （若指定）
  <slug>_scene.blend          燈光、攝影機、材質、背景、紋理均已嵌入
  materials_map.json          每個零件 -> 預設 + 原因（可透過 --rules 編輯並重新執行）
  manifest.json               設定、時間戳記、檔案列表（含大小與雜湊值）
  embed/                      可自託管的 3D 檢視器套件（見下文）

.blend 是為了手動完成而設計的。 集合：Product（每個零件一個空的容器，因此零件可以單獨移動或設置動畫）和 Studio（背景、燈光、攝影機）。每個攝影機都綁定到時間軸標記，因此拖動時間軸即可切換視角。材質是普通的 Principled BSDF 節點樹。邊緣圓角使用 Bevel Shader 節點，因此幾何形狀保持精確。

嵌入套件

embed/ 是完全靜態的，不會發出任何外部請求。它內建了 Google <model-viewer>（Apache-2.0 授權）和 Draco 解碼器。將資料夾上傳到任何地方，然後貼上 snippet.html，或使用 iframe 嵌入 embed.html。它包含：

assets/<slug>.glb：經 Draco 壓縮，材質與渲染圖相符
assets/<slug>.usdz：iPhone/iPad 透過 Quick Look 進行 AR 檢視
一張預覽圖片
用於反射的工作室 HDRI
index.html：一個示範頁面，包含複製按鈕和下載渲染圖的功能

WordPress、Shopify、Webflow 等平台的託管注意事項請見 embed/README.md。

常見陷阱（每個都在開發過程中被遇到過）

模型側躺或倒置。 SolidWorks、Inventor、Creo 和 Fusion 預設為 Y 軸向上；其他大部分是 Z 軸向上。轉換器會讀取 STEP 標頭來猜測，並列印出猜測結果（up axis: Y (written by Solidworks)）。如果猜錯，請傳遞 --up z（或 y、-y、x...）。
零件散開 /「意外爆炸」。 原因是組裝變換被應用了兩次。場景建構器現在會檢查分組零件是否會移動幾何形狀，如果會則中止。如果您編輯場景程式碼，請保留此檢查。
金屬看起來平坦、假假的。 通常是光線問題，而非材質問題：沒有環境意味著金屬沒有東西可以反射。即使在有區域燈光的情況下也要保持 HDRI 開啟（--env-scale，不要設為 0）。
首次渲染顏色暗淡。 燈光強度是根據模型尺寸縮放的；如果您在 lighting.json 中加入自訂燈光，強度是以（模型半徑，單位公尺）² 為單位計算。從低強度開始，並使用 --preview。
材質猜測錯誤。 難以理解的零件名稱（P-0042、ASSY_7_REV2、音譯的非英文名稱）會使關鍵字匹配失敗，並回退到使用顏色/尺寸。這就是 （需審閱） 標記的作用。為這些零件編寫規則。
OCP 8 破壞了讀取器（TDF_LabelSequence 已移動）。CAD 讀取器固定使用 cadquery-ocp-novtk<8。未經重新測試請勿解除固定。
網頁模型看起來與渲染圖不同。 glTF 無法承載程式化產生的凹凸、倒角或粗糙度噪點，因此網頁模型只會獲得基礎值。這是預期的行為；預覽圖片是真實的渲染圖。
超大型組裝（超過 500 萬個三角形）：預覽時使用 --quality web；最終渲染仍可運作，但需要 RAM（Blender 中每 200 萬個三角形約需 1 GB）。

交付前的驗證

以 100% 比例開啟主視覺 PNG，並檢查最密集的區域：無黑色面、曲線無塊狀、無閃爍亮點（白色斑點）。
在深色和淺色背景上開啟透明 PNG：邊緣乾淨，陰影僅位於產品下方。
在本機提供 embed/ 服務（python3 -m http.server -d embed 8000），開啟並確認模型載入、可以旋轉且無控制台錯誤。如果 AR 功能重要，請在手機上檢查。
如果 materials_map.json 中仍有 （需審閱） 行，請在交接時說明。

檔案

scripts/studio.py：入口點（上述 CLI）
scripts/cad_to_glb.py：將 STEP/IGES/BREP 轉換為帶有組裝名稱和 CAD 顏色的 glTF（uv 腳本）
scripts/automap.py：零件到材質的決策（純 Python，可獨立執行）
scripts/blender_studio.py：場景、材質、燈光、攝影機、渲染、.blend、網頁匯出
scripts/package_embed.py：可自託管檢視器套件
assets/presets/*.json：材質、燈光配置、攝影機視角
examples/make_demo_model.py：建立示範用的檯虎鉗（原始幾何，CC0 授權）

CAD 棚拍靜幀