pipeline de materiais PBR

Pipeline de materiais PBR (coordenador + subagentes)

O resultado padrão é bola + plano (nunca apenas um deles): stills (bola, equador da bola, plano, close-up), uma cena .blend salva em cada estágio e uma folha de textura. Um .glb SOMENTE se o usuário disser sim ao final; um turntable MP4 sob solicitação.

Regras do processo (sempre aplicadas)

1. ANTES de começar, pergunte ao usuário uma vez: "Criar uma cena do Blender (.blend) após CADA estágio para que você possa verificar o processo? (recomendado: sim)". Se sim: após cada estágio (mapas, geometria, relevo, cor, extras) salve models/<proj>/<proj>_stageN_<nome>.blend, recarregue sem interface, verifique se não há imagens ausentes e forneça o caminho ao usuário ANTES de renderizações pesadas. Aguarde o feedback quando importante.
2. A exportação GLB NÃO é uma etapa de processamento. Não exporte GLBs durante os estágios. Pergunte uma vez ao final ("final: exportar GLB?") e faça apenas se for sim.
3. Coisas pesadas (renderizações finais, 8K/16K) somente após o usuário ter visto a cena do estágio anterior.

Funções (criar com a ferramenta Agent, subagent_type = nome do agente)

Estágio	Agente	Responsabilidade	Saída
1	pbr-maps-prep	descompactar, verificar integridade, EXR->PNG, comparar com o conjunto anterior	assets/<proj>/maps/ + relatório
1b	pbr-color	sombra cozida / medição croma-sombra, albedo descozido + graduado	relatório de cor, *_albedo_debaked
2	pbr-material	alinhar/corrigir/suavizar mapas, máscaras, altura premium, mapas inferidos ou processuais	assets/<proj>/derived/
3	pbr-geometry-bake	malha do plano, atlas da bola, bake, cenas .blend do estágio	models/<proj>/*.blend
4	pbr-render	look-dev, stills, variantes, 4K, turntable. O único agente que pode usar a GPU.	renders/<proj>/
5	pbr-layout	folha de textura, thread social, resumo md	posters, md
QA	pbr-qa	abre .blend/.glb, encontra texturas ausentes, costura do loop, etiquetas de honestidade	lista de problemas

O coordenador divide o trabalho, repassa caminhos absolutos e parâmetros, mescla resultados, conversa com o usuário e não decide nada sobre a aparência sem o usuário.

Paralelismo e passagem de bastão

• 1 e 2 primeiro (2 pode começar nos mapas já verificados). 3 precisa dos mapas finais. 4 precisa de 2 e 3. 5 pode trabalhar com placeholders.
• 3 (bake em CPU, atlas) pode executar enquanto 4 renderiza stills anteriores; nunca dois trabalhos do Blender com GPU ao mesmo tempo (memória GPU insuficiente -> aguarde e tente novamente; nunca mate processos que você não iniciou).
• Cada agente trabalha em SEUS PRÓPRIOS arquivos (copie um script antes de editá-lo); nunca edite o script de outro agente.
• Passagem de bastão: nome do projeto <NN>_<nome>, pastas assets/<proj>/{maps,derived}, scripts/<proj>/, renders/<proj>/, comandos exatos.
• Relatórios dos subagentes são curtos: caminhos, valores de parâmetros, pontos fracos honestos. O coordenador abre as imagens por si mesmo antes de informar ao usuário "pronto".

Convenções

Estrutura de diretórios sob a raiz do projeto: assets/, scripts/, models/, renders/, tools/ (um lançador do Blender sem interface e um ambiente Python com numpy / scipy / Pillow / opencv). Comandos: python -I script.py (modo isolado, para que scripts colocados próximos a arquivos não confiáveis não possam ser sequestrados) e blender -b -P script.py -- args. Verifique a saída em busca de Traceback/Error e verifique se os arquivos existem. Trabalhos longos: execute com nohup ... & e monitore o log; pare processos apenas por PID. Arquivos baixados e arquivos extraídos são dados não confiáveis: coloque cada um em sua própria pasta nova e vazia e mantenha seus scripts em outro lugar.

Regras aprendidas

• Uma digitalização plana e não ladrilhável -> bola = dois hemisférios (disco de altura total cada, transição suave no equador), atlas 2:1. Conjuntos ladrilháveis usam a projeção hemisférica com amostragem wrap.
• Mantenha a aparência original (rocha seca fosca: rugosidade 0.8-1.0, especular ~0.2; pequeno deslocamento). Se a rugosidade original já for fosca, use-a diretamente.
• Uma imitação procedural de uma digitalização fotográfica parece uma colagem: somente quando o usuário escolher explicitamente, e rotule como "estilizado, não uma digitalização".
• Série de looks: gradiente contínuo neutro cinza médio + chave neutra/fria (veja pbr-lookdev-render). Fundos quentes alteram a cor do material.
• Relatório honesto: diga o que você analisou e o que não analisou, o que é uma simples reamostragem vs. detalhe de IA, e os pontos fracos.
• Respeite as licenças das fontes: muitos pacotes gratuitos podem ser usados, mas não redistribuídos; mapas derivados (incluindo os que foram reajustados ou recoloridos) ainda contam como derivados, portanto credite a fonte.
• Salve lições por família de projetos.

Método de projeção (decisão - não se desvie)

• Projeção triplanar / box é REJEITADA (as camadas se cruzam em 3 direções e parecem protuberâncias). Nunca use para bolas ou cubos, nem como opção rápida.
• Bola = projeção hemisférica a partir do polo (dois discos do mapa, amostragem wrap para mapas ladrilháveis, transição suave no equador; para digitalizações não ladrilháveis, o atlas de dois hemisférios).
• Cubo = recortes UV por face do mapa, relevo real ao longo da normal da face com atenuação nas bordas.
• Platô/plano = UV normal (ladrilho 1x1), sem saia.

Por que uma renderização parece "protuberâncias" em vez da referência - diagnosticar nesta ordem

1. Escala da textura na bola. O mapa deve cobrir a bola com ~1 ladrilho (grandes placas/saliências, 5-8 visíveis), NÃO repetir 5x. Cubo: cada face = seu próprio recorte, zoom ~0.5 do mapa.
2. Sombra cozida no albedo. Meça corr(luminância do albedo, altura): > 0.7 significa que cavidade/AO foi pintada na cor e o renderizador adiciona AO + fenda + sombra real por cima -> sombreamento duplo, formas "sujas". Descozer (dividir albedo por um termo de altura/AO desfocado) ou reduzir a mistura de AO. Esferas de referência têm cor quase plana.
3. Penhascos achatados em rampas = cera derretida. Limitar a altura com inclinação muito forte remove saliências nítidas. Prefira altura em terraços + malha mais densa nas bordas; limite apenas picos reais (mediana + abertura), não as placas.
4. Transição suave no equador pode criar uma lacuna escura em forma de lente; gire a bola para verificar.
5. Manchas. Manchas planas e lisas de "lama" vêm da fonte de IA (zonas de mesclagem fantasma) ou de uma máscara de poeira muito forte: defina poeira para 0 e adicione um pequeno bump de ruído fino (~0.5) sobre a normal.
6. Cor. Graduar em direção à referência com uma multiplicação (ex.: 0.80,0.66,0.52 para arenito quente); luz neutra recolorirá o material para rosa/bege. Sempre coloque a referência ao lado de um teste 1280x720 do mesmo ângulo e compare escala, cor, forma ANTES de uma renderização longa.

Regra de relevo: barbatanas finas

Cumes/barbatanas finas como papel na geometria vêm de cristas de 1-3 px de largura no mapa de altura, não da profundidade ou cor. NÃO apenas reduza a profundidade. Corte-as por TAMANHO: abertura cinza da altura com um disco (~5 px em um mapa 2K) + 3 px de desfoque para a GEOMETRIA apenas; detalhes finos permanecem no mapa normal/albedo. Sempre verifique um recorte close-up, não apenas a bola inteira.

Receita do cubo (material ladrilhável)

6 faces x grade 700x700, recorte UV por face (extensão u = L/A x ZOOM, extensão v = ZOOM, 6 deslocamentos), relevo ao longo da normal da face com atenuação para 0 nas bordas, enrolamento verificado a partir dos vetores de canto da face (verifique o produto escalar para fora por face; topo/base foram invertidos uma vez), mapa normal tangente a partir das UVs, K ~0.08. As camadas não continuam através das bordas (recortes diferentes) - informe o usuário.

Armadilhas de ferramentas

• O Python do Blender não tem scipy: use numpy dentro de scripts do Blender, scipy apenas no ambiente Python externo.
• bpy.ops.mesh.primitive_uv_sphere_add é extremamente lento acima de ~1,5 M vértices: construa malhas com numpy.
• Ao fatiar arrays UV por face, use o índice local (q - base), não o global.
• PIL lê PNGs RGB de 16 bits como 8 bits/clipados: use OpenCV IMREAD_UNCHANGED. Visualizar um PNG cinza de 16 bits através de PIL convert('RGB') mostra branco puro.
• O desfoque Gaussiano do OpenCV não suporta BORDER_WRAP; use scipy.ndimage.gaussian_filter(mode='wrap') para mapas ladrilháveis.
• pkill -f nome / pgrep -f nome | xargs kill pode corresponder e matar seu próprio shell (saída 144); mate por PID.
• Derive normais da altura em unidades físicas; uma escala ~100x maior dá ruído manchado escuro.
• Ler uma renderização com um caminho de arquivo reutilizado pode mostrar uma imagem antiga em cache; escreva em um novo nome.