sketch-to-photoreal-render

Sketch to photoreal render

Transforme um desenho arquitetônico — esboço à mão, elevação, exportação do SketchUp ou Revit, planta colorida de terreno, folha PDF — em uma imagem que parece ter sido fotografada com uma DSLR full-frame, mantendo o design exatamente como desenhado. O Gemini faz os pixels (gemini-3-pro-image, legado generateContent). Seu trabalho é tudo em torno dessa chamada: ler o desenho, escrever o briefing, controlar os gastos e verificar cada resultado contra sua fonte antes de entregar.

scripts/render.py faz a mecânica, uma chamada de modelo por passada: ele faz edge-extend da fonte para a mais próxima das dez proporções que o modelo oferece (para que o modelo nunca seja solicitado a recompor), renderiza nessa proporção, recorta o retângulo original da fonte de volta, sinaliza qualquer re-enquadramento e escreve uma folha de comparação antes/depois. Os caminhos abaixo são relativos à pasta deste skill; chame o script pelo caminho absoluto, com o Python que render.py check aprovar.

Onde isso é executado

A renderização ao vivo precisa do Claude Code na própria máquina do usuário, com GOOGLE_API_KEY definida lá. Se você não tiver um shell local ou sistema de arquivos — chat do claude.ai, contêiner de skills da API Claude — diga claramente: você pode ler o desenho, escrever o briefing e, se Python e Pillow estiverem presentes, mostrar um prompt --prompt-only, mas não pode renderizar. Nunca se ofereça para pegar a chave.

A política vigente — cite-a, nunca parafraseie

A política de renderização do usuário, fornecida em 28 de agosto de 2026:

Tarefa: Renderizar a imagem de entrada em qualidade 1K primeiro para reduzir custos.

• Manter geometria, escala e proporção 100% precisas.
• Sem alucinação, sem adição/remoção de elementos a menos que instruído explicitamente.
• Substituir materiais por acabamentos reais (por exemplo, telhados de terracota, árvores realistas, piscinas, paisagens).
• A saída deve parecer fotografia arquitetônica DSLR de alto nível.
• Todas as edições e revisões devem permanecer em qualidade 1K até confirmação.

Uma vez aprovado, amplie a mesma imagem para qualidade 4K:

• Entregue precisão nítida e detalhada, sem desfoque ou mancha.
• Cada elemento deve parecer real e fotorrealista ao ampliar.
• Preserve a geometria exata e a fidelidade dos detalhes da imagem de referência.

Regra final: Sempre renderize edições em 1K primeiro, depois melhore para 4K somente após confirmação explícita.

O requisito de folha de comparação do usuário, fornecido em 31 de agosto de 2026:

em todas as renderizações futuras, após cada renderização quero folha de comparação para verificar cruzadamente. atualizar em todos os lugares.

Se você reafirmar qualquer um dos dois, cite-o. Valores de custo e contexto: references/policy.md.

Portões rígidos

1. Pergunte antes de gastar. Antes de qualquer chamada faturada, informe ao usuário a contagem de imagens, o nível e o custo, e aguarde um sim explícito. Só então adicione --spend-ok. O script impõe isso: sem --spend-ok ele imprime a estimativa e sai com código 3 sem ler a chave. Um sim cobre exatamente o que você cotou; cada revisão, correção ou reexecução posterior de uma passada com falha é um novo gasto, então cotar (uma imagem, 1K, até USD 0,268) e obter um sim novamente. Você pode colocar o plano e o preço em uma mensagem ("Próximo: revisar vista 02 para corrigir a cor do telhado — 1 imagem em 1K, até USD 0,268. Posso prosseguir?"). As cotações são pela taxa de imagem; o Google também fatura a imagem de entrada de cada tentativa (cerca de USD 0,0011), o texto do prompt e os tokens de pensamento do modelo, então diga que a cobrança real é ligeiramente superior à cotação.
2. 4K é por imagem, após aprovação. Execute upscale --confirmed apenas para uma imagem que o usuário tenha visto em sua folha de comparação e aprovado pelo nome. "Parece bom" em um conjunto não é aprovação para levar o conjunto para 4K, e "deixe mais nítido" não é aprovação para re-renderizar em 4K — pergunte qual imagem única. Cote como qualquer gasto: o nome do arquivo, 1 imagem, 4K, até 2 tentativas, máx. USD 0,48 (USD 0,24 por tentativa).
3. Nunca itere em 4K. Corrija tudo em 1K primeiro; a passada 4K reproduz falhas fielmente. Um arquivo 4K é final e nunca é revisado.
4. Toda passada entrega sua folha, e você a revisa primeiro. Após cada passada, abra a imagem da folha com a ferramenta Read e revise-a com references/review-checklist.md. Decida um veredito (match / minor / major) com os problemas que você vê, depois entregue a renderização, a folha e o que a folha mostra. Uma renderização sem sua folha não está concluída.
5. Nunca sobrescreva e nunca escreva dentro da pasta deste skill. O script nunca reutiliza um nome de arquivo e recusa uma pasta de saída dentro do skill; não mova, renomeie ou substitua arquivos ou fontes entregues por conta própria.
6. Nunca manuseie a chave da API no chat. Não a peça, aceite, imprima ou escreva em um arquivo. Se um usuário colar uma, diga que agora ela está exposta no chat, que eles devem excluí-la e recriá-la no AI Studio, e como definir a nova como uma variável de ambiente. Prefira a variável de ambiente do usuário a um arquivo .env, e nunca coloque um .env em uma pasta de skill que seja copiada, compactada ou enviada.
7. Diga uma vez por projeto, antes da primeira chamada ao vivo, que o desenho é enviado para a API Gemini do Google (generativelanguage.googleapis.com) para ser renderizado. Desenhos de clientes são confidenciais; obtenha a autorização do usuário.
8. Cada repetição é faturada, incluindo tentativas que não retornam imagem. Corrija o prompt; nunca aumente --attempts para resgatar uma tentativa ruim (o script limita a 3).

O que este skill não pode fazer

O pipeline mantém a câmera do próprio desenho. Ele não pode mostrar outro lado do edifício, um novo ângulo, um zoom, um corte ou uma proporção diferente, e não pode transformar uma planta baixa em perspectiva ou vista ao nível dos olhos: na árvore, uma planta enviada como imagem voltou como uma casa diferente, e movimentos de câmera apenas com prompt deram uma vila diferente a cada vez (references/art-direction.md seção 13). Quando o usuário pedir algo assim, não gaste: explique e peça uma nova exportação dessa vista do modelo 3D, depois renderize essa exportação como um novo trabalho. Nunca coloque alterações de câmera ou enquadramento em notas de revise ou patch; o script imprime !! CAMERA / FRAMING WORDS se você fizer isso.

Ele também não apaga rótulos, registra painéis, une aéreos íngremes ou compõe placas de fundo, o que a árvore fazia ao redor de suas renderizações (references/failure-modes.md). Onde esses eram o que funcionava, avise o usuário antes de gastar que apenas o texto pode não ser suficiente.

Verificação de configuração (uma vez por máquina)

Execute python scripts/render.py check. Ele imprime as versões do Python, Pillow e PyMuPDF, a fonte da folha, o ID do modelo e onde a chave foi encontrada (apenas a fonte, nunca o valor); sem chave, imprime as etapas para definir uma. Se falhar em uma importação, execute python -m pip install -r scripts/requirements.txt com esse Python. Com uma chave no lugar, check --online faz a chamada de metadados gratuita models.get para provar que a chave e o modelo funcionam; nunca é faturado.

Fluxo de trabalho para uma vista

1. Recepção

Obtenha do usuário: o arquivo como um caminho no disco (uma imagem colada não tem caminho — pergunte onde o arquivo está), um nome de vista e notas em quatro campos — materiais, iluminação, ambiente, outros (cada um opcional). Pergunte sobre qualquer coisa que o desenho deixe em aberto e que mudaria a imagem (esta área plana é gramado ou pavimento? de onde vem o sol?) em vez de adivinhar. Faça a triagem da entrada:

• Uma folha com vários painéis (pisos, elevações), ou um PDF cuja vista não está na página 1: peça para exportar um painel ou página, ou recorte você mesmo em um novo arquivo em uma pasta ... Input, uma vista por trabalho. Diga ao usuário que a folha de comparação pareia esse painel com sua renderização. Layouts densos de móveis falharam generativamente na árvore; diga isso antes de gastar.
• Uma solicitação que o pipeline não pode atender (veja acima): pare e explique antes de qualquer gasto.
• Uma folha com carimbo, quadro de áreas, rótulos ou linhas de limite estatutário: estes devem permanecer exatamente como desenhados, e o modelo não consegue manter texto (o briefing proíbe). Peça para recortá-los antes da renderização e colocá-los de volta inalterados na folha final fora da renderização; nomeie qualquer linha estatutária em uma precaução para que não seja transformada em parede ou apagada.
• Uma solicitação que contradiz o desenho (um telhado plano onde um telhado de quatro águas é desenhado): aponte e pergunte. A política mantém a geometria como desenhada, a menos que o usuário diga explicitamente o contrário.

2. Leia o desenho e escreva o briefing

Execute uma passada gratuita --prompt-only primeiro, sempre com --out (fora desta pasta do skill; para assets/test_sketch.png, uma pasta temporária): ela rasteriza a página 1 de um PDF e escreve a alimentação preenchida em <out>/_work/prompt-only/<view>_<tier>_padded.jpg (no máximo 2400 px), o arquivo mais fácil de visualizar. Abra-o com a ferramenta Read e estude-o. Em seguida, escreva o JSON do briefing seguindo references/art-direction.md:

{"elements": ["bloco de dois andares, telhado de quatro águas, metade esquerda do quadro", "..."],
 "finishes": ["paredes de gesso cal off-white quente", "..."],
 "cautions": ["ENQUADRAMENTO: vila ocupa 20-78%% da largura, beirado a 37%% de altura; se crescer, re-centralizar ou adicionar céu, o resultado falhou", "..."]}

• elements: cada elemento do edifício, abertura, forma do telhado, nível, guarda-corpo, piscina, área pavimentada, massa de plantio e item de mobiliário, com sua posição e sua contagem (máx. 30 itens, 160 caracteres).
• finishes: os materiais reais (máx. 15, 120 caracteres).
• cautions: a âncora de enquadramento mensurável PRIMEIRO, com seu teste "o resultado falhou se ..."; depois contagens de andares, artefatos de desenho que não são objetos e negativos específicos deste quadro (máx. 10, 160 caracteres).

Mantenha o briefing curto — briefings longos perderam enquadramento na árvore. Salve-o ao lado do trabalho, por exemplo, <out>/_briefs/<view>.json. Texto mais longo de material ou configuração pertence a --materials / --environment (as notas podem totalizar 4000 caracteres).

3. Escolha os sinalizadores

• Telhados não são de terracota (lajes planas, membrana, ardósia, metal, telhado verde)? Adicione --no-terracotta-example, coloque uma precaução de telhado no briefing ("todos os telhados são planos — sem telhas, sem inclinação, sem terracota", ou "o telhado da ala é uma laje plana — sem telhas, sem inclinação") e nomeie o acabamento real do telhado. O briefing de fidelidade compartilhada usa terracota como exemplo de acabamento e adicionou telhados de telha vermelha a vilas de telhado plano; o sinalizador remove esse exemplo positivo. Uma precaução ainda pode nomear terracota como negativo.
• O nível padrão é 1K. Sugira --size 2K (mesmo preço de tabela) apenas quando elementos-chave teriam menos de cerca de 20 px de largura em 1K, como em uma aérea de grande propriedade, e use-o somente após o usuário concordar; 4K nunca é um nível de rascunho.
• A entrada é uma cópia preparada (linhas de eixo limpas, rótulos apagados, um vazio branco pré-preenchido)? Passe a exportação intocada como --original FILE para que a folha pareie o original verdadeiro.
• --out assume como padrão uma pasta 03 Output irmã quando a entrada está em uma pasta ... Input, caso contrário <pasta de entrada>/03 Output; nunca pode estar dentro da pasta deste skill.

4. Audite o prompt (gratuito)

Re-execute com o briefing e notas e --prompt-only, leia o prompt impresso e verifique se nada nele pede um elemento que o desenho não possui.

5. Estime, pergunte, renderize

Execute o comando sem qualquer sinalizador de portão para obter a estimativa (código de saída 3), cotar para o usuário e aguardar um sim. Em seguida, execute novamente com --spend-ok. Uma chamada ao vivo geralmente leva de 20 a 60 segundos, mas uma tentativa pode esperar até 15 minutos, mais do que uma chamada Bash em primeiro plano: execute passadas ao vivo em segundo plano (run_in_background) e aguarde-as. Se um comando ao vivo for interrompido, execute render.py status, relate a passada interrompida como possivelmente faturada e pergunte antes de qualquer nova execução. Várias vistas: cote o total do lote (vistas x 1K x até 2 tentativas) e obtenha um sim para o lote, depois execute as vistas uma após a outra.

6. Revise a folha

Abra <out>/_Before After - <view>_1K.jpg com a ferramenta Read. Siga references/review-checklist.md: enquadramento e proporções, contagens, aberturas, forma do telhado, andares, objetos adicionados ou ausentes, texto, materiais, realismo. Uma nota laranja "aspecto a -> b (enquadramento alterado)", ou uma linha WARNING do script, significa que o modelo re-enquadrou: essa renderização não pode ser revisada ou aprovada, então renderize novamente a partir da fonte com uma âncora de enquadramento mais forte e uma precaução nomeando exatamente o que a passada com falha fez ("TENTATIVA ANTERIOR FALHOU: ..."). Se duas renderizações 1K de uma vista re-enquadrarem, pare e relate em vez de re-tentar. Abra a própria renderização quando a folha for muito pequena para julgar um detalhe.

7. Relate

Dê ao usuário: o caminho da renderização, o caminho da folha, seu veredito com os problemas encontrados, o custo (render.py status mostra) e as escolhas — aprovar esta imagem para 4K, revisar uma coisa, corrigir uma região ou renderizar novamente a partir da fonte.

Loop de revisão (permanece em 1K)

revise "<renderização atual>" --notes "<uma alteração>". Regras:

• Uma alteração por passada. Várias alterações em uma edição tendem a regenerar o quadro inteiro.
• Descreva o estado alvo do objeto, não a correção ("a porta de entrada é de madeira bronze quente sólida com duas barras de puxar verticais", não "consertar a porta"). Aumente o zoom na renderização antes de escrever: uma recolorização não é uma adição.
• O "antes" é a imagem que está sendo revisada; a folha a pareia com o novo arquivo (BEFORE · <view>_1K / AFTER · <view>_1K_rev02).
• Apenas o arquivo atual (a passada não 4K mais recente do trabalho) pode ser revisado; o script o nomeia se você escolher outro. Uma revisão de uma renderização 2K é feita em 1K e nomeada _1K_revNN.
• Quando a composição em si estiver errada (câmera movida, assunto cresceu, aviso de re-enquadramento), não revise: execute render novamente a partir da fonte com um briefing melhor.

Patch (correção local, permanece em 1K)

patch "<renderização atual>" --box x0,y0,x1,y1 --notes "<a alteração>" com a caixa como frações do quadro (0,0 canto superior esquerdo). A caixa é recortada, editada em 1K completo, redimensionada de volta e colada com uma pena de 36 px nas bordas dentro do quadro; todo pixel fora da caixa permanece byte-idêntico. Use para um objeto ou uma área (uma parede inventada, uma planta errada, uma porta). Diga o que deve mudar e que deve estar claramente visível; não diga para manter exatamente o que você deseja alterar. Cada lado da caixa deve ter pelo menos 72 px.

4K (uma imagem aprovada)

Quando o usuário confirmar uma única imagem, execute upscale "<caminho da imagem>" --confirmed. Mostre a estimativa e aguarde o sinal verde. Após a conclusão, entregue o resultado ampliado, a folha (se houver — o script a produz se --always-sheet for dado) e o custo. Um upsell para 4K nunca é revisado — se o usuário quiser uma alteração, volte para a versão 1K final, revise e depois amplie novamente.

Múltiplas vistas em um lote

Cada vista é um trabalho independente: desenho, briefing, portão de gasto, renderização, folha, relatório. O lote é cotado como "3 vistas, cada uma 1 imagem em 1K com até 2 tentativas = até 3 x USD 0,268". Se a cotação custar o mesmo que executar uma por uma, execute-as todas por trás: "Vou renderizar as três vistas em sequência." Quando uma falha (re-enquadramento, erro do modelo, nenhuma imagem), termine as outras e depois relate o lote: três resultados, explicação de cada falha, uma solicitação para re-renderizar o trabalho com falha.

Desenhos revisados e PDFs grandes

Uma "revisão" de um desenho que já foi renderizado não é uma revisão do arquivo de saída: é um novo trabalho a partir da fonte atualizada. Trate-o como uma nova vista ("rev 02 da elevação frontal, a partir do PDF revisado"), com seu próprio briefing e portão de gasto — cotação completa. Para PDFs com várias páginas, especifique a página e o zoom: o script lê apenas a página 1 a menos que você use --zoom-at para extrair um retângulo de coordenadas de uma página nomeada. Se o conteúdo não estiver na página 1, extraia uma imagem da página relevante primeiro.

Referências

• references/policy.md — notas de custo, árvore de decisão de gasto, valores de modelo
• references/art-direction.md — guia de briefing, precauções de enquadramento, resumo de idioma, exemplos de prompt e respostas ruins
• references/review-checklist.md — lista de verificação de revisão renderização a renderização
• references/failure-modes.md — modos de falha conhecidos: mantenção de texto, layouts de móveis, aéreos, látex, múltiplas vistas