What does pcb-render do?
Turn a material package exported from LCEDA (EasyEDA) Professional Edition into a finished product shot. All pipeline scripts are in scripts/; this file handles routing and discipline only. See references/ for details as needed.
Trigger Conditions
- User provides an EDA-exported zip (containing
*_3D.step,*_DXF.dxf, BOM, PickAndPlace) and asks for a render. - User says "render another version," "change the angle," "take a macro shot," "zoom to 4K," or "that board from last time."
- User is discussing PCB rendering, board 3D, or product shots.
Ironclad Rules (Each one comes from hard lessons – violating them will cause failures)
- STEP first – never use DXF to redraw existing layers.
When STEP contains
TopCopper/TopSilkscreenetc., copper and silkscreen must be projected from STEP geometry (vialayers_from_step.py). DXF is for layers missing in STEP only: solder mask openings, drill holes, board outline.- Anti-example 1: Using DXF to redraw copper → copper pour keepouts become solid-filled (97% coverage), traces vanish.
- Anti-example 2: Using DXF TEXT + substitute font to redraw silkscreen → inconsistent character width, 4–6 characters offset by 0.3–0.5 mm.
- Audit first. If
audit_assets.pyexits with non-zero code, stop – do not render. It checks coverage and connected components, catching "solid fill," "empty layer," "single connected domain." - Single GPU queue. Never run two Blender OptiX renders simultaneously (6 GB VRAM contention, measured 85 s → 696 s).
- No overwriting. Validation images go into
render/out/diag/;render/out/final/is written only once; confirm target resolution before re-rendering. - 1:1 spot check before delivery. Inspect at least three areas at 100% crop: pads, traces, silkscreen reference designators. Thumbnails don't count as acceptance.
- Update material mapping for each new board. Run
recon_footprints.pyto print footprints and colors, then add toFOOTPRINT_MAPinmaterials.py.
Environment Detection (Perform at the start of each session)
No hardcoded paths in scripts – scripts/env.py handles detection (run python scripts/env.py first to see the report):
| Item | How to Find |
|---|---|
| Blender | --blender argument → config.json's blender → environment variable PCB_RENDER_BLENDER → PATH → common install locations (Windows: Program Files / Steam library, macOS: /Applications, Linux: /usr/bin, snap, flatpak) |
| Python | The interpreter running pipeline.py (sys.executable), so just start with your Python that has dependencies installed |
| Dependencies | python -m pip install -r requirements.txt (cascadio / ezdxf / numpy / Pillow) |
Override methods when Blender is not found – choose one:
# A. Command line
python pipeline.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" ...
# B. Config file (set once)
# Copy config.example.json to config.json, fill in "blender": "<path>"
# Also supports %APPDATA%/pcb-render/config.json or ~/.config/pcb-render/config.json
When dependencies are missing, pipeline.py prints an install command with the interpreter path – never a bare traceback.
All Blender invocations must include --factory-startup. Otherwise, user preferences (e.g., Chinese UI) are loaded, new nodes are localized to names like "Background" in Chinese, and scripts like studio.py that fetch nodes by name will break. This repo's studio.py has been updated to fetch nodes by type, but the argument is still recommended (also avoids plugin incompatibility errors).
Main Pipeline
Single command (recommended – about 40 s for preview, 3–5 min for 2K):
& $py "<skill>\scripts\pipeline.py" `
--package "<material-package.zip>" `
--workdir "<working-directory>" `
--resolution preview # preview | 2k | 4k
# Optional: --views hero,top,macro --samples 160 --skip-render
# --macro-target 0.010,-0.010,0.0016 --macro-distance 0.062
It sequentially: unpacks → STEP→GLB → DXF exports only mask/drill (and writes align.json) → STEP exports copper/silk →
Audit gate (exits without rendering if failed) → prints footprint list → build_board → renders 3 views → converts to 8-bit/jpg.
For step-by-step commands and artifacts, see references/pipeline.md.
After completion, do:
- Review images (
render/out/final/) – check composition, materials, traces. - 1:1 crop spot check (Python crop 3 areas, read each to confirm).
- Convert to 8-bit: Keep 16-bit master as
*_16bit.png, main filename as 8-bit, also save q95 jpg. - Write README.md to delivery directory: input package, board model, dimensions, content/size of each image, audit numbers, reproduction command.
- Deliver 3 images + README using
present.
Composition & Parameters Quick Reference
| Board Type | Hero | Top | Macro |
|---|---|---|---|
| Wide board (100×65) | 16:9 3840x2160 | Portrait/landscape based on board | 2560x1600 |
| Square board (36×36) | 1:1 2048x2048 (2K) / 3840x3840 (4K) | 1:1 | 2400x1680 |
| Long strip | 4:5 or 16:9 | Portrait | — |
Verified cameras/lighting (no need to re-scan each time):
- 3/4 hero:
--framing three_quarter --azimuth -32 --elevation 38 --margin 0.0~0.02 - Top:
--framing top --azimuth 0 --elevation 84 --margin 0.05 --exposure -0.2 - Macro:
--framing three_quarter --target X,Y,0.0016 --lens 100 --distance 0.05~0.07(Must use--distance: studio detail framing distance is 2–3× too large) - Lighting always:
--light pcb_hero --floor black --exposure -0.8(top: -0.2) - Samples: 2K 128–160, 4K 200; denoiser OIDN
Troubleshooting Table
| Symptom | Cause | Fix |
|---|---|---|
| Traces invisible / board solid blue | Copper layer redrawn with DXF, filled solid | Run layers_from_step.py to re-project from STEP |
| Silkscreen text offset, longer labels offset more | DXF redraws silkscreen with substitute font | Same as above, switch silkscreen to STEP |
KeyError: 'Background'/'背景' | Missing --factory-startup, Chinese UI localized node names | Add --factory-startup |
| Macro shot still shows full board | Studio detail auto-distance too large | Add --distance 0.05~0.07 |
| Rendering suddenly 5–10× slower | Two OptiX renders running concurrently | Serialize, run one at a time |
| Module silkscreen upside down | Component rotated 180° (by design) | Check PickAndPlace Rotation, not a bug |
| Through-hole/mounting holes become gold discs | Gold pads use "mask opening" instead of "mask opening ∧ copper" | Implemented mask ∧ copper – check copper texture is not empty |
| Pads larger than component pins by one size | Mask expansion | Normal – real openings are slightly larger than pads |
| Board texture misaligned overall | align.json board outline inconsistent with UV | Confirm build_board.py reads the same align.json |
Reference Files
| When to Read | File | Content |
|---|---|---|
| Want to run step-by-step / unclear about artifacts | references/pipeline.md | Commands, directory structure, input/output per step, audit meanings |
| Troubleshooting with context | references/pitfalls.md | Data, root causes, detection methods for 5 real incidents |
| New board colors wrong / need to add footprint | references/materials.md | Color palette, FOOTPRINT_MAP structure, mapping update flow |
| Adjusting composition, lighting, macro target | references/lighting-camera.md | Studio presets, aspect ratio decisions, macro coordinate conversion |
Installation (Where DSH Scans From)
DSH discovers skills via the skill-filesystem plugin from the following root directories (lower rank = higher priority):
| Scope | Path | Rank |
|---|---|---|
| Project | <project-root>/.dsh/skills | 100 |
| Project | <project-root>/.agents/skills | 200 |
| Custom | customSkillDirs config (in cordis.patch.yml under skill-filesystem) | 300 |
| User | %USERPROFILE%\.dsh\skills (Windows) / ~/.dsh/skills (macOS, Linux) | 400 |
| User | ~/.agents/skills | 500 |
A skill = a directory + SKILL.md. Frontmatter must have name (kebab-case, regex ^[a-z0-9]+(?:-[a-z0-9]+)*$) and description;
other fields (compatibility / allowed-tools) are ignored or stored as metadata without errors.
To prevent automatic model invocation, add disable-model-invocation: true.
# Local: Mount repo as directory junction to DSH skill directory – changes take effect immediately, single copy of content
cmd /c mklink /J "%USERPROFILE%\.dsh\skills\pcb-render" "<this-repo>\skill\pcb-render"
# Other machines: Simple copy
Copy-Item -Recurse -Force "<this-repo>\skill\pcb-render" "$env:USERPROFILE\.dsh\skills\pcb-render"
# Or use the repo script (default junction, -Copy for copy)
powershell -File "<this-repo>\scripts\install-skill.ps1"
Gotcha: The DSH installation directory resources/runtime/office-skills/ is not a general scan directory –
it is the office plugin's own assetRoot; placing skills there will not be discovered (learned the hard way, wasted effort).
Skills are hot-reloaded automatically (provider has chokidar watcher) and will be visible in new sessions.