pcb-render 是做什麼的?
把「立創 EDA 專業版一鍵導出的素材包」變成成品效果圖。整條鏈路的腳本都在 scripts/,本文件只做路由與紀律;細節按需讀 references/。
觸發條件
- 使用者給了 EDA 導出的 zip(內含
*_3D.step、*_DXF.dxf、BOM、PickAndPlace),要出圖 - 使用者說「再渲一版」「換個角度」「來張微距」「放大到 4K」「上次那塊板」
- 使用者在聊 PCB 渲染、板子 3D、產品圖
鐵律(每一條都是踩坑換來的,違反必翻車)
- STEP 優先,禁止用 DXF 重繪已存在的層。
STEP 裡有
TopCopper/TopSilkscreen等產品時,銅層和絲印必須從 STEP 幾何投影(layers_from_step.py)。 DXF 只補 STEP 沒有的層:阻焊開窗、鑽孔、板框。- 反例 1:用 DXF 重繪銅層 → 鋪銅的隔離帶被填成實心(覆蓋率 97%),走線全消失
- 反例 2:用 DXF TEXT + 替代字體重繪絲印 → 字寬不一致,4
6 個字元偏移 0.30.5 mm
- 審計先行。
audit_assets.py非 0 退出就停止,不許渲染。它查覆蓋率/連通塊,能抓住「實心填充」「空層」「單連通域」。 - 單 GPU 佇列。 禁止同時跑兩個 Blender OptiX 渲染(6 GB 顯存互搶,實測 85 s → 696 s)。
- 不許覆蓋。 驗證圖進
render/out/diag/,render/out/final/只寫一次;重渲前確認目標解析度。 - 交付前 1:1 抽查。 至少看 3 處 100% 裁切:焊盤、走線、絲印位號。縮圖不算驗收。
- 每換一塊板就補齊材質映射。
recon_footprints.py列印封裝 + 顏色,補進materials.py的FOOTPRINT_MAP。
環境探測(每次開工先做)
腳本裡不寫死任何路徑,scripts/env.py 負責探測(先跑 python scripts/env.py 看報告):
| 項 | 怎麼找 |
|---|---|
| Blender | --blender 參數 → config.json 的 blender → 環境變數 PCB_RENDER_BLENDER → PATH → 各系統常見安裝位置(Windows 的 Program Files / Steam 庫、macOS 的 /Applications、Linux 的 /usr/bin、snap、flatpak) |
| Python | 跑 pipeline.py 的那個直譯器(sys.executable),所以用你自己裝了依賴的 Python 啟動即可 |
| 依賴 | python -m pip install -r requirements.txt(cascadio / ezdxf / numpy / Pillow) |
找不到 Blender 時的覆蓋方式,二選一:
# A. 命令列
python pipeline.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" ...
# B. 設定檔(一次配好)
# 把 config.example.json 複製成 config.json,填 "blender": "<路徑>"
# 也支援 %APPDATA%/pcb-render/config.json 或 ~/.config/pcb-render/config.json
缺依賴時 pipeline.py 會直接列印帶直譯器路徑的安裝命令,不會甩裸 traceback。
所有 Blender 呼叫都要帶 --factory-startup。 否則會載入使用者偏好(中文介面),新建節點被本地化成「背景」,studio.py 之類按名字取節點的地方會炸。本倉庫的 studio.py 已改成按類型取節點,但仍建議加該參數(還能避開不相容插件的報錯)。
主流程
一條命令跑完(推薦,約 40 s 出 preview / 3–5 min 出 2K):
& $py "<skill>\scripts\pipeline.py" `
--package "<素材包.zip>" `
--workdir "<工作目錄>" `
--resolution preview # preview | 2k | 4k
# 可選:--views hero,top,macro --samples 160 --skip-render
# --macro-target 0.010,-0.010,0.0016 --macro-distance 0.062
它依次做:解包 → STEP→GLB → DXF 只出 mask/drill(並寫出 align.json)→ STEP 出 copper/silk →
審計門(不通關直接退出,不渲染) → 列印封裝清單 → build_board → 渲染 3 張 → 轉 8bit/jpg。
分步命令與每步產物見 references/pipeline.md。
跑完必做:
- 看圖(
render/out/final/)→ 構圖/材質/走線是否正常 - 1:1 裁切抽查(Python 裁 3 處,逐張 Read 確認)
- 轉 8-bit:16 位母版留
*_16bit.png,主檔名給 8-bit,另存 q95 jpg - 寫 README.md 到交付目錄:輸入包、板子型號、尺寸、每張圖的內容/尺寸、審計數字、復現命令
- 用
present交付 3 張 + README
構圖與參數速查
| 板型 | 主圖 | 俯視 | 微距 |
|---|---|---|---|
| 寬板(100×65) | 16:9 3840x2160 | 豎/橫按板 | 2560x1600 |
| 方板(36×36) | 1:1 2048x2048(2K)/ 3840x3840(4K) | 1:1 | 2400x1680 |
| 長條 | 4:5 或 16:9 | 豎構圖 | — |
已驗證的相機/燈光(不要每次重掃):
- 3/4 主圖:
--framing three_quarter --azimuth -32 --elevation 38 --margin 0.0~0.02 - 俯視:
--framing top --azimuth 0 --elevation 84 --margin 0.05 --exposure -0.2 - 微距:
--framing three_quarter --target X,Y,0.0016 --lens 100 --distance 0.05~0.07(必須用--distance:studio 的 detail 取景距離偏大 2~3 倍) - 燈光一律
--light pcb_hero --floor black --exposure -0.8(俯視 -0.2) - 取樣:2K 128~160、4K 200;降噪 OIDN
故障對照表
| 症狀 | 原因 | 處理 |
|---|---|---|
| 走線看不見 / 板子一片純藍 | 銅層用 DXF 重繪被填實 | 跑 layers_from_step.py 重新用 STEP 投影 |
| 絲印文字偏移、越長的標籤偏得越多 | DXF 用替代字體重繪 | 同上,絲印也改用 STEP |
KeyError: 'Background'/'背景' | 沒加 --factory-startup,中文介面節點本地化 | 加 --factory-startup |
| 微距出來還是整板 | studio detail 自動距離偏大 | 加 --distance 0.05~0.07 |
| 渲染突然變慢 5~10 倍 | 兩個 OptiX 渲染並發 | 串行,一次只跑一個 |
| 模組絲印上下顛倒 | 器件旋轉 180°(設計如此) | 核對 PickAndPlace 的 Rotation,不是 bug |
| 通孔/安裝孔變成金圓盤 | 金盤用「開窗」而不是「開窗∧銅」 | 已實現 mask ∧ copper,檢查銅層貼圖是否為空 |
| 焊盤比器件引腳大一圈 | 蒙版擴張(mask expansion) | 正常現象,實物也是開窗略大於焊盤 |
| 板子貼圖整體錯位 | align.json 的板框與 UV 不一致 | 確認 build_board.py 讀的是同一份 align.json |
參考文件
| 什麼時候讀 | 檔案 | 內容 |
|---|---|---|
| 要分步執行 / 搞不清每步產物 | references/pipeline.md | 命令、目錄結構、每步輸入輸出、審計含義 |
| 出問題要對照前因後果 | references/pitfalls.md | 5 次事故的數據、根因、檢測手段 |
| 新板子分色不對 / 要加封裝 | references/materials.md | 調色盤、FOOTPRINT_MAP 結構、補映射流程 |
| 調構圖、燈光、微距目標點 | references/lighting-camera.md | studio 預設、aspect 決策、微距座標換算 |
安裝(DSH 到底從哪掃)
DSH 由 skill-filesystem 插件按以下根目錄發現 skill(rank 越小優先級越高):
| 範圍 | 路徑 | rank |
|---|---|---|
| 專案 | <專案根>/.dsh/skills | 100 |
| 專案 | <專案根>/.agents/skills | 200 |
| 自訂 | customSkillDirs 配置(cordis.patch.yml 裡 skill-filesystem 的 config) | 300 |
| 使用者 | %USERPROFILE%\.dsh\skills(Windows)/ ~/.dsh/skills(macOS、Linux) | 400 |
| 使用者 | ~/.agents/skills | 500 |
一個 skill = 一個目錄 + SKILL.md。frontmatter 必須有 name(kebab-case,正則 ^[a-z0-9]+(?:-[a-z0-9]+)*$)和 description;
其餘欄位(compatibility / allowed-tools)會被忽略或收進 metadata,不會報錯。
想禁止模型自動觸發可加 disable-model-invocation: true。
# 本機:倉庫透過「目錄聯接」掛到 DSH 技能目錄 —— 改倉庫立即生效,只有一份內容
cmd /c mklink /J "%USERPROFILE%\.dsh\skills\pcb-render" "<本倉庫>\skill\pcb-render"
# 其他機器:普通複製即可
Copy-Item -Recurse -Force "<本倉庫>\skill\pcb-render" "$env:USERPROFILE\.dsh\skills\pcb-render"
# 或直接用倉庫腳本(預設 junction,-Copy 走複製)
powershell -File "<本倉庫>\scripts\install-skill.ps1"
坑:DSH 安裝目錄下的 resources/runtime/office-skills/ 不是通用掃描目錄 ——
它是 office 插件自己的 assetRoot,塞進去不會被發現(踩過,白折騰一輪)。
改完 skill 會自動熱載入(provider 帶 chokidar watcher),新工作階段必然可見。