TikZ 라이브 피규어
라이브 피규어는 독자가 변경할 수 있는 TikZ 그림입니다. 정적 피규어(tikz-dl-visualizer)와 마찬가지로 하나의 아이디어를 명확하게 전달하는 것이 목적이지만, 독자는 이제 무언가를 하고, 그에 대한 아이디어의 반응을 지켜봅니다. 시작점을 드래그하여 모멘텀이 지그재그를 상쇄하는지 확인하고, 온도를 낮추어 소프트맥스가 argmax로 수축하는 것을 지켜봅니다.
모든 피규어는 두 부분으로 구성됩니다.
| 파일 | 내용 | 컴파일러 |
|---|---|---|
figure.tex | 절대 변하지 않는 모든 것: 축, 등고선, 그리드, 고정 값 행렬, 레이블, 방정식, 라이브 텍스트를 위한 슬롯 | pdflatex (한 번) |
figure.js | 변하는 모든 것: 매개변수, 핸들, 핫스팟, 순수 compute(state) 함수, draw(d, state, c) 함수 | 브라우저 (매 변경 시) |
scripts/build.py는 .tex를 두 번 컴파일합니다(한 번은 일반, 한 번은 라이브 텍스트를 ID 색상으로 변환하여 해당 글리프를 잘라내기 위해). 그런 다음 TikZ 좌표 프레임과 명명된 노드 박스를 내보내고, Node.js에서 사양을 실행하여 다음 파일을 생성합니다:
figure.html: 네트워크 없이 완전히 독립된 단일 페이지입니다. 열거나, iframe에 넣거나, 게시할 수 있습니다.figure.png및figure.<snapshot>.png: 기본 상태와 각 스냅샷을 브라우저 없이 렌더링합니다. 이것이 작업 결과를 확인하는 방법입니다.figure.svg: 기본 상태를 정적 SVG로 저장합니다. 논문이나 대체 콘텐츠에 사용합니다.
번들 포함:
assets/dlviz.sty: 팔레트 및 TikZ 스타일(tikz-dl-visualizer와 동일).assets/dllive.sty: TeX 측,export및live=키 및\dlnum.assets/dllive.js: 런타임: 좌표 매핑, 드로잉 API, 슬라이더, 핸들, 핫스팟, 재생.assets/examples/momentum/: 매개변수, 드래그 가능한 핸들, 재생 버튼, 라이브 숫자, 움직이는 레이블.assets/examples/attention/: 내보낸 셀, 호버 핫스팟, 히트맵, 29개의 라이브 숫자, 곡선.references/api.md: 전체 API(TeX 키, 스펙 필드, 드로잉 호출). 세션에서 첫 번째 스펙을 작성하기 전에 읽어보세요.references/gotchas.md: 발생한 문제와 해결 방법입니다. 무언가 이상해 보일 때 읽어보세요.
시각적 언어 자체(색상 역할, 표기법, 레이아웃, 주석)는 tikz-dl-visualizer를 따르세요. 해당 references/visual-language.md 및 references/archetypes.md가 그대로 적용됩니다. 이 세션에서 읽지 않았다면 읽어보세요.
워크플로우
1. 상호작용 문장 작성
코드를 작성하기 전에 "독자가 X를 하면 Y가 보이며, 이는 Z를 보여줍니다" 형식의 한 문장을 작성하세요.
- "시작점을 드래그하고 β를 변경합니다: 계곡을 가로지르는 지그재그는 상쇄되고, 계곡을 따라 움직임은 누적됩니다. β가 너무 크면 오버슈트가 발생합니다."
- "토큰에 마우스를 올리면: 해당 행의 A는 가중치 집합이고, 출력 행은 V 행의 가중 평균입니다. τ를 낮추면 가중치가 하나의 행으로 수축합니다."
Y가 정적 피규어에서도 동일하게 명확하다면 정적 피규어를 만드세요 (tikz-dl-visualizer).
하나에서 세 개의 컨트롤을 사용하세요. 각 컨트롤은 눈으로 따라갈 수 있는 무언가를 변경해야 합니다. 효과를 볼 수 없는 슬라이더는 노이즈에 불과합니다.
2. 정적 부분과 라이브 부분 분리
종이에 무엇이 변하는지 그려보세요. 나머지 모든 것은 .tex에 넣습니다. 일반적인 분할:
- 정적: 축, 등고선, 그리드, 셀 윤곽선, 고정 행렬, 토큰 레이블, 방정식,
\(\beta = {}\)와 같은 판독 레이블, 범례 선. - 라이브: 경로, 점, 하이라이트, 히트맵 채우기, 화살표, 흐리게 하기, 숫자(실제 TeX 글리프를 유지하기 위해
\dlnum슬롯 사용). - 이동해야 하는 레이블(예: 핸들에 연결된 레이블)도
live=노드이며d.label(id, {from, to})로 이동합니다.
3. figure.tex 작성
가장 가까운 예제에서 시작하세요. 필수:
\documentclass[tikz,border=8pt]{standalone}
\usepackage[dark]{dlviz} % [light] for white pages
\usepackage{dllive}
\begin{document}
\begin{tikzpicture}[x=1.15cm, y=1.15cm]
\useasboundingbox (xmin,ymin) rectangle (xmax,ymax); % 항상: 라이브 드로잉이 이 안에 맞아야 함
...정적 그리기...
\node[cell=coloraqua, export] (A-1-1) at (..) {}; % export: JS가 이 박스를 참조할 수 있음
\node[fit=(Q-1-1)(Q-1-3), inner sep=0, export] (Qrow-1) {}; % 핫스팟을 위한 보이지 않는 박스
\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}
scale=대신x=/y=로 스케일을 설정하세요. 그러면 JS의 1 단위가 TikZ의 1 단위가 됩니다.- 라이브 숫자 노드는 정확히
\(\dlnum\)을 포함합니다.text=로 색상을,font=로 크기를 설정하세요. 노드 내부의 색상 명령은 이를 깨뜨립니다. - 표 셀에 숫자를 넣을 때는 셀 중앙에
anchor=mid west를 사용하고,d.number(id, v, {at: "cell"})로 중앙 정렬합니다.\matrix또는 레이아웃이 중요한 곳에서는\dlnumin{2em}을 사용하여 슬롯이 해당 너비만 예약하도록 합니다. - 피규어가 무언가 선택되었을 때만 의미가 있다면
initial: {hover: "..."}및stickyHover: true로 해당 상태로 엽니다. - JS가 이름을 반복할 수 있도록 이름을 지정하세요 (
A-\i-\j,Qrow-\i). tikz-dl-visualizer에서와 같이 상단에% Caption:주석을 넣으세요.
4. figure.js 작성
DLLive.figure({
title: "...", caption: "...상호작용 방법, 한두 문장...",
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$/, // `state.hover`를 설정하는 내보낸 노드
play: { param: "t", ms: 110 }, // 선택 사항: (숨겨진) 매개변수 애니메이션
compute: (s) => ({ path: run(s.beta, s.w0) }), // 순수 수학, 메모이제이션
draw(d, s, c) { // TikZ 단위, dlviz 색상
d.path(c.path, { color: "aqua", width: "thick", dots: true });
d.number("beta", s.beta, { digits: 2 });
},
snapshots: [{ name: "overshoot", beta: 0.95 }], // 추가 PNG 확인용
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]}` }],
});
- 수학은
compute에 있으며, 정확해야 합니다. 먼저 Python(numpy)으로 참조를 작성한 다음, Python에서 계산한 숫자와 JS를 비교하는tests항목을 추가하세요. 머리로 작성한 수학을 절대 믿지 마세요. draw는 그리기만 합니다. 상태 변경 없음, 난수 없음(노이즈가 필요하면compute에서 시드된 RNG 사용), 모든 프레임에서 실행됩니다.- dlviz 색상 역할(
aqua,red,orange!55!bg...)과 TikZ 너비(thin,thick,very thick)를 사용하여 오버레이가 스캐폴드와 조화를 이루도록 합니다. - 중요한 모든 상태(각 슬라이더의 극단, 호버, 애니메이션 중간)에 대한 스냅샷을 추가하세요. 중첩이 숨겨지는 곳입니다.
5. 빌드
uv run --with pymupdf python <skill-dir>/scripts/build.py path/to/figure.tex
내보낸 노드 이름과 라이브 슬롯, 핫스팟이 일치한 노드 수, 각 테스트의 PASS/FAIL, 페이지 외부 그림 또는 TeX 텍스트가 가장자리에서 잘린 경우 WARN을 출력합니다. 오류는 문제가 있는 슬롯, 노드 또는 매개변수의 이름을 지정합니다. .js만 변경한 경우 --no-tex를 추가하세요(약 1초).
6. 확인, 비판, 반복
작성된 모든 PNG를 열고(읽기 도구 사용) 정적 피규어와 마찬가지로 다음을 확인하세요:
- 라이브 부분이 스캐폴드와 정렬됩니까? (경로가 올바른 점에서 시작하고, 숫자가 셀 안에 있으며, 하이라이트가 행을 감싸고 있습니까?)
- 모든 스냅샷에서 겹치는 것이 있습니까? (판독값을 통과하는 경로, 숫자 위의 곡선, 셀 밖의 텍스트, 가장자리에서 잘린 것 등)
- 컨트롤의 극한값도 여전히 잘 읽힙니까? (β = 0.99, τ = 0.2, 모서리의 핸들 등)
- 기본 상태에서 눈이 3초 안에 아이디어를 찾을 수 있습니까? 기본 상태는 썸네일과 훑어보는 독자가 보는 것입니다.
- 색상이 스캐폴드와 오버레이 모두에서 역할을 유지합니까?
수정하고 다시 빌드하세요. 보통 2~3회 반복합니다.
그런 다음 브라우저가 있다면 실제 페이지를 시도하세요(내장 브라우저 창). 일반적으로 file://을 거부하므로 --directory로 폴더를 서빙하세요(예: .claude/launch.json 항목 {"name": "fig", "runtimeExecutable": "python3", "runtimeArgs": ["-m", "http.server", "8800", "--directory", "<folder>"], "port": 8800} 및 preview_start). 드래그, 슬라이드, 호버 및 재생을 수행하고, 콘솔에서 DLLive.state()는 현재 상태를 보여줍니다. 스냅샷은 대시나 호버 커서를 표시하지 않습니다.
7. 전달
사용자에게 PNG(기본 상태), figure.html 경로, 그리고 짧은 읽기 가이드(무엇을 먼저 시도하고 무엇을 관찰해야 하는지("w₀를 가파른 방향으로 드래그한 다음 β를 높이세요...")를 제공하세요. 공유 가능한 링크를 원한다면 HTML을 아티팩트로 게시하세요. 자체 포함되어 있으므로 추가 파일이 필요하지 않습니다. 자연스러운 다음 컨트롤 또는 피규어를 한 줄로 언급하세요.
임베딩
- 한 페이지에 여러 피규어, 또는 자체 밝음/어두움 테마가 있는 페이지 (tikz-explorer-book은
tools/fig.sh를 통해 이 작업을 수행):--themes dark,light --embed로 빌드하세요. 두 테마 모두에서 스캐폴드를 컴파일하고figure.live.html(조각<div class="dl-live">및<script>DLLive.load("name", ...)</script>)을 생성합니다. 호스트 페이지는 조각 앞에assets/dllive.js를 한 번 포함하고,assets/template.html에 "live figure"로 표시된 CSS 규칙을 포함합니다.--show-d/--show-l로 현재 테마에 대한 스캐폴드를 표시합니다. 런타임은 페이지 테마(<html>의data-theme="dark|light"또는 시스템 설정)를 따라 오버레이의 색상을 다시 지정합니다.-light.png도 생성됩니다. - 독립형 또는 아티팩트:
figure.html을 그대로 사용합니다.--themes dark,light를 사용하면 뷰어의 테마를 따르고, 그렇지 않으면.tex의 테마를 유지합니다. - 슬라이드: 정적 슬라이드에는
figure.png/figure.svg를 사용하고 HTML에 연결하세요. - 논문:
figure.svg또는.dllive/의 스캐폴드 PDF를 사용하세요. 정적 기본 상태는 그 자체로 완전한 피규어입니다. 인쇄 전용 피규어의 경우tikz-dl-visualizer가 더 나은 도구입니다.