ML Paper Figure 1
Construye la figura como SVG escrito a mano en cuatro fases con compuertas: Planificar → Borrador → Renderizar y Criticar (≤ 3 rondas) → Exportar. No empieces a escribir SVG antes de que exista el plano. Las coordenadas elegidas ad hoc son la causa principal de etiquetas y flechas que se salen de las cajas, y el lint y la revisión visual solo funcionan bien contra un plano.
SKILL_DIR abajo significa el directorio base de este skill. Los scripts se ejecutan sin conexión; verifica el renderizador una vez por sesión:
python3 "$SKILL_DIR/scripts/render_svg.py" --list-backends
El script elige Chromium (Playwright), rsvg-convert, inkscape, cairosvg o resvg, el que esté instalado. El lint de geometría exacta necesita Chromium. Sin él, las comprobaciones son aproximadas, así que apóyate más en la revisión visual.
Archivos de referencia (léelos cuando la fase lo indique)
| Archivo | Cuándo leerlo |
|---|---|
references/design-system.md | Fase 1. Cubre el tamaño del lienzo según la conferencia, espaciado del layout, roles de paleta, niveles tipográficos, metáforas de forma, estilos de conectores. Son valores por defecto; adáptalos cuando el contenido lo requiera. |
references/svg-primitives.md | Fase 2. Contiene los <defs> para copiar y pegar (marcadores, insignias, miniaturas), fórmulas de centrado de texto y conectores, y plantillas de formas para ML. |
assets/primitives-gallery.png | Opcional. Una vista renderizada de cada primitiva, útil para elegir metáforas. |
assets/example-figure1.svg (+ .png) | Opcional. Una Figura 1 completa, limpia de lint (encoder congelado → módulo propuesto → decoder + pérdidas discontinuas) para copiar su estructura. |
scripts/svg_geom.py | Úsalo en cualquier momento que necesites coordenadas exactas. Imprime rutas de conectores, trapezoides, pilas, rejillas y etiquetas centradas con una comprobación de ajuste. |
scripts/tex_math.py | Usado por render_svg.py para las matemáticas $…$. Ejecuta --paper main.tex --show para ver la configuración de matemáticas y macros tomadas del paper, --test 'c_{FA}' --pt 6 para componer un fragmento. |
Fase 1: Planificar (plano antes de cualquier SVG)
- Extrae la estructura de lo que el usuario haya dado (prosa, LaTeX/Markdown de Métodos, código PyTorch
nn.Module):- etapas (2–4 grupos que se convierten en tarjetas (a), (b), (c)), y los módulos dentro de cada una;
- qué módulo(s) son la contribución del paper (recibe el color de acento), cuáles están congelados/preentrenados, cuáles son entrenables;
- tensores en la ruta principal con formas, p.ej.
(B, 3, H, W) → (B, N, D), usando los símbolos propios del paper; - flujos: datos hacia adelante (sólido), pérdidas/supervisión (discontinuo), gradientes/retroalimentación, conexiones de salto, rutas solo de inferencia vs solo de entrenamiento.
Desde el código:
__init__lista los módulos,forward()da el orden y las formas,requires_grad_(False)/.eval()/torch.no_grad()marcan partes congeladas, y los términos de pérdida provienen del paso de entrenamiento. Si la fuente no dice qué es novedoso o qué está congelado, haz una pregunta corta. De lo contrario, procede con suposiciones razonables y menciónalas.
- Fija el lienzo: la conferencia y el ancho objetivo, y el
viewBoxde la tabla endesign-system.md§2. El valor por defecto es 2 unidades por punto impreso, p.ej. NeurIPS800 × ~300. - Escribe el plano en
<nombre>.blueprint.mdjunto a la figura, y resúmelo al usuario en unas pocas líneas. Los archivos van donde el usuario guarda las figuras del paper (por defecto:figures/en su proyecto):
figure: figure1_overview # tallo del archivo
target: neurips # valor de --target para render_svg.py; viewBox 800 x 300 (2u = 1pt)
flow: left-to-right # o top-to-bottom / two-row snake
stages: # los rangos x de las tarjetas cubren el ancho con espacios; las tarjetas comparten un rango y
- id: a
title: "(a) Frozen Encoder"
box: [12, 12, 186, 240] # x, y, w, h
modules:
- {id: img, kind: thumb-patches, box: [28, 120, 40, 40], label: "x", dims: "3×H×W"}
- {id: enc, kind: trapezoid-encoder, role: frozen, badge: frozen, box: [96, 90, 88, 100], inset: 18, label: "Vision|Encoder"}
- id: b
# ...
edges:
- {from: img.right, to: enc.left, style: forward, role: data}
- {from: dec.bottom, to: loss.top, style: loss, label: "ŷ"}
colors: {enc: frozen, uam: proposed, dec: train, loss: loss} # roles de paleta de design-system.md §4
legend: [forward, loss, frozen, trainable] # solo codificaciones que necesitan explicación
notes: "tarjeta propuesta ~45% del ancho; columna vertebral en y = 140"
Verificaciones del plano antes de continuar: todo módulo tiene una caja; las cajas dentro de una tarjeta dejan ≥ 14u de padding de tarjeta; los vecinos que une una flecha están separados ≥ 28u (≥ 40u si la flecha lleva etiqueta); los anchos de etiqueta caben en sus cajas (svg_geom.py label … reporta el padding); y la columna vertebral (ruta principal) es una línea recta cuando sea posible.
Fase 2: Borrador (un solo SVG autocontenido)
Lee references/svg-primitives.md, luego escribe <nombre>.svg:
- Comienza con el esqueleto y los
<defs>principales de allí (pila de fuentes, clases tipográficas, una punta de flecha por rol de paleta, insignias vectoriales). Añade definiciones de miniatura solo cuando se usen. - Autocontenido: sin imágenes externas, sin fuentes web ni
@import, sin<foreignObject>, sin scripts, sin emojis. Usa las insignias vectoriales en lugar de ❄️/🔥, porque los emojis se convierten en mapas de bits o tofu en los PDFs. - Orden de dibujo: fondo → tarjetas → bordes → módulos → etiquetas → insignias → leyenda. Los bordes quedan debajo de los módulos para que sus extremos se escondan bajo los bordes.
- Da a los módulos identificadores (
id="enc"), a los conectoresclass="edge"yfill="none", y a los mini visualesdata-lint="ignore". Los mensajes de lint luego nombran elementos que puedes encontrar. - Calcula las coordenadas con las fórmulas o
svg_geom.py, no a ojo. La línea base del centro del texto escy + 0.35 × font-size. Los trazados terminan 2u antes del borde del objetivo, ya que la punta de flecha estándar sobresale 2u. - Las matemáticas son LaTeX: escribe símbolos entre
$…$dentro de un<text>(puntuaciones $S[i,v,p]$,$\mathcal{L}_{\text{KL}}$) en la notación del paper. El script de renderizado las compone con la fuente matemática y las macros del paper (--paper main.tex) y escribe el resultado en el SVG. Edita solo el<text>fuente; nunca finjas matemáticas con texto serif itálico o subíndices<tspan dy>(svg-primitives.md §2).
Fase 3: Renderizar y criticar (bucle, máx. 3 rondas)
Cada ronda:
- Renderiza y ejecuta lint:
Conpython3 "$SKILL_DIR/scripts/render_svg.py" <nombre>.svg --target <conferencia> [--paper main.tex] # conferencia: neurips (por defecto), icml, cvpr, …-col, o 5.5in--paper(necesario una vez; la configuración se almacena en el SVG) las matemáticas$…$usan la fuente matemática y las macros del paper. Esto escribe<nombre>.png,<nombre>.debug.png(rejilla de coordenadas más cajas numeradas alrededor de cada problemaE#/W#) y<nombre>.preview.png(la figura a tamaño impreso), e imprime errores y advertencias con coordenadas. - Mira las imágenes tú mismo. Lee
<nombre>.debug.pngprimero, luego<nombre>.preview.png. El lint no puede juzgar la composición, así que el pase visual es obligatorio. - Revisa la lista de verificación y escribe una crítica corta: una línea por defecto, con la solución en coordenadas.
- Ajuste del texto: ninguna etiqueta toca o cruza el borde de su caja; las etiquetas de los módulos tienen ≥ 8u de padding lateral.
- Flechas: ninguna atraviesa un módulo o etiqueta; las puntas de flecha tocan los bordes del objetivo (sin espacio, sin perforar); sin cruces evitables; la dirección del flujo es obvia.
- Espaciado y alineación: espacios iguales entre hermanos, las filas comparten líneas centrales, las cajas del mismo tipo comparten tamaños, el padding de las tarjetas es uniforme, y ninguna esquina está abarrotada mientras otra está vacía.
- Legibilidad impresa (
preview.png): el texto más pequeño sigue siendo legible; el script reporta mínimo ≥ 6pt al ancho objetivo; los trazos visibles; los roles distinguibles. - Jerarquía: el módulo propuesto es lo primero que el ojo capta; los títulos de etapa (a)/(b)/(c) son escaneables; un color de acento.
- Semántica: cada módulo y borde del plano está presente y correcto; sólido = adelante, discontinuo = pérdida; las insignias y la leyenda coinciden con lo dibujado; la notación coincide con el paper.
- Corrige, luego vuelve a renderizar. Detente cuando haya 0 errores y cada elemento de la lista esté aprobado, o una advertencia restante sea una elección deliberada que puedas justificar (di cuál y por qué). Las advertencias de lint son pistas, no veredictos: una advertencia que has inspeccionado y consideras correcta no necesita cambio.
Después de la ronda 3, deja de iterar incluso si quedan problemas menores, y menciónalos en el informe.
Fase 4: Exportar
python3 "$SKILL_DIR/scripts/render_svg.py" <nombre>.svg --target <conferencia> --export
Esto produce <nombre>.pdf (vectorial, el tamaño de página es igual al ancho impreso, por lo que sus tamaños de texto son los tamaños impresos reales), un <nombre>.png de alta resolución (3 px/u, o --dpi 300), y comprobaciones del PDF: una sola página, fuentes incrustadas, solo fuentes Type 1 / TrueType (Type 3 es un error), sin contenido rasterizado, y el PDF coincidiendo con el PNG. Si el renderizador incrustara fuentes Type 3 para el texto sans (Chromium hace esto para fuentes CFF como Inter .otf o TeX Gyre .otf, y los verificadores de estilo NeurIPS/ICML las rechazan), ese texto se convierte en contornos vectoriales automáticamente (--pdf-text auto|fonts|outline). Las matemáticas $…$ se estampan después desde la salida de pdflatex, por lo que el PDF lleva las fuentes matemáticas reales Type 1 (p.ej. CMMI6 con subíndices CMMI5); el informe lista las fuentes y sus tamaños impresos. También elimina las imágenes de revisión. Luego, dale al usuario:
- los archivos (
.svgfuente,.pdfpara LaTeX,.pngpara diapositivas/vista previa); - un fragmento LaTeX que coincida con el ancho objetivo:
\begin{figure*}[t] % usa figure + \linewidth para conferencias de una columna (NeurIPS/ICLR) o figuras de ancho de columna \centering \includegraphics[width=\textwidth]{figures/<nombre>.pdf} \caption{...}\label{fig:overview} \end{figure*} - un informe corto: el ancho objetivo y el tamaño de fuente impreso más pequeño (y los tamaños de base/script matemáticos, si los hay), las rondas de crítica ejecutadas y qué cambió, y cualquier advertencia aceptada.
Nivel de calidad (lo que significa "terminado")
- Legible al ancho impreso: texto ≥ 6pt, como máximo 4 tamaños de fuente, grosores de línea ≥ 0.5pt.
- Cero errores de lint. Sin desbordamiento de texto, superposiciones, elementos fuera del lienzo, referencias rotas ni emojis.
- Cada flecha comienza y termina en un borde, nunca atraviesa un módulo o etiqueta, y sigue rutas ortogonales redondeadas.
- Un punto focal claro (la contribución), colores de rol consistentes, y una leyenda solo para codificaciones no obvias.
- Fiel al paper: los nombres de módulos, símbolos y formas de tensor coinciden con el texto o el código. No se inventa nada. Marca cualquier suposición.
- Las matemáticas son compuestas por LaTeX en la fuente matemática y notación del paper, con tamaños de script LaTeX (≥ 5pt impresos).
- Los entregables son un único SVG autocontenido, un PDF vectorial (fuentes Type 1/TrueType o contorneadas, nunca Type 3), y un PNG, todos renderizados localmente sin APIs en la nube.