abchiaravalle/cad-studio-renders

Renderizações de estúdio CAD

Transforme uma montagem CAD nos itens que uma página de produto precisa: imagens fotorrealistas de estúdio, recortes transparentes, um vídeo giratório e um visualizador 3D auto-hospedado com AR para celular. Toda a execução é feita com um único comando e tudo roda localmente. A GPU faz a renderização; não há geração de imagens por IA, então os pixels são a geometria real.

python3 "${CLAUDE_SKILL_DIR}/scripts/studio.py" model.step --name "Nome do Produto"

${CLAUDE_SKILL_DIR} é a pasta deste skill (o Claude Code preenche automaticamente). Em outros agentes, use a pasta onde este SKILL.md está. Todos os caminhos de script abaixo são relativos a essa pasta.

Quando usar

• "Renderize este arquivo STEP", "faça imagens de produto / packshots a partir de CAD", "renderização fotorrealista desta peça"
• "Coloque um modelo 3D deste produto no nosso site", "torne-o giratório", "visualização AR do produto"
• "PNG transparente do produto", "recorte para o catálogo", "vídeo giratório"
• Um artista 3D quer uma cena Blender editável para finalizar manualmente

Não é este skill: modelar uma peça do zero (use uma ferramenta CAD), geração de imagem a partir de um prompt de texto ou renderizar uma cena que não seja um produto (interiores, personagens).

Instalação deste skill

• Claude Code, terminal: claude plugin install cad-studio-renders --marketplace abchiaravalle/cad-studio-renders
• Claude Code, aplicativo desktop: peça ao Claude para clonar https://github.com/abchiaravalle/cad-studio-renders em ~/.claude/skills/cad-studio-renders (o aplicativo desktop e o terminal leem essa mesma pasta).
• Qualquer outro agente: coloque esta pasta no diretório onde esse agente carrega pastas SKILL.md.

Requisitos (verifique primeiro)

blender --version       # 4.2 ou mais recente. Se faltar: https://www.blender.org/download/
uv --version            # lê o arquivo CAD. Se faltar: https://docs.astral.sh/uv/
ffmpeg -version         # necessário apenas para vídeos --turntable

Se o Blender estiver instalado mas não no PATH, defina BLENDER=/caminho/para/blender. Uma GPU (Apple Silicon, NVIDIA, AMD) torna as renderizações 5 a 20 vezes mais rápidas; CPU funciona, mas é mais lento. A primeira execução baixa uma biblioteca CAD (~60 MB) e um HDRI de estúdio (24 MB, CC0) para ~/.cache/cad-studio-renders/.

Fluxo de trabalho

1. Mapeie os materiais antes de renderizar qualquer coisa. Arquivos CAD raramente trazem acabamentos reais.

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

   Leia a tabela. Cada peça mostra seu preset e o motivo. Linhas que terminam com (review me) são palpites. Corrija os errados com um arquivo de regras (próxima seção) e execute novamente --map-only até que esteja correto.
2. Preview (cerca de 10 s): --preview renderiza um rascunho de 1000 px. Olhe antes de gastar minutos em finais. Verifique: orientação correta, peças montadas (nada flutuando), enquadramento, materiais.
3. Final: remova --preview. Os padrões geram uma imagem principal de 2400 px com fundo de estúdio, a mesma imagem como PNG transparente, um .blend editável e o pacote de incorporação web.
4. Verifique a saída no tamanho original (amplie a região mais densa) antes de entregar.

Corrigindo materiais: o arquivo de regras

{"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 é uma expressão regular sem distinção entre maiúsculas e minúsculas testada contra o nome da peça, nome da instância e caminho da montagem. A primeira regra correspondente vence. params substitui qualquer valor de preset (roughness, metallic, coat, anisotropic, bevel, bump...). offset_mm define a posição dessa peça na vista explodida. Os presets estão em assets/presets/materials.json; adicione novos lá.

Sem regras, o mapeador automático usa, nesta ordem: palavras-chave do nome da peça (fixadores, rolamentos, trilhos lineares, fusos de esferas, motores, borracha, vidro...), depois a cor do CAD (cores saturadas tornam-se tinta, peças que compartilham uma cor compartilham um acabamento), depois o tamanho.

Opções importantes

Flag	O que faz
--shots hero,front,side,top,iso,back,square,hero_low,detail	Quais ângulos de câmera (assets/presets/shots.json)
--lighting studio_soft / high_key / dramatic / hdri_only	Esquema de iluminação (assets/presets/lighting.json)
--backdrop 0.42 ou --backdrop "#1d1f22"	Fundo cinza ou cor
--size 4000 --aspect 16:9	Tamanho e proporção da saída
--samples 768	Mais amostras = detalhes brilhantes mais limpos, renderização mais longa
--exposure 0.3, --light-scale 1.2, --env-scale 0.8	Brilho
--hdri photo_studio_01 ou --hdri meu.exr, --hdri-rotation 40	Ambiente de reflexão
--dof 0 / --dof 2	Desfoque de fundo desligado / menos desfoque
--bevel-scale 0	Desligar arredondamento de bordas (arredondar é o que torna o CAD realista)
`--detail-target "spindle	chuck"com--shots detail`
--no-transparent, --no-backdrop, --no-embed, --no-blend	Pular entregáveis
--clay	Passada em argila cinza (verificação de iluminação/formas, revisões de design)
--passes	EXR multicamadas: profundidade, normais, AO, névoa, cryptomatte (IDs de objeto + material)
--exploded 0.4	Vista explodida (peças empurradas do centro; regras offset_mm substituem)
--turntable [--turntable-transparent]	MP4 360° + WebM (alfa opcional) + quadros PNG
--up y	Forçar o eixo para cima se a detecção automática errar

O que você obtém

<modelo>_studio/
  hero.png                    16 bits, no fundo de estúdio
  hero_transparent.png        16 bits RGBA, sombra de contato suave mantida (--shadow none para removê-la)
  hero_clay.png, hero_exploded.png, hero_passes.exr       (quando solicitado)
  <slug>_turntable.mp4 / .webm, turntable_frames/          (quando solicitado)
  <slug>_scene.blend          luzes, câmeras, materiais, fundo, texturas compactadas
  materials_map.json          cada peça -> preset + motivo (edite e execute novamente via --rules)
  manifest.json               configurações, tempos, lista de arquivos com tamanhos e hashes
  embed/                      pacote de visualizador 3D auto-hospedado (veja abaixo)

O .blend é feito para finalização manual. Coleções: Product (um empty por peça, para que as peças possam ser movidas ou animadas individualmente) e Studio (fundo, luzes, câmeras). Cada câmera está vinculada a um marcador de timeline, então avançar na timeline alterna as tomadas. Os materiais são árvores de nós Principled BSDF simples. O arredondamento de bordas é um nó de shader Bevel, para que a geometria permaneça exata.

O pacote de incorporação

embed/ é totalmente estático e não faz nenhuma requisição externa. Ele inclui o Google <model-viewer> (Apache-2.0) e o decodificador Draco. Faça upload da pasta em qualquer lugar e cole snippet.html, ou use iframe embed.html. Inclui:

• assets/<slug>.glb: Comprimido com Draco, com materiais correspondentes às renderizações
• assets/<slug>.usdz: AR para iPhone/iPad via Quick Look
• uma imagem de pôster
• o HDRI do estúdio para reflexões
• index.html: uma página de demonstração com botões de cópia e downloads de renderização

Notas de hospedagem para WordPress, Shopify, Webflow e outros estão em embed/README.md.

Armadilhas (cada uma ocorreu durante o desenvolvimento)

• Modelo de lado ou de cabeça para baixo. SolidWorks, Inventor, Creo e Fusion usam Y para cima por padrão; a maioria dos outros é Z para cima. O conversor lê o cabeçalho STEP para adivinhar e imprime o palpite (up axis: Y (written by Solidworks)). Se estiver errado, passe --up z (ou y, -y, x...).
• Peças se afastando / "explodidas acidentalmente". A causa foi transformações de montagem aplicadas duas vezes. O construtor de cena agora verifica que agrupar peças não move a geometria e aborta se isso acontecer. Se você editar o código da cena, mantenha essa verificação.
• Metal plano e falso. Geralmente é a iluminação, não os materiais: sem ambiente, não há nada para o metal refletir. Mantenha um HDRI mesmo com luzes de área (--env-scale, não 0).
• Primeira renderização desbotada. A potência da luz é dimensionada ao tamanho do modelo; se você adicionar luzes personalizadas em lighting.json, a potência é por (raio do modelo em metros)². Comece baixo e use --preview.
• Palpite de material errado. Nomes de peça enigmáticos (P-0042, ASSY_7_REV2, nomes não ingleses transliterados) impedem a correspondência por palavras-chave e recorrem à cor/tamanho. É para isso que servem os flags (review me). Escreva regras para essas peças.
• OCP 8 quebrou o leitor (TDF_LabelSequence movido). O leitor CAD fixa cadquery-ocp-novtk<8. Não remova a fixação sem testar novamente.
• O modelo web parece diferente da renderização. glTF não pode transportar bump procedural, bevel ou ruído de rugosidade, então o modelo web recebe apenas os valores base. Isso é esperado; a imagem do pôster é a renderização real.
• Montagens enormes (>5M triângulos): use --quality web para previsualizações; renderizações finais ainda funcionam, mas precisam de RAM (cerca de 1 GB por 2M triângulos no Blender).

Verificação antes de entregar

1. Abra o PNG principal em 100% e inspecione a região mais densa: sem faces pretas, sem facetamento em curvas, sem fireflies (pontos brancos).
2. Abra o PNG transparente sobre um fundo escuro e um claro: bordas limpas, sombra apenas sob o produto.
3. Sirva embed/ localmente (python3 -m http.server -d embed 8000), abra e confirme que o modelo carrega, gira e não tem erros no console. Verifique em um celular se o AR for importante.
4. Se materials_map.json ainda tiver linhas review me, informe na entrega.

Arquivos

• scripts/studio.py: ponto de entrada (CLI acima)
• scripts/cad_to_glb.py: STEP/IGES/BREP para glTF com nomes de montagem e cores CAD (script uv)
• scripts/automap.py: decisões de peça para material (Python puro, executável sozinho)
• scripts/blender_studio.py: cena, materiais, luzes, câmeras, renderizações, .blend, exportação web
• scripts/package_embed.py: pacote do visualizador auto-hospedado
• assets/presets/*.json: materiais, esquemas de iluminação, tomadas de câmera
• examples/make_demo_model.py: constrói o morsa de demonstração (geometria original, CC0)