abchiaravalle/cad-studio-renders

Renders de estudio CAD

Convierte un ensamblaje CAD en lo que necesita una página de producto: tomas fotorrealistas de estudio, recortes con fondo transparente, un video de giradiscos y un visor 3D autoalojado con realidad aumentada para el móvil. Todo el proceso es un solo comando y se ejecuta localmente. La GPU realiza el renderizado; no se utiliza generación de imágenes por IA, por lo que los píxeles representan la geometría real.

python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --name "Nombre del Producto"

${CLAUDE_SKILL_DIR} es la carpeta de este skill (Claude Code la completa automáticamente). En otros agentes, usa la carpeta donde se encuentra este SKILL.md. Todas las rutas de scripts a continuación son relativas a esa carpeta.

Cuándo usarlo

• "Renderiza este archivo STEP", "haz fotos de producto / packshots a partir de CAD", "render fotorrealista de esta pieza"
• "Pon un modelo 3D de esto en nuestro sitio web", "hazlo giratorio", "vista AR del producto"
• "PNG transparente del producto", "recorte para el catálogo", "video de giradiscos"
• Un artista 3D quiere una escena editable de Blender para terminarla a mano

No es este skill: modelar una pieza desde cero (usa una herramienta CAD), generar imágenes a partir de una descripción de texto o renderizar una escena que no sea un producto (interiores, personajes).

Instalación de este skill

• Claude Code, terminal: claude plugin install cad-studio-renders --marketplace abchiaravalle/cad-studio-renders
• Claude Code, aplicación de escritorio: pídele a Claude que clone https://github.com/abchiaravalle/cad-studio-renders en ~/.claude/skills/cad-studio-renders (tanto la aplicación de escritorio como el terminal leen esa carpeta).
• Cualquier otro agente: coloca esta carpeta en el lugar donde ese agente cargue las carpetas de SKILL.md.

Requisitos (verificar primero)

blender --version       # 4.2 o superior. Si falta: https://www.blender.org/download/
uv --version            # lee el archivo CAD. Si falta: https://docs.astral.sh/uv/
ffmpeg -version         # solo necesario para videos --turntable

Si Blender está instalado pero no en el PATH, establece BLENDER=/ruta/a/blender. Una GPU (Apple Silicon, NVIDIA, AMD) acelera los renders entre 5 y 20 veces; la CPU funciona, pero es más lenta. La primera ejecución descarga una biblioteca CAD (~60 MB) y un HDRI de estudio (24 MB, CC0) en ~/.cache/cad-studio-renders/.

Flujo de trabajo

1. Mapea los materiales antes de renderizar nada. Los archivos CAD rara vez tienen acabados reales.

   python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --map-only
   

   Lee la tabla. Cada pieza muestra su preajuste y la razón. Las líneas que terminan en (revísame) son conjeturas. Corrige las incorrectas con un archivo de reglas (siguiente sección) y vuelve a ejecutar --map-only hasta que esté correcto.
2. Vista previa (aproximadamente 10 s): --preview renderiza un borrador de 1000 px. Míralo antes de dedicar minutos a los finales. Verifica: orientación correcta, piezas ensambladas (nada flotando), encuadre, materiales.
3. Final: elimina --preview. Los valores predeterminados generan una imagen principal de 2400 px sobre un fondo de estudio, la misma imagen como PNG transparente, un archivo .blend editable y el paquete de visor web.
4. Revisa la salida a tamaño completo (amplía la región más densa) antes de entregarla.

Corrección de materiales: el archivo de reglas

{"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 es una expresión regular que no distingue mayúsculas de minúsculas y se prueba contra el nombre de la pieza, el nombre de la instancia y la ruta del ensamblaje. Gana la primera regla que coincida. params anula cualquier valor preestablecido (roughness, metallic, coat, anisotropic, bevel, bump...). offset_mm establece la posición de esa pieza en la vista explotada. Los preajustes están en assets/presets/materials.json; puedes añadir nuevos allí.

Sin reglas, el mapeador automático usa, en este orden: palabras clave del nombre de la pieza (sujetadores, rodamientos, guías lineales, husillos de bolas, motores, caucho, vidrio...), luego el color del CAD (los colores saturados se convierten en pintura, las piezas que comparten un color comparten un acabado) y luego el tamaño.

Opciones importantes

Indicador	Qué hace
--shots hero,front,side,top,iso,back,square,hero_low,detail	Qué ángulos de cámara (assets/presets/shots.json)
--lighting studio_soft / high_key / dramatic / hdri_only	Configuración de iluminación (assets/presets/lighting.json)
--backdrop 0.42 o --backdrop "#1d1f22"	Fondo gris o color
--size 4000 --aspect 16:9	Tamaño y relación de aspecto de la salida
--samples 768	Más muestras = detalles brillantes más limpios, renderizado más largo
--exposure 0.3, --light-scale 1.2, --env-scale 0.8	Brillo
--hdri photo_studio_01 o --hdri mi.exr, --hdri-rotation 40	Entorno de reflexión
--dof 0 / --dof 2	Desenfoque de fondo desactivado / menos desenfoque
--bevel-scale 0	Desactivar el redondeo de bordes (el redondeo es lo que hace que el CAD parezca real)
`--detail-target "spindle	chuck"con--shots detail`
--no-transparent, --no-backdrop, --no-embed, --no-blend	Omitir entregables
--clay	Pase de arcilla gris (verificación de iluminación/forma, revisiones de diseño)
--passes	EXR multicapa: profundidad, normales, AO, niebla, cryptomatte (IDs de objeto + material)
--exploded 0.4	Vista explotada (piezas desplazadas desde el centro; las reglas offset_mm anulan)
--turntable [--turntable-transparent]	MP4 + WebM de 360° (alfa opcional) + fotogramas PNG
--up y	Forzar el eje vertical si la detección automática se equivoca

Qué obtienes

<modelo>_studio/
  hero.png                    16 bits, sobre el fondo de estudio
  hero_transparent.png        16 bits RGBA, sombra de contacto suave conservada (--shadow none para eliminarla)
  hero_clay.png, hero_exploded.png, hero_passes.exr       (cuando se solicite)
  <slug>_turntable.mp4 / .webm, turntable_frames/          (cuando se solicite)
  <slug>_scene.blend          luces, cámaras, materiales, fondo, texturas empaquetadas
  materials_map.json          cada pieza -> preajuste + razón (editar y volver a ejecutar con --rules)
  manifest.json               configuración, tiempos, lista de archivos con tamaños y hashes
  embed/                      paquete de visor 3D autoalojado (ver más abajo)

El archivo .blend está diseñado para finalizarlo a mano. Colecciones: Product (un vacío por pieza, para que las piezas se puedan mover o animar individualmente) y Studio (fondo, luces, cámaras). Cada cámara está vinculada a un marcador de línea de tiempo, por lo que al desplazarse por la línea de tiempo se cambian las tomas. Los materiales son árboles de nodos Principled BSDF simples. El redondeo de bordes es un nodo de sombreado Bevel, por lo que la geometría permanece exacta.

El paquete embed

embed/ es completamente estático y no realiza ninguna solicitud externa. Incluye Google <model-viewer> (Apache-2.0) y el decodificador Draco. Sube la carpeta a cualquier lugar y pega snippet.html, o usa un iframe con embed.html. Incluye:

• assets/<slug>.glb: comprimido con Draco, con materiales coincidentes con los renders
• assets/<slug>.usdz: AR en iPhone/iPad mediante Quick Look
• una imagen de póster
• el HDRI de estudio para reflejos
• index.html: una página de demostración con botones de copia y descargas de renders

Notas de alojamiento para WordPress, Shopify, Webflow y otros en embed/README.md.

Errores comunes (cada uno ocurrió durante el desarrollo)

• Modelo de lado o al revés. SolidWorks, Inventor, Creo y Fusion tienen por defecto Y hacia arriba; la mayoría de los otros son Z hacia arriba. El convertidor lee el encabezado STEP para adivinarlo e imprime la suposición (up axis: Y (written by Solidworks)). Si es incorrecto, pasa --up z (o y, -y, x...).
• Piezas que se separan / "accidentalmente explotadas". La causa fue aplicar dos veces las transformaciones del ensamblaje. El constructor de escenas ahora verifica que agrupar piezas no mueva la geometría y se detiene si lo haría. Si editas el código de la escena, mantén esa comprobación.
• Metal plano y falso. Generalmente es la iluminación, no los materiales: sin entorno no hay nada que el metal pueda reflejar. Mantén un HDRI incluso con luces de área (--env-scale, no 0).
• Primer render sobreexpuesto. La potencia de la luz se escala al tamaño del modelo; si agregas luces personalizadas en lighting.json, la potencia es por (radio del modelo en metros)². Empieza bajo y usa --preview.
• Suposición de material incorrecta. Los nombres de piezas crípticos (P-0042, ASSY_7_REV2, nombres no ingleses transliterados) no coinciden con la búsqueda de palabras clave y recurren al color/tamaño. Para eso están las marcas (revísame). Escribe reglas para esas piezas.
• OCP 8 rompió el lector (TDF_LabelSequence se movió). El lector CAD fija cadquery-ocp-novtk<8. No lo desfijes sin volver a probar.
• El modelo web se ve diferente del render. glTF no puede transportar bump procedural, bevel o ruido de rugosidad, por lo que el modelo web solo obtiene los valores base. Esto es esperado; la imagen del póster es el render real.
• Ensamblejes enormes (>5M triángulos): usa --quality web para previsualizaciones; los renders finales aún funcionan pero necesitan RAM (aproximadamente 1 GB por cada 2M triángulos en Blender).

Verificación antes de entregar

1. Abre el PNG principal al 100 % e inspecciona la región más densa: sin caras negras, sin facetas en curvas, sin luciérnagas (puntos blancos).
2. Abre el PNG transparente sobre un fondo oscuro y otro claro: bordes limpios, sombra solo debajo del producto.
3. Sirve embed/ localmente (python3 -m http.server -d embed 8000), ábrelo y confirma que el modelo se carga, gira y no tiene errores en la consola. Verifícalo en un teléfono si la RA es importante.
4. Si materials_map.json aún tiene líneas revísame, menciónalo en la entrega.

Archivos

• scripts/studio.py: punto de entrada (CLI anterior)
• scripts/cad_to_glb.py: STEP/IGES/BREP a glTF con nombres de ensamblaje y colores CAD (script uv)
• scripts/automap.py: decisiones de pieza a material (Python puro, ejecutable de forma independiente)
• scripts/blender_studio.py: escena, materiales, luces, cámaras, renders, .blend, exportación web
• scripts/package_embed.py: el paquete de visor autoalojado
• assets/presets/*.json: materiales, configuraciones de iluminación, tomas de cámara
• examples/make_demo_model.py: construye el tornillo de banco de demostración (geometría original, CC0)