shrugg0/blueprint-maker

Blueprint Maker

Gera uma folha técnica estilo blueprint (PNG, 1920x1080 padrão) a partir de:

• um modelo 3D -> vistas ortográficas reais com linhas ocultas: uma vista grande 3/4 mais vistas lateral, superior e frontal com linhas de cota medidas (pipeline 3D), ou
• uma imagem 2D -> extração de linhas com contorno de silhueta, dimensões da caixa delimitadora e chamadas (pipeline 2D).

Ambos os pipelines compartilham um mecanismo de layout (quadro, painéis, bloco de título, ajuste de texto) para que o resultado tenha a mesma aparência.

O que pode e não pode fazer (diga isto ao usuário quando relevante)

• Sem arquivo, sem blueprint. Um objeto descrito apenas em palavras não pode ser transformado em um desenho preciso. Peça um modelo 3D ou uma imagem. Não invente geometria.
• 3D fornece vistas ortográficas reais; 2D não. Uma única foto tem um ponto de vista, então o pipeline 2D produz uma vista de linha, não frente/lateral/superior.
• A qualidade da linha depende da malha/imagem. Malhas extraídas de jogos com centenas de milhares de triângulos geram linhas densas; é uma boa base automática, não qualidade de ilustração feita à mão.
• A escala é desconhecida a menos que o usuário a forneça. As dimensões são em unidades do modelo (u) ou pixels (px) a menos que um scale_ref (uma medida real) seja fornecido. Nunca apresente um tamanho real adivinhado como verdade.
• Fontes: a renderização de texto incluída usa DejaVu (Latim, Grego, Cirílico). Texto CJK/Árabe/Hebraico não será renderizado corretamente.
• Layout é projetado para 16:9 (testado em 1920x1080, 2560x1440 e 1920x1200). Outras proporções esticam o layout do painel; verifique a saída.
• Ativos extraídos de jogos/filmes são propriedade intelectual de terceiros. Tudo bem para um papel de parede pessoal; mencione para não redistribuir.

Etapa 0 - Coletar entradas (pergunte uma vez, apenas o que está faltando)

1. O arquivo (modelo ou imagem).
2. Nome do objeto e uma descrição - ou ofereça-se para redigir. A descrição deve corresponder ao que realmente está no render (olhe primeiro). Uma descrição de um veículo com rodas sobre uma criatura de quatro patas destrói a credibilidade da folha; se o texto do usuário não corresponder à geometria, diga isso e reescreva.
3. Resolução de saída e a zona segura superior se for um papel de parede (uma barra da área de trabalho cobre o topo). Padrão top_safe = 76 (o quadro começa 76 px abaixo em 1080p, espaço para uma barra de ~1 cm em um laptop). Se o usuário fornecer centímetros, converta: px_por_cm = largura_tela_px / largura_tela_cm (cerca de 36 px/cm em um monitor 24" 1080p, cerca de 56 px/cm em um laptop 15,6"). Use altura da barra em px + ~12.
4. Estilo: blueprint (padrão, azul), graphite (escuro com linhas laranja), paper (claro, imprimível).
5. Idioma do texto (padrão inglês; escreva o texto da especificação nesse idioma).

Não interrogue o usuário: se ele já forneceu o suficiente, prossiga com os padrões e declare suas suposições.

Etapa 1 - Configuração

pip install trimesh numpy scipy networkx pillow opencv-python-headless matplotlib --break-system-packages -q
# opcional, apenas para malhas > 700k faces: pip install fast-simplification --break-system-packages

Todos os scripts residem em scripts/ ao lado deste arquivo. Substitua SKILL_DIR pela pasta da skill.

Etapa 2A - Modelo 3D

Inspecionar (sempre faça isso primeiro - uma imagem, um comando)

python3 SKILL_DIR/scripts/blueprint3d.py inspect MODEL.glb --out /home/claude/insp

Abra inspect.png com view (é uma única folha de contato) e leia o texto impresso:

• Linha superior = projeções brutas dos eixos: descubra qual eixo bruto é para cima e para qual direção o objeto está voltado.
• Parte inferior = a vista 3/4 com candidatos a âncora numerados (amarelo). O console lista cada cand N com sua posição em pixels e canônica. A grade tênue está em 1500x860 pixels de referência (utilizável como pick).

Flags de orientação (quadro canônico: +y para cima, frente do objeto em direção a -x): --up +Y (padrão para GLB/glTF; +Z para outros formatos) e --front -X|+X|+Z|-Z|.... A dica impressa nomeia o eixo horizontal mais longo; a frente deve estar à ESQUERDA da vista lateral, então inverta o sinal se a cabeça/frente estiver do outro lado. Se a orientação estiver errada, execute inspect novamente uma vez com outros valores. Coloque os valores finais na especificação como "up" e "front".

inspect também aceita --az, --el (padrão 58 / 20) e --k (número de candidatos, padrão 16). Use o mesmo az/el de view na especificação, caso contrário os números dos candidatos não corresponderão.

Escrever a especificação

Crie spec.json (esquema abaixo, exemplo funcional em assets/example_spec_3d.json). Para cada chamada, forneça um título, uma descrição curta e uma âncora:

• "cand": N - um candidato numerado de inspect.png (mais barato: sem adivinhar pixels). Os candidatos estão espalhados pela superfície visível, então verifique se o ponto realmente cai na parte que você nomeia; se nenhum candidato estiver próximo o suficiente, use pick.
• "pick": [px, py] - pixel na vista de referência 1500x860 (a grade em inspect.png)
• "extreme": "+x" | "-x" | "+y" | "-y" | "+z" | "-z" - ponto extremo no quadro canônico (frente é -x; pode estar oculto atrás da geometria)
• "point": [x, y, z] - coordenadas canônicas exatas

Não defina "label" a menos que necessário: as posições dos rótulos são então escolhidas automaticamente (texto mantido longe da silhueta do modelo e de outros rótulos, colunas organizadas nas laterais do painel, líderes curtos sem cruzamento). "label": [x, y] (coordenadas de referência 1920x1080, painel principal x 40-1290, y 96-826) força uma posição manual e é verificado pela auditoria abaixo.

Construir

python3 SKILL_DIR/scripts/blueprint3d.py build MODEL.glb spec.json --out /mnt/user-data/outputs/blueprint.png

As vistas pintadas são armazenadas em cache no disco (~/.cache/blueprint-maker, ou $BP_CACHE), indexadas por modelo + vista + estilo. Alterar texto, rótulos, chamadas ou conteúdo independente da paleta reconstrói em cerca de 2 s em vez de repintar; --no-cache ou "cache": false desativa isso.

Layouts: "layout": "multi" (padrão: vista grande 3/4 + lateral/superior/frente + dimensões) ou "single" (apenas a vista 3/4, mais larga).

Lock de especificação (vinculação entre especificação e modelo)

Âncoras escritas como cand, pick ou extreme só fazem sentido para o modelo, orientação e vista em que foram escolhidas. A primeira construção escreve <spec>.lock.json ao lado da especificação: o ponto 3D ao qual cada âncora foi resolvida, uma impressão digital geométrica do modelo e as configurações que influenciam as âncoras (up, front, az/el da vista, candidates, max_faces). Toda construção posterior re-resolve as âncoras e compara:

• âncoras movidas (modelo, orientação ou vista diferente) -> a construção falha com error: spec is not bound to this model..., nomeando cada chamada e o que mudou. Reexecute inspect com as configurações da especificação, escolha novamente as âncoras e construa com --relock (ou restaure o modelo/configurações originais);
• modelo diferente, mas cada âncora ainda cai no mesmo lugar (por exemplo, reexportação sem perdas) -> WARNING: binding: ...; verifique, então --relock;
• você editou uma âncora propositalmente (mesmo modelo/configurações) -> a entrada do lock é atualizada silenciosamente.

--no-lock ignora a verificação (não recomendado). Mantenha o arquivo de lock com a especificação (commit). Nunca "corrija" um erro de vinculação ignorando-o: os rótulos apontariam para as partes erradas.

Etapa 2B - Imagem 2D

python3 SKILL_DIR/scripts/blueprint2d.py inspect IMAGE.png --out /home/claude/insp

Leia a cobertura da máscara impressa (a remoção de fundo funciona para fundos planos ou PNGs transparentes; caso contrário, relata "none"), então view inspect.png: esquerda = a fonte com uma grade rotulada em pixels da fonte (para point_px), direita = o que o extrator de linhas vê. Os rótulos das chamadas também são colocados automaticamente aqui (omitir "label").

Escreva spec.json (veja assets/example_spec_2d.json) e construa:

python3 SKILL_DIR/scripts/blueprint2d.py build IMAGE.png spec.json --out /mnt/user-data/outputs/blueprint.png

Ajuste: "detail" 0.3 (limpo, ousado) a 0.8 (ocupado); "mode": "edges" (Canny, fotos/renderizações) ou "sketch" (XDoG, arte suave/baixo contraste); "bg": "none" para manter o quadro inteiro, ou "mask": "path.png" para uma silhueta feita à mão; "crop": [x0,y0,x1,y1] para isolar o assunto; "fill" 0-1 para a tonalidade translúcida do corpo.

Etapa 3 - Verificar o resultado (não pule, mas mantenha rápido)

O construtor imprime linhas WARNING:. Leia-as primeiro - elas são uma auditoria automática, então você normalmente precisa view o PNG apenas uma vez, no final:

• error: spec is not bound to this model - veja "Lock de especificação" acima; isso é uma falha grave, não um aviso.
• layout: ... - texto da chamada sobrepondo o modelo, dois rótulos sobrepostos, um líder cruzando o texto de outro rótulo / outro líder / seu próprio texto, texto fora do painel, texto na tríade de eixos. Corrija removendo o "label" manual (deixe o posicionador decidir), alterando a âncora ou encurtando o texto.
• description / specs / notes: reduzido para Npx ou NÃO cabe - encurte o texto ou remova linhas em vez de aceitar texto ilegível.

Então view o PNG final uma vez e verifique o que a auditoria não pode saber:

1. Modelo na vertical e voltado para a direção pretendida em todas as vistas; dimensões plausíveis.
2. Cada ponto de chamada realmente cai na parte que seu texto nomeia.
3. A zona segura superior está vazia (uso como papel de parede).

Se algo estiver errado, edite a especificação (âncoras, view.az/view.el, comprimento do texto, feature_deg) e reconstrua; com o cache, isso leva segundos. Total típico: 1 inspeção + 1-2 construções, 2-3 visualizações de imagem.

Etapa 4 - Entregar

Salve em /mnt/user-data/outputs/, chame present_files, então responda brevemente. Na resposta, sempre informe:

• quais textos você inventou (descrições, especificações, observações, funções de chamada) versus o que foi medido do arquivo - o usuário deve substituir reivindicações técnicas inventadas com as quais se importa;
• a suposição de unidades/escala;
• qualquer WARNING ou limitação visível (linhas densas, âncora oculta, proporção).

Mantendo o uso de tokens baixo

• Uma imagem de inspect, uma view final; confie na auditoria impressa em vez de revisar após cada ajuste.
• Use âncoras cand e omita label; não ajuste manualmente coordenadas de pixel.
• Escreva a especificação uma vez, completamente (âncoras, textos), depois construa; edite apenas os campos que a auditoria ou a visualização final sinalizou.

Escrevendo o texto da anotação

• Descreva apenas o que é visível nos renders; mantenha as afirmações funcionais plausíveis e genéricas. Se o objeto é de uma franquia, não afirme detalhes de lore sobre os quais você não tem certeza.
• Títulos das chamadas: 2-4 palavras. Texto da chamada: uma frase curta (cerca de 70 caracteres). Notas: 3-5 itens curtos. Descrição: cerca de 600-700 caracteres. Linhas de especificação: valor abaixo de ~45 caracteres.
• Mantenha o texto técnico e consistente: designação, número de especificação, revisão, unidades.

Referência da especificação

Chaves comuns (ambos os pipelines):

chave	significado	padrão
title	título grande no bloco de título	"UNTITLED"
subtitle	linha abaixo do título	""
designation	linha em negrito no topo da caixa de descrição	""
description	parágrafo para a caixa de descrição	(caixa omitida)
specs	[["Label","Value"], ...] para a tabela de especificações	(omitido)
notes	lista de strings para a caixa de observações (A, B, C...)	(omitido)
notes_title	título dessa caixa	"DESIGN REMARKS" / "NOTES"
callouts	lista de objetos de chamada (abaixo)	nenhum
spec_no, class, rev, sheet, scale	campos do bloco de título (campos vazios são ignorados)	sheet "01 / 01", scale "AS SHOWN"
fields	substituição completa dos campos do bloco de título: [["KEY","value"], ...]	automático
width, height	tamanho da saída em px	1920, 1080
top_safe	y (em 1080p) onde o quadro começa; mantenha a barra da área de trabalho limpa	76
palette	blueprint, graphite, paper	blueprint
scale_ref	`{"axis": "length	height

Apenas 3D: up, front, layout (multi/single), view {"az": 58, "el": 20, "margin": 0.045}, candidates (k usado para cand, padrão 16; deve ser igual a inspect --k), feature_deg (limiar de ângulo de aresta, padrão 38; aumente para 50-60 para menos linhas), feature_deg_small (padrão 44, vistas lateral/superior/frente), max_faces (padrão 700000), cache (padrão true).

Apenas 2D: mode, detail, bg, mask, crop, fill, fit_subject (cortar para o assunto, padrão true), view_title, view_sub.

Objeto de chamada: {"title": "...", "desc": "..."} mais a âncora - 3D: cand / pick / extreme / point; 2D: point_px: [x, y] em pixels da imagem de origem - e opcionalmente "label": [x, y] para forçar uma posição manual.

Solução de problemas

• Modelo lateral / de cabeça para baixo / virado para longe: execute novamente inspect com --up / --front; verifique a linha superior de inspect.png.
• Apenas uma mancha cinza de linhas: aumente feature_deg (50-65); para uma malha muito densa, defina também max_faces mais baixo (precisa de fast-simplification).
• Partes faltando ou buracos transparentes: a malha não é à prova d'água ou tem faces invertidas; o renderizador do algoritmo do pintor tolera isso, mas partes internas de ativos de jogos podem aparecer. Reduza view.margin ou tente um az diferente.
• Muito lento: malhas acima de ~700k faces são decimadas automaticamente se fast-simplification estiver instalado; caso contrário, uma construção pode levar minutos.
• Máscara 2D errada ou fragmentada: a cor do assunto está muito próxima do fundo. Use "bg": "none", um crop ou forneça um PNG de mask (branco = assunto).
• Avisos de texto: encurte o texto; não reduza os tamanhos de fonte manualmente.
• Números de candidatos não correspondem à imagem / spec is not bound to this model: o arquivo do modelo, up/front, o view az/el da especificação ou candidates diferem daqueles para os quais a especificação foi escrita. Reexecute inspect com as configurações da especificação, escolha novamente as âncoras e construa com --relock.
• Posicionamento automático de rótulos continua falhando ("no collision-free position"): muitas chamadas ou muito longas para o painel; encurte as descrições, remova chamadas ou use "layout": "single" para um painel mais largo.
• Saída com aparência desatualizada após editar os scripts: a chave de cache inclui o código do renderizador, mas se estiver em dúvida, execute uma vez com --no-cache.

Arquivos

• scripts/binding.py - lockfile de especificação (lock)
• scripts/blueprint3d.py - pipeline 3D
• scripts/blueprint2d.py - pipeline 2D
• scripts/layout.py - layout compartilhado e renderização de texto
• assets/example_spec_3d.json - especificação 3D de exemplo
• assets/example_spec_2d.json - especificação 2D de exemplo
• scripts/fonts/ - arquivos de fonte DejaVu incluídos