szcharlesji/tikz-live

TikZ Live-Figuren

Eine Live-Figur ist eine TikZ-Zeichnung, die der Leser verändern kann. Der Zweck ist derselbe wie bei einer statischen Figur in tikz-dl-visualizer (eine Idee, offensichtlich gemacht), aber der Leser tut jetzt etwas und beobachtet, wie die Idee reagiert: zieht den Startpunkt und sieht, wie der Impuls das Zickzack aufhebt, senkt die Temperatur und beobachtet, wie Softmax zu Argmax kollabiert.

Jede Figur besteht aus zwei Hälften:

Datei	Inhalt	Kompiliert durch
figure.tex	Alles, was sich nie ändert: Achsen, Konturen, Gitter, Matrizen mit festen Werten, Beschriftungen, die Gleichung und Slots für den Live-Text	pdflatex, einmal
figure.js	Alles, was sich ändert: Parameter, Griffe, Hotspots, eine reine compute(state)-Funktion und draw(d, state, c)	Der Browser, bei jeder Änderung

scripts/build.py kompiliert die .tex zweimal (einmal normal, einmal mit dem Live-Text in ID-Farben, um diese Glyphen ausschneiden zu können), exportiert den TikZ-Koordinatenrahmen und die benannten Knoten-Boxen, führt die Spezifikation unter Node aus und schreibt:

• figure.html: Eine eigenständige Seite (kein Netzwerk). Öffnen, einbetten (iframe) oder veröffentlichen.
• figure.png plus figure.<snapshot>.png: der Standardzustand und jeder Snapshot, ohne Browser gerendert. So sehen Sie Ihre eigene Arbeit.
• figure.svg: Der Standardzustand als statisches SVG, für Paper und Fallbacks.

Enthalten:

• assets/dlviz.sty: Die Palette und TikZ-Stile (gleiche Datei wie in tikz-dl-visualizer).
• assets/dllive.sty: TeX-Seite mit den Schlüsseln export, live= und \dlnum.
• assets/dllive.js: Laufzeit: Koordinaten-Mapping, Zeichen-API, Schieberegler, Griffe, Hotspots, Play-Funktion.
• assets/examples/momentum/: Parameter, ziehbarer Griff, Play-Button, Live-Zahlen, sich bewegende Beschriftung.
• assets/examples/attention/: Exportierte Zellen, Hover-Hotspots, Heatmap, 29 Live-Zahlen, Kurven.
• references/api.md: Die vollständige API (TeX-Schlüssel, Spezifikationsfelder, Zeichenbefehle). Lesen Sie diese, bevor Sie Ihre erste Spezifikation schreiben.
• references/gotchas.md: Bekannte Probleme und deren Behebung. Lesen Sie dies, wenn etwas nicht stimmt.

Für die visuelle Sprache selbst (Farbrollen, Notation, Layout, Annotationen) folgen Sie tikz-dl-visualizer: Deren references/visual-language.md und references/archetypes.md gelten unverändert. Lesen Sie diese, falls Sie sie in dieser Sitzung noch nicht gesehen haben.

Arbeitsablauf

1. Den Interaktionssatz formulieren

Schreiben Sie vor dem Code einen Satz der Form "Der Leser tut X und sieht Y, was Z zeigt":

• "Ziehen Sie den Startpunkt und ändern Sie β: Das Zickzack über das Tal hebt sich auf, während sich die Bewegung entlang des Tals aufaddiert; zu viel β führt zum Überschwingen."
• "Bewegen Sie die Maus über ein Token: Seine Zeile in A ist die Menge der Gewichte, und seine Ausgabezeile ist der gewichtete Durchschnitt der V-Zeilen. Senken Sie τ, und die Gewichte kollabieren auf eine Zeile."

Wenn Y in einer statischen Figur genauso klar wäre, erstellen Sie eine statische (tikz-dl-visualizer). Verwenden Sie ein bis drei Steuerelemente. Jedes Steuerelement muss etwas ändern, dem das Auge folgen kann; ein Schieberegler, dessen Wirkung unsichtbar bleibt, ist Rauschen.

2. Statisch von Live trennen

Zeichnen Sie auf Papier, was sich ändert. Alles andere kommt in die .tex. Typische Aufteilungen:

• Statisch: Achsen, Konturen, Gitter, Zellenumrisse, feste Matrizen, Token-Labels, die Gleichung, Ausgabelabel wie \(\beta = {}\), Legendenstriche.
• Live: Pfade, Punkte, Hervorhebungen, Heatmap-Füllungen, Pfeile, Abdunklungen und Zahlen (als \dlnum-Slots, damit sie echte TeX-Glyphen bleiben).
• Ein Label, das sich bewegen muss (z. B. an einem Griff befestigt), ist ebenfalls ein live=-Knoten, der mit d.label(id, {from, to}) bewegt wird.

3. figure.tex schreiben

Beginnen Sie mit dem nächsten Beispiel. Erforderlich:

\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz}     % [light] für helle Seiten
\usepackage{dllive}
\begin{document}
\begin{tikzpicture}[x=1.15cm, y=1.15cm]
  \useasboundingbox (xmin,ymin) rectangle (xmax,ymax);   % IMMER: Live-Zeichnung muss hineinpassen
  ...statische Zeichnung...
  \node[cell=coloraqua, export] (A-1-1) at (..) {};       % export: JS kann auf diese Box zugreifen
  \node[fit=(Q-1-1)(Q-1-3), inner sep=0, export] (Qrow-1) {};   % unsichtbare Box für einen Hotspot
  \node[anchor=base west, inner sep=0, text=coloraqua] (b) at (..) {\(\beta = {}\)};
  \node[live=beta, anchor=base west, inner sep=0, text=coloraqua] at (b.base east) {\dlnum};
\end{tikzpicture}
\end{document}

• Setzen Sie den Maßstab mit x=/y= (nicht scale=), sodass 1 Einheit in JS 1 Einheit in TikZ entspricht.
• Ein Live-Zahlen-Knoten enthält genau \dlnum. Setzen Sie seine Farbe mit text= und die Größe mit font=; Farbbefehle innerhalb des Knotens zerstören ihn.
• Platzieren Sie Zahlen in Tabellenzellen mit anchor=mid west in der Zellenmitte, dann zentriert d.number(id, v, {at: "cell"}) sie. In einer \matrix oder wo das Layout wichtig ist, verwenden Sie \dlnumin{2em}, damit der Slot nur diese Breite reserviert.
• Wenn die Figur nur Sinn ergibt, wenn etwas ausgewählt ist, öffnen Sie sie entsprechend: initial: {hover: "..."} plus stickyHover: true.
• Benennen Sie die Objekte so, dass JS darüber iterieren kann (A-\i-\j, Qrow-\i).
• Fügen Sie einen % Caption:-Kommentar am Anfang ein, wie in tikz-dl-visualizer.

4. figure.js schreiben

DLLive.figure({
  title: "...", caption: "...wie interagieren, ein bis zwei Sätze...",
  params:  { beta: { label: "β", min: 0, max: 0.99, step: 0.01, value: 0.6 } },
  handles: { w0: { value: [-4, 1.5], min: [-5.2, -1.85], max: [5.2, 1.85] } },
  hotspots: /^Qrow-\d$/,                 // exportierte Knoten, die state.hover setzen
  play: { param: "t", ms: 110 },         // optional: animiert einen (versteckten) Parameter
  compute: (s) => ({ path: run(s.beta, s.w0) }),          // reine Mathematik, memoisiert
  draw(d, s, c) {                                          // TikZ-Einheiten, dlviz-Farben
    d.path(c.path, { color: "aqua", width: "thick", dots: true });
    d.number("beta", s.beta, { digits: 2 });
  },
  snapshots: [{ name: "overshoot", beta: 0.95 }],          // zusätzliche PNGs zur Überprüfung
  tests: [{ name: "matches numpy", state: { beta: 0.4 }, check: (c) => Math.abs(c.path[30][0] - 1.036e-5) < 1e-8 || `got ${c.path[30]}` }],
});

• Die Mathematik lebt in compute, und sie muss korrekt sein. Schreiben Sie zuerst eine Referenz in Python (numpy) und fügen Sie dann einen tests-Eintrag hinzu, der die JS gegen einen von Ihnen in Python berechneten Wert vergleicht. Vertrauen Sie niemals Mathematik, die Sie im Kopf schreiben.
• draw zeichnet nur: keine Zustandsänderungen, keine Zufälligkeit (verwenden Sie bei Bedarf einen gesetzten RNG in compute), und es wird bei jedem Frame ausgeführt.
• Verwenden Sie dlviz-Farbrollen (aqua, red, orange!55!bg...) und TikZ-Dicken (thin, thick, very thick), damit die Overlay-Schicht wie das Grundgerüst aussieht.
• Fügen Sie einen Snapshot für jeden wichtigen Zustand hinzu: Extremwerte jedes Schiebereglers, ein Hover, eine Animation. Dort verstecken sich Überlappungen.

5. Bauen

uv run --with pymupdf python <skill-dir>/scripts/build.py path/to/figure.tex

Es gibt die exportierten Knotennamen und Live-Slots aus, wie viele Knoten die Hotspots getroffen haben, PASS/FAIL für jeden Test und WARN für Zeichnungen außerhalb der Seite oder abgeschnittenen TeX-Text. Fehler benennen den fehlerhaften Slot, Knoten oder Parameter. Nach einer Änderung nur in der .js fügen Sie --no-tex hinzu (ca. 1 Sekunde).

6. Prüfen, kritisieren, iterieren

Öffnen Sie jedes geschriebene PNG (Lese-Tool) und prüfen Sie wie bei einer statischen Figur:

1. Passt der Live-Teil zum Grundgerüst (Pfade beginnen am richtigen Punkt, Zahlen sitzen in ihren Zellen, Hervorhebungen liegen auf ihren Zeilen)?
2. Gibt es in jedem Snapshot Überlappungen: ein Pfad durch eine Beschriftung, eine Kurve über Zahlen, Text außerhalb seiner Zelle, etwas am Rand abgeschnitten?
3. Lesen sich die Extremwerte der Steuerelemente noch gut (β = 0,99, τ = 0,2, ein Griff in einer Ecke)?
4. Findet das Auge die Idee in drei Sekunden im Standardzustand? Der Standardzustand ist das, was ein Thumbnail und ein überfliegender Leser sehen.
5. Behalten die Farben ihre Rollen sowohl im Grundgerüst als auch in der Overlay-Schicht?

Korrigieren und neu bauen. Zwei oder drei Durchgänge sind normal.

Probieren Sie dann die echte Seite aus, falls Sie einen Browser haben (der integrierte Browser-Bereich): Normalerweise verweigert er file://, also dienen Sie den Ordner aus, z. B. mit einem .claude/launch.json-Eintrag {"name": "fig", "runtimeExecutable": "python3", "runtimeArgs": ["-m", "http.server", "8800", "--directory", "<folder>"], "port": 8800} und preview_start. Ziehen, schieben, schweben und abspielen; in der Konsole zeigt DLLive.state() den aktuellen Zustand. Snapshots zeigen keine Strichelung oder Hover-Cursor.

7. Ausliefern

Geben Sie dem Benutzer das PNG (Standardzustand), den Pfad zu figure.html und eine kurze Leseanleitung: was zuerst ausprobieren und worauf achten ("Ziehen Sie w₀ in die steile Richtung, dann erhöhen Sie β..."). Falls ein teilbarer Link gewünscht ist, veröffentlichen Sie das HTML als Artefakt; es ist eigenständig, daher sind keine zusätzlichen Dateien nötig. Erwähnen Sie das naheliegende nächste Steuerelement oder die nächste Figur in einer Zeile.

Einbettung

• Mehrere Figuren auf einer Seite oder eine Seite mit eigenem Hell/Dunkel-Design (tikz-explorer-book macht dies über sein tools/fig.sh): Bauen Sie mit --themes dark,light --embed. Das kompiliert das Grundgerüst in beiden Designs und schreibt figure.live.html, ein Fragment (<div class="dl-live"> plus ein <script>DLLive.load("name", ...)</script>). Die Host-Seite bindet assets/dllive.js einmal vor den Fragmenten ein und die CSS-Regeln, die in assets/template.html als "live figure" markiert sind. Es zeigt das Grundgerüst für das aktuelle Design mit --show-d / --show-l. Die Laufzeit folgt dem Seitendesign (data-theme="dark|light" auf <html> oder der Systemeinstellung) und färbt die Overlay-Schicht entsprechend ein. Es wird auch -light.png geschrieben.
• Eigenständig oder als Artefakt: figure.html wie es ist. Mit --themes dark,light folgt es dem Design des Betrachters; andernfalls behält es das Design der .tex.
• Folien: Verwenden Sie figure.png / figure.svg für die statische Folie und verlinken Sie das HTML.
• Paper: Verwenden Sie figure.svg oder das Grundgerüst-PDF in .dllive/; der statische Standardzustand ist eine vollständige Figur für sich. Für reine Druckfiguren ist tikz-dl-visualizer das bessere Werkzeug.