¿Qué hace pcb-render?
Convierte el «paquete de exportación de un solo clic de EasyEDA Profesional» en imágenes de producto terminadas. Todos los scripts de la cadena están en scripts/; este archivo solo se encarga del enrutamiento y la disciplina. Para detalles, consultar references/ según sea necesario.
Condiciones de disparo
- El usuario proporciona un zip exportado desde EDA (que contiene
*_3D.step,*_DXF.dxf, BOM, PickAndPlace) y solicita generar imágenes. - El usuario dice «renderiza otra versión», «cambia el ángulo», «haz un macro», «amplía a 4K», «la placa anterior».
- El usuario está hablando de renderizado de PCB, imagen 3D de la placa, o foto de producto.
Reglas de hierro (cada una se ha ganado con errores; incumplirlas garantiza el fracaso)
- Priorizar STEP, prohibido redibujar capas existentes con DXF.
Cuando STEP contiene productos como
TopCopper/TopSilkscreen, las capas de cobre y serigrafía deben proyectarse desde la geometría STEP (layers_from_step.py). DXF solo complementa las capas que STEP no tiene: apertura de máscara, taladros, contorno de placa.- Contraejemplo 1: Redibujar capa de cobre con DXF → las zonas de aislamiento del cobre se rellenan sólidas (cobertura 97 %), todas las trazas desaparecen.
- Contraejemplo 2: Redibujar serigrafía con DXF TEXT + fuente alternativa → el ancho de los caracteres es inconsistente, 4
6 caracteres se desplazan 0.30.5 mm.
- Auditar primero. Si
audit_assets.pysale con código distinto de 0, detenerse, no renderizar. Detecta cobertura/bloques conectados, atrapa «relleno sólido», «capa vacía», «dominio único conectado». - Cola de una sola GPU. Prohibido ejecutar dos renders Blender OptiX simultáneamente (6 GB de VRAM compiten, medido: 85 s → 696 s).
- No sobrescribir. Las imágenes de verificación van a
render/out/diag/;render/out/final/solo se escribe una vez; antes de re-renderizar, confirmar la resolución objetivo. - Revisión 1:1 antes de entregar. Examinar al menos 3 recortes al 100 %: pads, trazas, etiquetas de serigrafía. Las miniaturas no cuentan como aceptación.
- Cada vez que se cambie de placa, completar el mapeo de materiales.
recon_footprints.pyimprime el footprint + color, se añade aFOOTPRINT_MAPenmaterials.py.
Detección del entorno (hacer cada vez que se inicia)
No se hardcodea ninguna ruta en los scripts. scripts/env.py se encarga de la detección (primero ejecutar python scripts/env.py para ver el informe):
| Elemento | Cómo encontrarlo |
|---|---|
| Blender | Parámetro --blender → blender en config.json → variable de entorno PCB_RENDER_BLENDER → PATH → ubicaciones comunes de instalación (Program Files / Steam en Windows, /Applications en macOS, /usr/bin, snap, flatpak en Linux) |
| Python | El intérprete que ejecuta pipeline.py (sys.executable), así que iniciar con el Python que tenga las dependencias instaladas. |
| Dependencias | python -m pip install -r requirements.txt (cascadio / ezdxf / numpy / Pillow) |
Formas de sobrescribir cuando no se encuentra Blender (elegir una):
# A. Línea de comandos
python pipeline.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" ...
# B. Archivo de configuración (configurar una vez)
# Copiar config.example.json a config.json, rellenar "blender": "<ruta>"
# También soporta %APPDATA%/pcb-render/config.json o ~/.config/pcb-render/config.json
Si faltan dependencias, pipeline.py imprimirá directamente el comando de instalación con la ruta del intérprete, sin lanzar un traceback crudo.
Todas las invocaciones a Blender deben incluir --factory-startup. De lo contrario, se cargan las preferencias del usuario (interfaz en chino), los nodos nuevos se localizan como «fondo», y studio.py y otros que buscan nodos por nombre fallan. El studio.py de este repositorio ya se ha modificado para buscar nodos por tipo, pero se recomienda añadir este parámetro (también evita errores de plugins incompatibles).
Flujo principal
Un solo comando (recomendado, ~40 s para preview / 3–5 min para 2K):
& $py "<skill>\scripts\pipeline.py" `
--package "<paquete_material.zip>" `
--workdir "<directorio_trabajo>" `
--resolution preview # preview | 2k | 4k
# Opcional: --views hero,top,macro --samples 160 --skip-render
# --macro-target 0.010,-0.010,0.0016 --macro-distance 0.062
Ejecuta en orden: descomprimir → STEP→GLB → DXF solo para mask/drill (y escribe align.json) → STEP para copper/silk → Puerta de auditoría (si no pasa, sale directamente, no renderiza) → Imprimir lista de footprints → build_board → Renderizar 3 imágenes → Convertir a 8bit/jpg.
Comandos paso a paso y productos de cada paso en references/pipeline.md.
Después de ejecutar, obligatorio:
- Mirar las imágenes (
render/out/final/) → verificar composición / materiales / trazas. - Revisión 1:1 con recortes (Python recorta 3 zonas, leer una por una para confirmar).
- Convertir a 8-bit: el master de 16 bits se guarda como
*_16bit.png, el nombre principal se da a la versión de 8 bits, también guardar como jpg q95. - Escribir README.md en el directorio de entrega: paquete de entrada, modelo de placa, dimensiones, contenido/dimensiones de cada imagen, cifras de auditoría, comando de reproducción.
- Entregar 3 imágenes + README con
present.
Tabla rápida de composición y parámetros
| Tipo de placa | Hero | Top | Macro |
|---|---|---|---|
| Placa ancha (100×65) | 16:9 3840x2160 | Vertical/Horizontal según placa | 2560x1600 |
| Placa cuadrada (36×36) | 1:1 2048x2048 (2K) / 3840x3840 (4K) | 1:1 | 2400x1680 |
| Placa alargada | 4:5 o 16:9 | Vertical | — |
Cámaras/iluminación verificados (no es necesario reescanear cada vez):
- Hero 3/4:
--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(Obligatorio usar--distance: la distancia de encuadre de studio detail es 2~3 veces mayor) - Iluminación siempre
--light pcb_hero --floor black --exposure -0.8(top -0.2) - Muestras: 2K 128~160, 4K 200; denoising OIDN
Tabla de fallos
| Síntoma | Causa | Solución |
|---|---|---|
| Las trazas no se ven / la placa es azul sólido | La capa de cobre se redibujó con DXF y se rellenó sólida | Ejecutar layers_from_step.py para reproyectar desde STEP |
| Texto de serigrafía desplazado, cuanto más larga la etiqueta, más se desplaza | DXF redibujó la serigrafía con fuente alternativa | Igual que arriba, la serigrafía también debe usar STEP |
KeyError: 'Background'/'fondo' | No se usó --factory-startup, interfaz en chino localiza los nodos | Añadir --factory-startup |
| El macro sigue mostrando la placa completa | La distancia automática de studio detail es demasiado grande | Añadir --distance 0.05~0.07 |
| El renderizado se vuelve 5~10 veces más lento | Dos renders OptiX concurrentes | Serializar, ejecutar uno a la vez |
| Serigrafía de módulo al revés (arriba/abajo) | El componente está rotado 180° (así diseñado) | Verificar Rotation en PickAndPlace, no es un bug |
| Los agujeros pasantes/de montaje se ven como discos dorados | El disco dorado usó «apertura de máscara» y no «apertura ∧ cobre» | Ya implementado mask ∧ copper, verificar que el mapa de cobre no esté vacío |
| Los pads son un poco más grandes que las patillas del componente | Expansión de la máscara (mask expansion) | Normal, en la realidad la apertura de máscara es ligeramente mayor que el pad |
| El mapa de textura de la placa está completamente desplazado | align.json del contorno no coincide con UV | Confirmar que build_board.py lee el mismo align.json |
Archivos de referencia
| Cuándo leerlo | Archivo | Contenido |
|---|---|---|
| Para ejecutar paso a paso / no entender los productos de cada paso | references/pipeline.md | Comandos, estructura de directorios, entrada/salida de cada paso, significado de la auditoría |
| Cuando surja un problema y haya que cotejar causas y consecuencias | references/pitfalls.md | Datos de 5 incidentes, causa raíz, método de detección |
| Cuando los colores de una placa nueva no sean correctos / haya que añadir un footprint | references/materials.md | Paleta de colores, estructura de FOOTPRINT_MAP, flujo para añadir mapeo |
| Para ajustar composición, iluminación, punto objetivo del macro | references/lighting-camera.md | Preajustes de studio, decisión de aspecto, conversión de coordenadas macro |
Instalación (dónde escanea DSH)
DSH descubre los skills mediante el plugin skill-filesystem en los siguientes directorios raíz (menor rank = mayor prioridad):
| Ámbito | Ruta | Rank |
|---|---|---|
| Proyecto | <raíz_proyecto>/.dsh/skills | 100 |
| Proyecto | <raíz_proyecto>/.agents/skills | 200 |
| Personalizado | Directorios customSkillDirs (config de skill-filesystem en cordis.patch.yml) | 300 |
| Usuario | %USERPROFILE%\.dsh\skills (Windows) / ~/.dsh/skills (macOS, Linux) | 400 |
| Usuario | ~/.agents/skills | 500 |
Un skill = un directorio + SKILL.md. El frontmatter debe tener name (kebab-case, regex ^[a-z0-9]+(?:-[a-z0-9]+)*$) y description;
Los demás campos (compatibility / allowed-tools) se ignoran o se guardan en metadatos, no generan error.
Para evitar que el modelo lo active automáticamente, se puede añadir disable-model-invocation: true.
# Local: enlazar el repositorio como «unión de directorios» al directorio de skills de DSH — los cambios en el repositorio surten efecto inmediatamente, solo hay un contenido
cmd /c mklink /J "%USERPROFILE%\.dsh\skills\pcb-render" "<este_repo>\skill\pcb-render"
# Otras máquinas: copia normal
Copy-Item -Recurse -Force "<este_repo>\skill\pcb-render" "$env:USERPROFILE\.dsh\skills\pcb-render"
# O usar el script del repositorio (por defecto junction, -Copy para copia)
powershell -File "<este_repo>\scripts\install-skill.ps1"
Peligro: El directorio resources/runtime/office-skills/ bajo el directorio de instalación de DSH no es un directorio de escaneo general —
es el assetRoot propio del plugin office, y si se coloca allí no será descubierto (ya se probó, fue tiempo perdido).
Al modificar un skill, se recarga automáticamente (el provider tiene un watcher chokidar), y las nuevas sesiones lo verán siempre.