polywright

O que polywright faz?

O hub para trabalho com modelos 3D. Decide como um modelo será criado, mantém cada recurso em uma pasta com um manifesto e comprova cada etapa com números e uma imagem. As habilidades irmãs detêm a profundidade.

Script: scripts/pw.py nesta pasta da habilidade (Python 3.9+, biblioteca padrão, um objeto JSON por comando; scripts/pw_bpy.py é sua metade Blender, nunca executada manualmente). Execute python <caminho desta pasta>/scripts/pw.py doctor uma vez por sessão: ele encontra o Blender (qualquer SO), as bibliotecas Python de malha, slicers e hosts ComfyUI, e informa o que está faltando. Lista completa de comandos: references/cli.md.

Etapa 1: o briefing (pergunte apenas o que você não pode inferir)

• O quê: o objeto ou local, real ou imaginado, e quão reconhecível ele deve ser.
• Alvos: um ou mais de pw.py check --list (game-roblox, game-unity, game-unreal, web-threejs, ar-usdz, commerce-gltf, print-fdm, print-resin, video-blockout, cad-step). O alvo define o orçamento.
• Tamanho real em metros (um banco tem 1,8 m de comprimento; uma pessoa 1,7 a 1,8 m). Escala errada é o erro silencioso mais comum; check --real-size-m detecta isso.
• Entradas: um prompt, fotos, um esboço, medidas, uma localização no mapa, uma malha existente.
• Fidelidade e orçamento: blockout, pronto para jogo, herói; quanto tempo ou dinheiro um gerador hospedado pode custar.

Scaffold: pw.py new <dir> --name <Nome> --kind real|imaginado|hibrido --route <rota> --targets a,b --real-size-m X. Pasta: refs/ (referências, cada uma registrada como fonte), work/ (.blend, intermediários), out/ (um entregável por alvo), renders/ (folhas de revisão), brief.md, manifest.json. Contrato para outros plugins: references/contract.md.

Etapa 2: escolha a rota (a mais barata que atende ao briefing)

Situação	Rota	Habilidade
Um objeto comum; licença permite reuso	encontrar: Poly Haven, Kenney, Quaternius (CC0), Sketchfab e sites de impressão (verifique cada licença)	esta habilidade, references/routes.md
Tem dimensões, partes que se encaixam, arestas vivas (suporte, caixa, prédio, móvel)	código (--route procedural): bpy, build123d/CadQuery/OpenSCAD	polywright-generate, polywright-blender
Um local real (parque, rua, campus, terreno)	lugar: OSM + elevação (pw.py place)	polywright-capture
Um objeto real que você pode fotografar ou escanear	capturar: fotogrametria, splats, escâner ou modelo a partir de medidas	polywright-capture
Imaginado, orgânico ou único (estátua, criatura, adereço)	gerar: folha de referência, depois imagem para 3D	polywright-references, polywright-generate
Personagem herói que deforma	gerar ou esculpir como base, depois retopologia e rig	polywright-generate, polywright-finish

A maioria dos bons resultados mistura rotas: um parque OSM com adereços heróis gerados, uma casa construída por código com uma estátua gerada. Registre a rota por parte no manifesto.

Etapa 3: referências antes da geometria

Para qualquer coisa não encontrada pronta, reúna ou gere referências primeiro (polywright-references): vistas ortográficas em uma linha de solo compartilhada com uma barra de altura, amostras de material, referências de escala. Entradas geradas decidem a maior parte do resultado imagem para 3D.

Etapa 4: construa, depois comprove (toda rota)

1. Blockout primeiro no tamanho real: primitivas para silhueta e proporção. Corrija a escala aqui; é barato agora.
2. Números: pw.py inspect <arquivo>: triângulos, objetos, tamanho, materiais, texturas, UVs, estanqueidade, partes. Leia antes e depois de cada etapa destrutiva.
3. Imagem: pw.py render <arquivo> --out renders/<etapa>: seis vistas e uma sheet.png. Leia a folha, não seis capturas de tela. Compare com as referências: silhueta, proporção, partes faltando ou flutuantes, picos de sombreamento, eixo errado (deitado de lado), escala errada.
4. Alvo: pw.py check <arquivo> --target <t> --real-size-m X. Falha significa corrigir antes de entregar; aviso significa informar na transferência.
5. Registre: pw.py manifest <dir> --add-output out/<arquivo> --target <t> --inspect, cada fonte com --add-source <url> --licence <l> --author <a>, depois --validate.

Planeje, aja e critique são passagens separadas: após construir, olhe a folha como um crítico faria e liste defeitos antes de afirmar que está pronto. Duas rodadas corrigindo um traceback valem a pena; depois disso, repense a abordagem. Salve um .blend numerado por marco (work/<nome>_v03.blend) para que um trabalho longo possa reiniciar do disco.

Compor um modelo em uma imagem

Quando um modelo de imagem ou vídeo continua desenhando um adereço projetado de forma errada (um quadro de storyboard, uma referência de cenário, um pôster), pegue a composição da imagem e a forma do modelo:

1. Escolha a imagem apenas para composição: onde as pessoas estão, a luz, o objetivo. Um adereço substituto simples é suficiente.
2. pw.py match model.blend --still pic.png --out work/match.png --anchor-px X,Y --anchor-local=X,Y,Z --aim-px X,Y --aim-local=X,Y,Z --depth M --horizon LINHA --hide CAIXA --mask-add CAIXA: a âncora do modelo (uma empunhadura) aterrissa na mão, seu ponto de mira (uma ponta) no pixel exato, renderizado RGBA com a lente e o horizonte da imagem. Defina --depth para que sua largura em pixels corresponda à do substituto (largura = f_px x diâmetro / profundidade; f_px está no resultado). --hide elimina a parte atrás de uma mão; --mask-add adiciona as mãos à máscara.
3. Leia match_paste.png recortado em 3x: forma, tamanho no quadro, mira. Corrija profundidade e pixels, execute novamente (segundos).
4. Mescle dentro de match_mask.png com uma edição de imagem mascarada de baixa remoção de ruído (FLUX.2 Klein ou qualquer modelo de inpaint: remoção de ruído 0,3 a 0,5, cfg baixo), depois cole o resultado de volta através da máscara para que cada pixel fora permaneça o da imagem. Uma edição de imagem inteira redesenha tudo (cor HDR, um adereço maior).
5. Verifique no tamanho original; mantenha duas ou mais sementes.

As folhas de referência do adereço vêm do modelo também (polywright-references, Etapa 2b).

Sprites de jogo a partir de um modelo

Quando um modelo de imagem continua errando um mecanismo em um sprite de jogo (uma roda que não é redonda, uma lâmina no telhado), construa o modelo, renderize-o através da própria câmera do jogo e deixe o modelo de imagem apenas pintar:

1. pw.py spritecam <registry.json> --like <sprite> --out camera.json: a câmera ortográfica ajustada a partir dos losangos do solo do jogo (L-014). Defina tile_m nele para os metros por tile do modelo.
2. Construa o modelo com um prefixo de parte por objeto (wheel_, roof_...) na propriedade de cena sprite_parts, movendo partes sob um vazio de pivô construído no espaço do pivô, e o movimento na propriedade de cena loop.
3. pw.py sprite model.blend --camera camera.json --out renders/L1 --scale 10.6667 (1024 px para um sprite de 96 px): leia o estilo sheet das passagens e da beleza em 1x ao lado dos sprites do jogo; --frames N --frame-passes id,pos para uma parte animada, --hide wheel_ para uma placa sem ela. Em seguida, verifique o tamanho em relação aos vizinhos do jogo antes de pintar: aw.py sprite <beauty at 96> --refs <sprites da mesma classe> falha uma cobertura abaixo de 0,9 da mediana deles. O ajuste do losango define a escala do solo, não o tamanho que o prédio tem: adicione massa e adereços primeiro (paredes mais altas, um anexo, um quintal), depois aumente px_per_tile e mova footprint_centre_px para que a caixa delimitadora cubra a tela como os vizinhos (L-016). Mantenha vigas finas longe da silhueta de um cilindro: um tronco nivelado sobre encostas inclinadas é lido como passando acima e abaixo delas (L-017).
4. Pinte a beleza com Canny do clay como controle (um modelo de imagem com um ControlNet), corte com o alfa da renderização para que o enquadramento e groundBase permaneçam exatos, depois verifique a pintura contra os dados de ID e aro em sprite.json.

Ilustrações de cena a partir de um modelo

Uma tela de carregamento, uma arte-chave ou uma capa em torno de um modelo que já existe (um prédio, uma máquina): construa a cena no Blender e deixe o modelo de imagem pintá-la, para que o mecanismo e o layout permaneçam corretos.

1. Construa a cena em torno do modelo com um prefixo de parte por objeto na propriedade de cena scene_parts, rodas e discos em rings, pontos-chave ou caminhos em scene_points. Bancos, diques e paredes ao longo de um caminho são um sweep cada (importe de scripts/pw_scene.py em um script pw.py bpy), não uma fileira de caixas (L-020).
2. pw.py framecam problem.json --out cameras.json: pontos do mundo com caixas de tela, pontos mantidos no quadro e fora das faixas de texto da interface, uma medida de tamanho para maximizar; imprime as melhores câmeras como predefinições. Pegue as faixas do arquivo real da interface (seu padding e âncoras), não de uma regra prática (L-018).
3. pw.py scene scene.blend --cameras cameras.json --camera framecam_1 --out renders/v1 --size 1280x720 (o tamanho de primeira passagem do fluxo de pintura): clay, beleza, profundidade, normal, id, linha e scene.json. Leia clay e profundidade primeiro; deixe o alcance da profundidade para a própria medição da cena, a menos que uma predefinição exija que seja fixo (L-019).
4. Pinte com controle (profundidade ou linha), depois compare a pintura com scene.json: aros de anéis, pontos, cores de id.

Blockouts de multidão e batalha (vídeo com IA)

Modelos de vídeo falham em multidões; Blender não. Deixe o Blender posicionar o exército e o modelo de vídeo pintar a aparência:

1. pw.py crowd --out work/crowd --action clash --preview (ou march, advance, charge, hold; --view, --lens, --move), depois leia work/crowd/sheet.png.
2. Remova --preview para a tomada completa: depth.mp4 (controle principal), pose.mp4 (fileiras da frente), mask.mp4, clay.mp4, camera.json; 832x480, 81 quadros a 16 fps por padrão (Wan).
3. Repinte o clay quadro 1 em uma imagem inicial aprovada; conduza Wan VACE ou Wan 2.2 Fun Control com o vídeo de profundidade e essa imagem. Solicite figurino, cor por lado, luz e névoa, não a contagem de cabeças.

Detalhes e o que não foi testado: references/crowd-blockouts.md. O planejamento de tomadas é do cinewright.

Dois lutadores: pw.py duel shot.json --preview posiciona dois manequins em suas marcas no cenário, através da câmera da tomada (examples/duel.json); leia sheet.png, depois remova --preview para cada mp4 de controle. Mais: crowd-blockouts.md, "Dois lutadores".

Um pequeno elenco de figuras reais ou brinquedos (lados trocados, uma figura extra, marcações perdidas): faça a malha de cada um a partir de fotos, corrija cor e marcações pintadas com pw.py mark, forneça ao modelo de vídeo imagens pw.py turnaround como referências e um pw.py lineup (equipes em lados fixos, profundidade e máscara) como sua abertura: references/figures-for-video.md.

Cenários e adereços para uma tomada de filme: references/film-and-video.md.

Etapa 5: finalize e entregue

Finalização por alvo (UVs, LODs, convenção de mapa normal, conversão de eixo e unidade, compressão) é polywright-finish; impressão (sólido estanque, paredes, base, divisão, 3MF) é polywright-print. Entregue a pasta para o plugin que a utiliza: páginas three.js (threewright), filme e vídeo (cinewright), lugares Roblox (roblox-agent), projetos Unity (unity-agent), uma habilidade de impressora ou slicer para configurações de impressão, uma habilidade de imagem para mais imagens. Eles leem manifest.json e out/.

Mensagem de entrega:

Modelo: <nome> (<rota>) -> out/<arquivo> para <alvo>: <tris> tris, <tamanho> m, <estanque/partes>
Verificação: <alvo> passou|aviso (<regras>)   Revisão: renders/<etapa>/sheet.png
Fontes: <n> com licenças; partes feitas por IA: <quais, qual modelo>   Pendente: <o que não está pronto>

Regras

• Tamanho real em metros no Blender e glTF (+Z para cima no Blender, +Y para cima no glTF); milímetros apenas em arquivos de impressão.
• Nunca afirme que uma malha está boa a partir de seu nome de arquivo ou da palavra de um gerador: inspecione, renderize, verifique.
• Cada entrada baixada ou gerada recebe uma linha de fonte com sua licença. Lojas e sites de impressão (Fab, Unity Asset Store, Sketchfab, MakerWorld, Printables, Steam) exigem divulgação de conteúdo feito por IA; o manifesto registra isso.
• Pontes Blender sobre MCP executam Python arbitrário: prefira pw.py bpy em cópias; use uma sessão MCP ao vivo apenas quando o usuário está assistindo (polywright-blender).
• Google Photorealistic 3D Tiles pode ser visualizado, nunca exportado, armazenado em cache ou rastreado (seus termos).

Manutenção

Unidade perene, nível fast (geradores e Blender mudam mensalmente). Companheiros: RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md com evals/evals.json, MAINTENANCE.md, estado em evergreen.json. Leia evergreen.json a cada uso; se estiver na hora, faça a tarefa, depois atualize (evergreen-refresh). Escreva lições em LEARNINGS.md à medida que acontecem.