paper-figure

O que paper-figure faz?

Desenhe uma figura de artigo a partir de elementos separados e editáveis, e meça-a no tamanho em que será impressa.

Princípios

• Nenhum modelo de geração de imagens. Você ou o autor desenham cada elemento.
• Entregue a figura como um quadro em um canvas do Claude Design sempre que essa ferramenta estiver disponível. Isso é obrigatório. Crie ou atualize o quadro primeiro, para que o autor possa mover, reestilizar e comentar cada elemento. Nunca termine apenas com um PNG, um PDF ou um arquivo HTML local. Desenhe quadros HTML simples em disco apenas quando a sessão não tiver ferramenta de canvas, e informe isso no relatório (references/drawing-boards.md).
• PDF e PNG são exportações, feitas quando o autor pede ou a figura está finalizada: um PDF vetorial com texto vivo para LaTeX, e um PNG de 300 dpi gerado a partir dele para Word e slides.
• O texto da figura usa exatamente os nomes do corpo do artigo, no idioma do artigo.
• A estrutura é preservada. Você pode alterar formas e layout. Você não pode alterar módulos, conexões ou limites sem perguntar (veja "Ledger estrutural").
• Escolha o veículo alvo antes de desenhar. Veículos divergem: a Nature limita o texto de figuras a 7 pt, a AAAI exige no mínimo 9 pt. Se o autor não escolheu, escolha o veículo típico de sua área e informe no relatório.
• O padrão de qualidade é o de uma figura de veículo de alto nível. Olhe primeiro para figuras de referência, construa candidatos e deixe o autor escolher. Não pare em caixas e setas.
• Diga "passa" ou "sem sobreposição" apenas depois de medir com scripts/figure_audit.py e olhar você mesmo para a renderização. Isso substitui qualquer padrão "não verifique" da superfície de desenho.
• A crítica visual é consultiva. Ela conta mal os elementos e perde conexões. Julgue a estrutura apenas com o ledger e --compare.

Fluxo de Trabalho

1. Leia as fontes: rascunho do artigo, código e a figura original do autor. Leia-as novamente cada vez que o autor disser "refaça".
2. Construa o ledger estrutural.
3. Escreva o briefing e escolha o veículo (references/venues.md).
4. Abra 2–3 figuras de referência e escreva a folha de estilo.
5. Desenhe 2–3 candidatos no canvas que diferem em layout ou vocabulário de formas, não em pequenos ajustes.
6. Audite, olhe, compare, critique. Corrija até que os erros sejam zero.
7. Mostre a folha de comparação. O autor escolhe.
8. Exporte assim que o autor tiver escolhido, coloque a figura no manuscrito e olhe para essa página.

Ledger estrutural (antes de qualquer edição)

Uma figura mostra o sistema que o autor projetou. Extraia cada item abaixo da figura do autor, do artigo e do código em uma tabela.

Tipo	Itens	Fonte
Módulos (caixas)	nomes exatos	figura original / caminho do código / seção do artigo
Conexões (setas)	remetente → destinatário : nome do dado	o código que produz aquele dado
Limites	o que cada sistema, skill ou ferramenta delimita	figura original / código
Estado e recursos	estado compartilhado, orçamentos, modelo compartilhado, corpus, parâmetros aprendidos	figura original / código
Decisões e laços	resultados de decisão, caminhos de feedback e recorrência	função de política / algoritmo
Entradas e saídas	entrada do usuário, saída final, tensores de entrada e saída	figura original / código

Ao desenhar o método de outra pessoa, construa o ledger a partir do algoritmo do artigo original e do código oficial, e cite-os.

• Nada no ledger pode desaparecer, ser renomeado ou se mover através de um limite. Se algo precisar mudar (por exemplo, a figura discorda do código), pergunte ao autor antes de editar.
• Não invente módulos ou setas, e não elimine conexões para simplificar. Anote omissões deliberadas na legenda ou no relatório.
• O layout pode mudar. A direção do fluxo e o conteúdo não.
• Figuras de detalhe dividem a figura geral. Nomes, cores e limites devem corresponder a ela.
• Verifique cada seta contra o código: ela deve sair do módulo que realmente produz aquele dado.
• Após editar, verifique o ledger linha por linha e execute python3 scripts/figure_audit.py NOVA --venue icml --compare ORIGINAL. O script não consegue ver setas não rotuladas; verifique-as contra o ledger manualmente.
• Comece o relatório com "Alterações estruturais: nenhuma" ou a lista de alterações e se o autor as aprovou.

Trabalhando com o autor

• O próprio desenho do autor é a linha de base. Remova e alinhe sobre ele. Não substitua sua estrutura ou estilo por completo.
• Nunca sobrescreva o original. Coloque cada nova versão ao lado dele (Fig2_v2). O autor confirma.
• Se o autor editou o quadro manualmente, releia o arquivo mais recente e trabalhe nele.
• Adicione um tipo de elemento de cada vez. Adicionar painéis de estágio, pílulas e caixas de saída de uma só vez torna a figura muito complicada.
• Mantenha estágios vizinhos como caixas tracejadas com seus nomes reais. Não os exclua nem os reduza a uma seta ou texto cinza.
• Relate apenas o que mudou, por figura. Se encontrar uma incompatibilidade com o artigo ou código, diga isso antes de editar a figura.

Briefing, referências, folha de estilo

Briefing (um por figura)

Função:            visão geral (estrutura + procedimento) / detalhe de estágio / bloco de arquitetura
Tipo de figura:    A pipeline de sistema ou agente / B modelo ou arquitetura
Veículo:           define a largura colocada e o texto em px (references/venues.md)
Mensagem central:  uma linha
Fatos a manter:    o ledger estrutural
Deixar de fora:    números de resultados, frases que pertencem ao corpo, configurações como nomes de modelos

Figuras de referência (2–3)

• Ordem de preferência: o artigo original do método ou repositório oficial; um artigo recente no mesmo veículo com o mesmo tipo de figura; as figuras anteriores do autor.
• Abra cada uma e observe: vocabulário de formas, o que cada cor significa, fontes e notação de variáveis, esqueleto do layout, quantidade de texto, e o que não imitar.
• Apenas convenções. Nunca redesenhe uma figura de referência nem reproduza sua paleta e composição.

Folha de estilo (uma por artigo)

• Todas as figuras de um artigo usam um vocabulário visual: fonte, texto em px, cores e seus significados, formas, larguras de linha e borda, raio de canto, pontas de seta.
• Com scripts/dc_board.py, o dicionário STYLE é a folha de estilo. Altere-o lá, nunca por elemento.

Regras de composição

• Uma caixa contém apenas o nome de uma função. Frases explicativas vão no corpo do texto.
• Uma seta carrega um rótulo com o nome do dado. Não numere dados.
• Nomes de espaço reservado, como A/B/C ou "Para B / De A", não são permitidos. Use os nomes reais do módulo.
• Um limite envolve apenas a parte que realmente realiza aquele trabalho.
• O texto da caixa são palavras-chave: sem frases, nada acima de 15 palavras, sem texto do corpo copiado, sem listas de equações. Um pequeno exemplo de dado é a exceção.
• Sem badges de número de etapa nos estágios. Sem título dentro da figura; o título é a legenda.
• Uma visão geral mostra estrutura e procedimento juntos: entrada → processo → saída lê-se da esquerda para a direita em poucos segundos, laços de realimentação são tracejados e a saída é claramente visível.
• Execute um exemplo trabalhado por todas as figuras de detalhe, como pequenas fichas dentro das caixas.
• Considere mesclar visão geral e detalhe em painéis a e b de uma figura (empilhados ou linhas de zoom macro-micro). Construa ambos como candidatos.
• Quando as regras entrarem em conflito, decida nesta ordem: relações e direção correspondem ao código e artigo → fluxo lê-se em segundos → legível no tamanho de impressão → alinhamento → aparência.

Vocabulário de formas, fontes, cores e linhas: references/style.md. Escolha o vocabulário A (pipelines de sistema: cartões de ícone, fichas, painéis) ou B (arquiteturas: forma indica tipo) e não os misture em um artigo.

Tamanho

Texto impresso (pt) = texto em px × largura colocada (pt) ÷ largura do quadro (px). O mesmo quadro imprime em tamanhos diferentes em veículos diferentes, portanto meça novamente sempre que o veículo mudar. Predefinições e tamanhos em px: references/venues.md.

• Mantenha os tamanhos de texto quase uniformes em uma figura. Não encolha algum texto para fazê-lo caber: mova o texto para a legenda, aumente a caixa ou o quadro, quebre a linha ou divida a figura.
• O texto não pode sair de sua caixa nem ficar a menos de 6 px da borda.
• Cinco ou mais caixas em uma linha ficam sem largura: quebre títulos em 2–3 linhas, depois vá para duas linhas.
• Uma figura larga vai na largura total do texto (figure*). Em uma coluna, seu texto se reduz pela metade.
• Com vários painéis, alinhe as linhas exatamente ou separe-as por 7 px ou mais.

Ciclo de auditoria

Configuração: pip install playwright numpy pillow && python3 -m playwright install chromium (poppler-utils habilita a verificação de PDF).

python3 scripts/figure_audit.py project/Fig2.dc.html --venue icml --png fig2.png     # medir + renderizar
python3 scripts/figure_audit.py project/Fig2.dc.html --venue nature --column         # figura de uma coluna
python3 scripts/figure_audit.py project/Fig2.dc.html --placed-mm 165 --min-pt 8      # veículo sem predefinição
python3 scripts/figure_audit.py project/Fig2.dc.html --venue icml --cvd fig2         # cinza + daltônico
python3 scripts/figure_audit.py project/Fig2_v2.dc.html --venue icml --compare project/Fig2.dc.html   # rótulos mantidos?

1. Corrija até ERROR ser 0: texto abaixo ou acima dos limites, texto fora de sua caixa, texto sobreposto, texto fora do canvas, um rótulo ausente do original. Para cada WARN (texto grudado na borda, texto cruzando uma linha, glifos de fallback, texto sobre cinza, linhas abaixo do mínimo, alinhamento quase perfeito), dê zoom na renderização e decida.
2. Olhe para a renderização no tamanho colocado e para as três imagens --cvd.
3. Verifique setas e rótulos contra o ledger, o código e o artigo novamente.
4. Pontue com a tabela de crítica e compare com as figuras de referência.
5. Mantenha o arquivo anterior a cada rodada e registre apenas o que mudou.

Ordem de correção (evita retrabalho): canvas e margens → regiões grandes e ordem de empilhamento → tamanhos das formas → preenchimentos e bordas → pontos finais dos conectores → texto → decoração.

Pronto significa todos os três: a auditoria passa, você olhou no tamanho colocado e a crítica ultrapassa a nota de aprovação. Uma auditoria aprovada por si só não é suficiente. Se problemas persistirem após cinco rodadas, o layout em si está errado: informe o autor e decidam juntos.

Candidatos e crítica

Faça 2–3 quadros com a mesma estrutura e um layout ou vocabulário diferente (painéis a/b versus linhas de zoom, esquerda para direita versus de baixo para cima, vocabulário A versus B). Empilhe os candidatos e as figuras de referência em uma imagem e mostre-a:

from PIL import Image
ims = [Image.open(p).convert("RGB") for p in ["vA.png", "vB.png", "ref.png"]]
W = 1584; ims = [im.resize((W, round(im.size[1] * W / im.size[0]))) for im in ims]
folha = Image.new("RGB", (W, sum(im.size[1] + 30 for im in ims)), "white"); y = 0
for im in ims: folha.paste(im, (0, y)); y += im.size[1] + 30
folha.save("folha_comparacao.png")

Pontue cada dimensão de 0 a 2,5 (total 10). Qualquer veto define aquela dimensão como 0.

Dimensão	Significado	Veto
Fidelidade	mostra o método dentro do escopo da legenda; simplificação razoável é aceitável	módulo ou conexão inventados, fluxo invertido, conexão necessária ausente, fora do escopo, texto quebrado ou fórmulas falsas
Concisão	um resumo visual com alta relação sinal-ruído	frases em caixas (acima de 15 palavras), texto do corpo copiado, listas de equações
Legibilidade	fluxo à primeira vista, texto legível	título ou legenda dentro da figura, rótulos redundantes, sobreposições, texto minúsculo ou irregular, fluxo emaranhado
Estética	polimento de veículo de alto nível	artefatos de grade, formas quebradas, cores neon ou conflitantes, clip art, fontes misturadas, desalinhamento, fundo preto

Notas de aprovação: revista 8,5, conferência 8,0, tese 8,0, pôster 7,0, slides 6,5. Para cada dimensão, escreva também "melhor / igual / pior que a referência" com uma linha de raciocínio.

Exportação

python3 scripts/dc_export.py <raiz> Fig2.dc.html --out paperfigs --venue icml

• Escreve Fig2.pdf (vetorial, tamanho do quadro) e Fig2.png (300 dpi na largura colocada).
• A verificação de PDF deve passar: todas as fontes embutidas, nenhuma fonte Type 3, nenhuma imagem raster. Se falhar, corrija a lista de fontes primeiro (references/style.md).
• LaTeX: \includegraphics[width=\textwidth]{figures/fig2.pdf} dentro de figure*. Não encolha com \resizebox ou scale=. Figuras de uma coluna usam figure e \columnwidth.
• Word e slides: insira o PNG na largura da figura e, em seguida, verifique essa página quanto a sobreposições e quebras de página.
• Faça backup da figura anterior antes de substituí-la no manuscrito e substitua apenas após a decisão do autor.
• Legendas seguem o modelo do veículo. Informe na legenda o que os símbolos de exemplo significam, o que foi omitido deliberadamente e que um exemplo é ilustrativo.

Nunca

• Adicione, remova ou renomeie um módulo, conexão ou limite sem a confirmação do autor.
• Use um modelo de geração de imagens, entregue uma figura final apenas em bitmap ou copie uma figura de referência.
• Termine apenas com um PNG, PDF ou arquivo local quando uma ferramenta de canvas estiver disponível.
• Coloque números de resultados em uma figura de método, ou varie regras de cores, tamanho de texto ou vocabulário entre figuras de um mesmo artigo.
• Coloque texto sobre cinza, use bordas CSS com px fracionário ou envie um PDF com fontes Type 3.
• Sobrescreva o original do autor, troque uma figura no manuscrito sem permissão ou escolha o candidato para o autor.
• Afirme "legível" ou "sem sobreposição" sem medir.

Arquivos

Arquivo	Uso
scripts/dc_board.py	constrói quadros a partir de Python curto: cartões, cartões de ícone, trapézios, círculos de operação, tensores, painéis, setas
scripts/figure_audit.py	mede uma figura no tamanho de impressão; --venue, --compare, --cvd
scripts/dc_export.py	quadro → PDF vetorial + PNG de 300 dpi, com verificação de fontes e raster do PDF
references/venues.md	predefinições de veículos: larguras, regras declaradas, menor texto em px
references/style.md	vocabulários de formas A e B, fontes, cores, linhas, densidade
references/drawing-boards.md	desenho em canvas Claude Design ou como quadros HTML simples; chamadas a dc_board.py; notas sobre TikZ
references/credits.md	fontes dos procedimentos emprestados e suas licenças
examples/	figuras executáveis que passam na auditoria: react-agent (vocabulário A), transformer-block (vocabulário B), rag-pipeline (mínimo)