Community影像github.com

pcb-render

將立創 EDA / 嘉立創 EDA(EasyEDA)專業版導出的 PCB 素材包渲染成照片級 3D 效果圖(Blender Cycles):STEP 3D + DXF 圖形層 → 每個元件獨立分色的 PBR 材質、藍色阻焊 + 金色焊盤 + 白色絲印 + 銅箔走線,輸出 2K/4K 主圖、俯視圖、微距。當用戶要求渲染 PCB / 電路板效果圖 / 板子 3D 圖,或從 EDA 導出包(.zip 包含 *.step + *.dxf)重新渲染不同角度/解析度,或添加微距/底部視圖時使用。

pcb-render 是什麼?

pcb-render 是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,能將立創 EDA(EasyEDA)專業版導出的素材包(包含 STEP 3D 模型與 DXF 圖形層)轉換為照片級 3D 渲染圖。它使用 Blender Cycles 引擎,為每個元件獨立分配 PBR 材質,並精確還原藍色阻焊層、金色焊盤、白色絲印及銅箔走線。此技能支援多種輸出解析度(preview / 2K / 4K),並提供預設的主視圖、俯視圖與微距構圖。 主要用途包括:一鍵渲染完整 PCB 效果圖、更換視角或解析度重新渲染、生成微距細節圖。其處理流程包含解包、STEP 轉 GLB、DXF 層處理(僅保留阻焊開窗與鑽孔)、幾何投影層生成、資產審計(檢查覆蓋率與連通性)、材質映射、渲染,以及最終的 8-bit / JPEG 轉換。內建嚴格的審計門與故障對照表,能避免常見的渲染錯誤(如銅層被填實、絲印偏移)。 支援平台為 Windows、macOS、Linux,依賴 Blender(建議 5.2+)、Python 及 cascadio / ezdxf / numpy / Pillow 等套件。所有設定透過環境探測腳本動態獲取,無需寫死路徑。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/maker114/PCB-Render-Kit/tree/HEAD/skill/pcb-render

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

pcb-render 是做什麼的?

把「立創 EDA 專業版一鍵導出的素材包」變成成品效果圖。整條鏈路的腳本都在 scripts/,本文件只做路由與紀律;細節按需讀 references/。

觸發條件

  • 使用者給了 EDA 導出的 zip(內含 *_3D.step、*_DXF.dxf、BOM、PickAndPlace),要出圖
  • 使用者說「再渲一版」「換個角度」「來張微距」「放大到 4K」「上次那塊板」
  • 使用者在聊 PCB 渲染、板子 3D、產品圖

鐵律(每一條都是踩坑換來的,違反必翻車)

  1. STEP 優先,禁止用 DXF 重繪已存在的層。 STEP 裡有 TopCopper / TopSilkscreen 等產品時,銅層和絲印必須從 STEP 幾何投影(layers_from_step.py)。 DXF 只補 STEP 沒有的層:阻焊開窗、鑽孔、板框。
    • 反例 1:用 DXF 重繪銅層 → 鋪銅的隔離帶被填成實心(覆蓋率 97%),走線全消失
    • 反例 2:用 DXF TEXT + 替代字體重繪絲印 → 字寬不一致,46 個字元偏移 0.30.5 mm
  2. 審計先行。 audit_assets.py 非 0 退出就停止,不許渲染。它查覆蓋率/連通塊,能抓住「實心填充」「空層」「單連通域」。
  3. 單 GPU 佇列。 禁止同時跑兩個 Blender OptiX 渲染(6 GB 顯存互搶,實測 85 s → 696 s)。
  4. 不許覆蓋。 驗證圖進 render/out/diag/,render/out/final/ 只寫一次;重渲前確認目標解析度。
  5. 交付前 1:1 抽查。 至少看 3 處 100% 裁切:焊盤、走線、絲印位號。縮圖不算驗收。
  6. 每換一塊板就補齊材質映射。 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。

跑完必做:

  1. 看圖(render/out/final/)→ 構圖/材質/走線是否正常
  2. 1:1 裁切抽查(Python 裁 3 處,逐張 Read 確認)
  3. 轉 8-bit:16 位母版留 *_16bit.png,主檔名給 8-bit,另存 q95 jpg
  4. 寫 README.md 到交付目錄:輸入包、板子型號、尺寸、每張圖的內容/尺寸、審計數字、復現命令
  5. 用 present 交付 3 張 + README

構圖與參數速查

板型主圖俯視微距
寬板(100×65)16:9 3840x2160豎/橫按板2560x1600
方板(36×36)1:1 2048x2048(2K)/ 3840x3840(4K)1:12400x1680
長條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.md5 次事故的數據、根因、檢測手段
新板子分色不對 / 要加封裝references/materials.md調色盤、FOOTPRINT_MAP 結構、補映射流程
調構圖、燈光、微距目標點references/lighting-camera.mdstudio 預設、aspect 決策、微距座標換算

安裝(DSH 到底從哪掃)

DSH 由 skill-filesystem 插件按以下根目錄發現 skill(rank 越小優先級越高):

範圍路徑rank
專案<專案根>/.dsh/skills100
專案<專案根>/.agents/skills200
自訂customSkillDirs 配置(cordis.patch.yml 裡 skill-filesystem 的 config)300
使用者%USERPROFILE%\.dsh\skills(Windows)/ ~/.dsh/skills(macOS、Linux)400
使用者~/.agents/skills500

一個 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),新工作階段必然可見。

相關技能