szcharlesji/tikz-dl-visualizer

Visualizador TikZ de deep learning

Você está desenhando para um aluno que já conhece os fundamentos (MLPs, backpropagation, CNNs, o que é um transformer) e quer entender o porquê. Uma boa figura aqui não é um diagrama decorado de caixas; ela torna uma ideia óbvia à primeira vista e recompensa um segundo olhar. O estilo segue o livro de Deep Learning de Alfredo Canziani, da NYU: fundo cinza escuro, pastéis ColorBrewer Set3 e cores que sempre significam a mesma coisa.

Tudo que você precisa está incluído:

• assets/dlviz.sty: paleta (escura e clara), macros de notação, estilos de nós, aparência do pgfplots, auxiliares. Sempre construa sobre ele em vez de reestilizar do zero; é isso que mantém cada figura em uma linguagem visual única.
• assets/examples/*.tex (com uma prévia .png de cada um): seis figuras compiladas e revisadas, uma por arquétipo. Veja o PNG para entender a qualidade desejada. Comece pelo mais próximo.
• scripts/render.py: compila para PDF e PNG e exibe apenas o primeiro erro.
• references/visual-language.md: papéis das cores, vocabulário de elementos, notação, tipografia e regras de layout. Leia antes de fazer sua primeira figura em uma sessão.
• references/archetypes.md: qual figura se encaixa em qual conceito, mais uma tabela de fatos de DL que as figuras comumente erram. Leia a linha do seu conceito.
• references/tikz-gotchas.md: erros de compilação e armadilhas de layout que encontramos, com correções. Leia quando algo não compilar ou parecer estranho.

Fluxo de trabalho

1. Encontre a única ideia

Antes de tocar no TikZ, escreva em uma frase o insight que a figura deve transmitir, formulado como algo que o aluno verá, por exemplo:

• "Cada linha de saída da atenção é uma média ponderada das linhas de valor, e os pesos são uma linha de uma matriz de scores softmax."
• "O momentum cancela o componente oscilante do gradiente e acumula o consistente."
• "Um bloco residual só precisa aprender a correção F(x), porque x é passado diretamente."

Se você não consegue escrever essa frase, ainda não sabe o que desenhar. Pergunte a si mesmo qual é o equívoco mais provável do aluno e direcione a figura para ele. Se o conceito for amplo (ex.: "transformers"), escolha a única fatia mais esclarecedora e diga isso; ofereça uma figura complementar para o resto, em vez de amontoar tudo em uma só.

2. Escolha o arquétipo

Abra references/archetypes.md e escolha a forma visual que torna a frase visível. Os principais:

Arquétipo	Mostra	Arquivo de exemplo
pipeline / grafo de computação	como os dados fluem, o que alimenta o quê	autoencoder.tex
layout de matriz / heatmap	formas e produtos de tensores, pesos	attention.tex
grade + campo receptivo	operações locais, deslizantes e compartilhadas	convolution.tex
geometria do espaço de parâmetros	caminhos de otimização, contornos de perda	momentum.tex
múltiplos pequenos de gráficos	comparar funções ou configurações	activations.tex
deformação do espaço antes/depois	o que uma camada faz ao espaço de entrada	linear-map.tex

Combinar dois arquétipos é aceitável (um pipeline com um pequeno inset de heatmap), mas um deles deve dominar.

3. Torne-o concreto

Abstração é inimiga da intuição. Use tamanhos pequenos e específicos (4 tokens, d_k = 3, uma entrada 5x5, parâmetros 2-D) e diga o que eles representam. Números reais são melhores que placeholders: pesos que somam 1, uma convolução cuja saída você pode verificar, uma trajetória que é realmente o que o otimizador faz.

Calcule números em Python, nunca manualmente ou de cabeça. Execute um pequeno script (numpy via uv run --with numpy python - ou Python puro), depois cole as coordenadas ou valores no .tex. Deixe um comentário dizendo como foram produzidos. Números "ilustrativos" feitos à mão são a origem de figuras erradas: uma linha de softmax que soma 1,1, uma saída de convolução que não corresponde à sua entrada.

4. Escreva a figura

Crie <concepto>.tex na pasta de saída (a pasta do usuário, se ele nomeou uma, CASO CONTRÁRIO, o diretório de trabalho atual) começando por:

% Legenda: <2-3 frases: o que olhar e o que mostra>
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}   % [light] para artigos / slides brancos
\begin{document}
\begin{tikzpicture}
  ...
\end{tikzpicture}
\end{document}

Escolha o tema de onde a figura será inserida: escuro (aparência do livro) para slides, telas e qualquer coisa que o usuário diga que deve combinar com o livro; claro para destinos como papel (artigos, teses, PDFs de notas de aula, trabalhos, impressão) ou quando solicitado. Se nada der uma dica, use escuro e mencione [light]. Os papéis das cores valem em ambos os temas, então alternar é uma palavra.

Princípios mais importantes (detalhes em references/visual-language.md):

• Cor = função, consistentemente. Entrada x rosa, oculta h verde, predição ỹ violeta, alvo y azul, latente z laranja, custo/perda/energia vermelho, codificador lavanda, decodificador aqua, preditor amarelo, parâmetros dourado. Use a mesma cor para um símbolo no desenho, nos rótulos e na equação (\pink{\vx}). Isso permite que o olho ligue figura e matemática sem ler. No máximo ~5 matizes por figura; tudo que é estrutural é branco/cinza.
• Contraste precisa de dois matizes. Quando a figura compara duas condições (simples vs residual, SGD vs momentum, BatchNorm vs LayerNorm), dê a cada uma seu próprio matiz e use esses matizes para as curvas, rótulos e destaques daquela condição em toda a figura. Não desenhe ambas em vermelho só porque ambas são gradientes; vermelho então marca a coisa compartilhada (a perda, a direção backward), e a comparação permanece legível à primeira vista.
• Torne a magnitude visível. Se uma quantidade cresce ou diminui (norma do gradiente, peso da atenção, variância), codifique-a no próprio desenho, não apenas em um número impresso: largura de linha que afina passo a passo, tom de preenchimento, comprimento da seta, tamanho do ponto. Correspondência também merece tinta: linhas finas de cada amostra até onde ela cai mostram uma transformação melhor que duas nuvens separadas.
• Mostre a matemática, codificada por cores. Coloque a equação definidora na figura, geralmente abaixo, com cada termo colorido como sua contraparte visual.
• Formas em tudo. Rotule tensores com sua forma no estilo dim suave (\(\R^{n\times d_k}\)). A contabilidade de formas é metade da compreensão de uma operação de DL.
• Siga um exemplo do início ao fim. Destaque uma linha, um patch ou uma etapa (estilo hl, contorno vermelho) em todos os lugares onde aparece, para que o aluno possa rastrear uma única computação do início ao fim.
• Anote com moderação e no lugar. Duas ou três notas curtas em itálico (annot) com linhas guias finas, ao lado do que explicam. Rótulos diretos em vez de caixa de legenda. Sem título geral (a legenda faz isso), mas figuras com vários painéis recebem rótulos curtos como "(a) simples: (\vx_l = F_l(\vx_{l-1}))" no estilo annot, com espaço claro acima de cada painel.
• Mínimo de tinta. Sem sombras, gradientes, 3D por si só ou ícones decorativos. Preenchimentos são tons claros da cor do traço (cell=colorX faz isso).
• Notação padrão. Vetores minúsculos em negrito, matrizes maiúsculas em negrito, escalares simples; use as macros (\vx, \mW, \vytld, \softmax). As convenções de linha versus coluna devem corresponder à equação que você imprime (atenção usa Q, K, V por linha por token, como em Vaswani et al.).

5. Compile e olhe para ela

python <caminho-do-skill>/scripts/render.py caminho/para/conceito.tex

Isso copia dlviz.sty para junto da figura para que a pasta possa ser recompilada em qualquer lugar, depois escreve conceito.pdf e conceito.png. Se a compilação falhar, exibe o primeiro erro; verifique references/tikz-gotchas.md. Se faltar um pacote, exibe o comando tlmgr; avise o usuário em vez de executar instalações na máquina dele sem perguntar.

Depois, abra o PNG e critique como um revisor. Compilar não é o fim; toda figura em assets/examples precisou de pelo menos uma rodada de correções após a visualização. Verifique:

1. Algo se sobrepõe ou toca: texto sobre linhas, setas através de rótulos, texto tocando a borda de um nó, rótulos cortados na borda de um eixo ou painel, notas de um painel apertando o rótulo do próximo? Dê zoom em áreas densas (corte o PNG com magick in.png -crop LxA+X+Y out.png) em vez de confiar em uma miniatura.
2. Você consegue ver a única ideia em três segundos? Onde o olho pousa primeiro? É a coisa certa?
3. Cada cor está fazendo um trabalho, e cada função está colorida da mesma forma em todos os lugares?
4. Cada número, forma e fórmula está correto (veja a tabela de fatos em references/archetypes.md)?
5. O espaçamento é uniforme e o alinhamento é intencional?

Corrija e recompile até que todas as respostas sejam sim. Duas ou três iterações é normal.

6. Entregue

Dê ao usuário:

1. O PNG, exibido inline se você puder exibir ou enviar arquivos, mais os caminhos para os arquivos .tex, .pdf e dlviz.sty.
2. Um guia de leitura: 4-8 frases que guiam o olho pela figura na ordem em que deve ser lida ("Comece na linha destacada de Q..."), conectando cada elemento visual à matemática e terminando com a conclusão. Escreva para um aluno intermediário: não reexplique o que é um neurônio, mas explique por que o mecanismo funciona.
3. Uma linha sobre como adaptá-la: mudar para [light], alterar tamanhos ou uma figura complementar natural (ex.: "versão multi-head a seguir?").

Mantenha o comentário % Legenda: no topo do .tex sincronizado com a figura; é a legenda que o usuário colará abaixo dela em seu documento.

Skills irmãos

Este skill produz figuras estáticas: um PDF/PNG por ideia, para slides, artigos e impressão. Dois irmãos compartilham o mesmo dlviz.sty e linguagem visual:

• tikz-live: o mesmo tipo de figura, mas interativa (arrastar, deslizar, passar o mouse, reproduzir) como uma página web autônoma. Use quando o leitor deve mudar algo e ver o mecanismo responder, ou quando o usuário pedir uma figura interativa, explorável ou animada no navegador.
• tikz-explorer-book: um livro web completo de um curso ou campo, com um mapa conceitual e capítulos de figuras; ele usa este skill para figuras estáticas e o tikz-live para as figuras interativas.

Quando o pedido for incomum

• O próprio documento LaTeX ou preâmbulo do usuário. Combine sua notação e cores se ele as tiver; você ainda pode \input os estilos de dlviz.sty ou copiar apenas as partes que ele precisa. Não substitua a cor da página dele.
• Slides (Beamer). Produza a figura standalone e mostre o uso de \includegraphics; para construções passo a passo, coloque \only<n> / \visible<n> nas camadas, ou crie vários arquivos standalone (passo-1, passo-2...).
• Animação ou um processo ao longo do tempo. Para impressão e slides, prefira múltiplos pequenos (t = 0, 1, 2, ..., T) em uma figura; uma sequência de painéis mostra a tendência que uma animação esconde. Se for lido na tela e o leitor deve percorrer ou passar por ele, use o tikz-live.
• PowerPoint / Keynote. Insira o PNG (renderizado a 200 dpi, nítido na largura total do slide) ou o PDF; para um modelo de slide branco, use [light].
• Figura de artigo. Use [light], remova a equação dentro da figura se o artigo já a declara, e mantenha as fontes do artigo (nenhum pacote de fontes é carregado por dlviz, então a fonte do documento é usada).
• Superfícies 3D. Use pgfplots \addplot3[surf] com view={...} e um mapa de cores suave (colormap name=dlheat), e pergunte se um gráfico de contorno explicaria melhor. Geralmente sim.