Debian Codegraph @

texmf-dist/doc/latex/svg-animate/svg-animate.tex

raw
1 \documentclass[a4paper,11pt]{article}
2
3 \usepackage[T1]{fontenc}
4 \usepackage{lmodern}
5 \usepackage[margin=2.5cm]{geometry}
6 \usepackage{tcolorbox}
7 \tcbuselibrary{documentation, listings, breakable, skins}
8 %% tcolorbox documentation library does not define \env; use \texttt formatting.
9 \newcommand{\env}[1]{\texttt{#1}}
10
11 \usepackage{hyperref}
12 \hypersetup{
13 colorlinks = true,
14 linkcolor = blue!50!black,
15 urlcolor = blue!70!black,
16 }
17
18 %% Load the package itself (in xelatex/pdflatex mode: animations are defined
19 %% but no SVG keyframes are emitted --- useful for static PDF examples)
20 \usepackage{svg-animate}
21
22 %% ── tcolorbox documentation style ────────────────────────────────────────────
23 \tcbset{
24 color command = blue!60!black,
25 color environment= green!40!black,
26 color option = orange!70!black,
27 before doc body = {\smallskip},
28 doc marginnote = {font=\footnotesize\ttfamily},
29 }
30
31 \lstset{
32 language = [LaTeX]TeX,
33 basicstyle = \small\ttfamily,
34 keywordstyle = \color{blue!60!black},
35 commentstyle = \color{black!50}\itshape,
36 columns = flexible,
37 keepspaces = true,
38 }
39
40 %% ── Title ─────────────────────────────────────────────────────────────────────
41 \title{%
42 \texttt{svg-animate}\\[0.5ex]
43 \large Animated SVG diagrams with Ti\textit{k}Z
44 }
45 \author{Sébastien Gross\\[0.5ex]
46 \small\url{https://github.com/renard/svg-animate}}
47 \date{\svganimatedate --- \svganimateversion}
48
49 \begin{document}
50
51 \maketitle
52 \tableofcontents
53 \bigskip
54
55 %% ─────────────────────────────────────────────────────────────────────────────
56 \section{Introduction}
57
58 \texttt{svg-animate} is a small LaTeX package for producing \textbf{animated
59 SVG diagrams} using Ti\textit{k}Z. The animation model is deliberately simple:
60 content is organised into discrete \emph{steps}, and only one step is fully
61 visible at a time --- exactly like a cinema film or a slide presentation.
62
63 The package wraps the low-level
64 \href{https://tikz.dev/library-animations}{\texttt{tikz animations}} library
65 (available since PGF~3.1.9) with a convenient high-level interface that handles
66 step counting, absolute timing, and option cascading automatically.
67
68 \medskip
69 \textbf{Output formats:}
70 \begin{itemize}
71 \item \textbf{Animated SVG} --- compile with \texttt{latex} + \texttt{dvisvgm}.
72 The animation uses SMIL opacity keyframes supported by all major browsers.
73 \item \textbf{Static PDF} --- compile with \texttt{xelatex} or \texttt{pdflatex}.
74 The package detects the output mode and adapts \cs{reveal} behaviour
75 accordingly (see Section~\ref{sec:static}).
76 \end{itemize}
77
78 %% ─────────────────────────────────────────────────────────────────────────────
79 \section{Installation}
80
81 Copy the \texttt{svg-animate} directory into a location where \TeX{} can find
82 it. Common user-local locations (no root access required):
83
84 \begin{itemize}
85 \item \texttt{\$TEXMFHOME/tex/latex/}
86 \item \texttt{\$TEXHOME/tex/latex/}
87 \item \texttt{\textasciitilde/texmf/tex/latex/} (typical Linux default)
88 \item \texttt{\textasciitilde/Library/texmf/tex/latex/} (typical macOS default)
89 \end{itemize}
90
91 Alternatively, point \texttt{TEXINPUTS} at the directory containing
92 \texttt{svg-animate.sty} before compiling:
93
94 \begin{dispListing}
95 TEXINPUTS="path/to/svg-animate//:$TEXINPUTS" latex diagram.tex
96 \end{dispListing}
97
98 The trailing \texttt{//} tells \TeX{} to search subdirectories recursively.
99
100 %% ─────────────────────────────────────────────────────────────────────────────
101 \section{Compilation pipeline}
102
103 \begin{dispListing}
104 # Compile to animated SVG
105 latex diagram.tex
106 latex diagram.tex # second pass for stable layout
107 dvisvgm --font-format=woff2 \
108 --optimize=all \
109 --bbox=min \
110 diagram.dvi -o diagram.svg
111
112 # Compile to static PDF (for preview)
113 xelatex diagram.tex
114 \end{dispListing}
115
116 \subsection{Embedding bitmap images}
117
118 If the diagram includes PNG or JPEG images (e.g.\ via \cs{includegraphics}),
119 pass \texttt{--embed-bitmaps} to \texttt{dvisvgm} to produce a fully
120 self-contained SVG\@. Each bitmap is then inlined as a base64 data URI
121 rather than an external file reference, so the SVG can be moved or published
122 independently of the source directory.
123
124 \begin{dispListing}
125 dvisvgm --font-format=woff2 --optimize=all --bbox=min \
126 --embed-bitmaps diagram.dvi -o diagram.svg
127 \end{dispListing}
128
129 \textbf{Why a driver override is needed.}
130 The stock \texttt{graphicx} dvisvgm driver (\texttt{graphics-def/dvisvgm.def})
131 implements bitmap inclusion via \verb|\special{dvisvgm:raw}|, injecting a
132 literal \texttt{<image xlink:href="file.png"/>} fragment. \texttt{dvisvgm}
133 copies this verbatim into the output SVG, leaving an external reference that
134 \texttt{--embed-bitmaps} does not process.
135
136 \texttt{svg-animate} therefore redefines \cs{Ginclude@bitmap} (in SVG mode
137 only) to emit \verb|\special{dvisvgm:img W H file}| instead. This is the
138 special type that \texttt{--embed-bitmaps} does process, converting the file
139 to a base64 data URI.
140
141 \textbf{Version requirement.}
142 Support for \texttt{--embed-bitmaps} on \verb|dvisvgm:img| specials was
143 introduced in \textbf{dvisvgm~3.4} (2024-07-24, shipped with \TeX{}
144 Live~2025). With earlier versions, \verb|dvisvgm:img| produces an external
145 \texttt{xlink:href} reference regardless of \texttt{--embed-bitmaps}: the
146 override has no effect and bitmaps remain as separate files.
147
148 The package detects the output mode via \texttt{\textbackslash pdfoutput}
149 (defined by pdfTeX and LuaTeX):
150 \begin{itemize}
151 \item \texttt{\textbackslash pdfoutput = 0} (\textbf{\texttt{latex}} in DVI
152 mode) --- loads the \texttt{dvisvgm} PGF driver and passes
153 \texttt{dvisvgm} to \texttt{graphicx}.
154 \item \texttt{\textbackslash pdfoutput = 1} (\textbf{\texttt{pdflatex}},
155 \textbf{\texttt{lualatex}}) --- default PDF drivers; no action needed.
156 \item \texttt{\textbackslash pdfoutput} undefined (\textbf{\texttt{xelatex}})
157 --- default XeTeX drivers; no action needed.
158 \end{itemize}
159
160 A minimal document looks like:
161 \begin{dispListing}
162 \documentclass{standalone}
163 \usepackage{svg-animate}
164
165 \begin{document}
166 \begin{tikzpicture}
167 % ... your diagram ...
168 \end{tikzpicture}
169 \end{document}
170 \end{dispListing}
171
172 %% ─────────────────────────────────────────────────────────────────────────────
173 \section{Animation}
174
175 \subsection{Overview}
176
177 All animation content is placed inside an \env{animate} environment. The body
178 is divided into \emph{steps} by \cs{animstep} separators. Each \cs{reveal}
179 call wraps a TikZ element and controls its opacity: the element is active (fully
180 visible) during its step and inactive (hidden or dimmed) during all other steps.
181
182 \begin{dispListing}
183 \begin{animate}[duration=1]
184 \reveal[inactive opacity=0.2]{\node (A) at (0,0) {Step 1};}
185 \animstep
186 \reveal{\node (B) at (0,0) {Step 2};}
187 \animstep[duration=2]
188 \reveal{\node (C) at (0,0) {Step 3 (lasts 2 s)};}
189 \end{animate}
190 \end{dispListing}
191
192 Options cascade from the environment down through each step to individual
193 elements: inner options override outer ones.
194
195 \begin{center}
196 \begin{tcolorbox}[width=0.8\linewidth, colback=gray!5, colframe=gray!40,
197 fontupper=\small\ttfamily]
198 \texttt{\textbackslash begin\{animate\}[duration=1, inactive opacity=0]}\\
199 \quad\texttt{\textbackslash animstep[inactive opacity=0.3]}\\
200 \quad\quad\texttt{\textbackslash reveal[active opacity=0.8]\{...\}}\\
201 \texttt{\textbackslash end\{animate\}}
202 \end{tcolorbox}
203 \end{center}
204
205 \subsection{Environment}
206
207 \begin{docEnvironment}{animate}{\oarg{options}}
208 Collects all content up to \cs{end}\texttt{\{animate\}} and processes it
209 in two passes: first to sum all step durations (without executing any TikZ
210 code), then to render each step with correct absolute timing.
211
212 \oarg{options} accepts any \texttt{/anim/.cd} key and applies them as
213 defaults for all steps in this environment.
214 \end{docEnvironment}
215
216 \subsection{Commands}
217
218 \begin{docCommand}{reveal}{\oarg{options}\marg{content}}
219 Wraps \meta{content} in an opacity animation. The element is shown at
220 \docValue{active opacity} during its step and at \docValue{inactive opacity}
221 at all other times.
222
223 Set \texttt{inactive opacity} to a value above~0 to \emph{dim} the element
224 instead of hiding it --- useful for nodes that should remain faintly visible
225 in the background.
226
227 \texttt{duration} in \oarg{options} is accepted but silently ignored (it has
228 no meaning at the per-element level).
229
230 \textbf{PDF mode behaviour} depends on whether \cs{noanimate} is present in
231 the enclosing \env{animate} body:
232 \begin{itemize}
233 \item No \cs{noanimate}: \meta{content} is rendered at full opacity
234 (all steps stacked --- useful for a quick overview).
235 \item \cs{noanimate} present: \meta{content} is suppressed; use the
236 \texttt{noanimate} key on \cs{reveal} to override for individual elements.
237 \end{itemize}
238 \end{docCommand}
239
240 \begin{docCommand}{noanimate}{\marg{content}}
241 \textbf{PDF mode:} renders \meta{content} as a plain static element, with no
242 animation wrapper. When \cs{noanimate} is present inside an \env{animate}
243 body, all \cs{reveal} elements in that body are automatically suppressed,
244 leaving \meta{content} as the sole visible output --- a single clean frame.
245
246 \textbf{SVG mode:} completely ignored; the animated steps play normally.
247
248 \cs{noanimate} must appear inside \env{animate}. Multiple calls are allowed;
249 each one renders independently in PDF.
250
251 \begin{dispListing}
252 \begin{animate}[inactive opacity=0.08]
253 \noanimate{\fill[red!85!black] (0,2.2) circle[radius=0.85];}
254 \reveal{\fill[green!65!black] (0,-2.2) circle[radius=0.85];}
255 \animstep
256 \reveal{\fill[red!85!black] (0, 2.2) circle[radius=0.85];}
257 \end{animate}
258 \end{dispListing}
259 \end{docCommand}
260
261 \begin{docCommand}{animstep}{\oarg{options}}
262 Step separator inside \env{animate}. The token is never executed; it
263 is consumed as a delimiter when the body is split into per-step segments.
264
265 \oarg{options} accepts any \texttt{/anim/.cd} key and applies them to
266 all elements of the \emph{following} step, overriding environment-level
267 defaults.
268 \end{docCommand}
269
270 \subsection{Keys}
271
272 All keys live under the \texttt{/anim/.cd} path and can be set at any level
273 of the cascade.
274
275 \begin{docKey}[anim]{duration}{=\meta{seconds}}{initial: \texttt{2}}
276 Duration of this step in seconds. Can be set globally, per-environment,
277 or per-step via \cs{animstep}\oarg{duration=\meta{N}}. Has no effect when
278 passed to \cs{reveal} (silently ignored).
279 \end{docKey}
280
281 \begin{docKey}[anim]{active opacity}{=\meta{value}}{initial: \texttt{1}}
282 Opacity of a \cs{reveal} element while its step is active.
283 \texttt{1}~= fully opaque (default), \texttt{0}~= fully transparent.
284 \end{docKey}
285
286 \begin{docKey}[anim]{inactive opacity}{=\meta{value}}{initial: \texttt{0}}
287 Opacity of a \cs{reveal} element while its step is \emph{inactive}.
288 \texttt{0}~= fully hidden (default). Set to a small positive value (e.g.\
289 \texttt{0.15}) to keep elements faintly visible rather than completely
290 disappearing.
291 \end{docKey}
292
293 \begin{docKey}[anim]{loop}{=\texttt{true}\textbar\texttt{false}}{initial: \texttt{true}}
294 Controls whether the animation repeats after reaching the last step.
295 \begin{itemize}
296 \item \texttt{true} (default) — the animation loops indefinitely.
297 \item \texttt{false} — the animation plays once and freezes on the last frame.
298 \end{itemize}
299 Can be set globally or per-environment.
300
301 \begin{dispListing}
302 %% One-shot animation — plays through all steps once, then stops.
303 \begin{animate}[loop=false]
304 \reveal{\node {Step 1};}
305 \animstep
306 \reveal{\node {Step 2};}
307 \animstep
308 \reveal{\node {Step 3};}
309 \end{animate}
310 \end{dispListing}
311
312 \medskip\noindent\textbf{Interaction with \cs{noanimate}:}
313 When the animation ends (\texttt{loop=false}), the SVG browser removes
314 all \texttt{<animate>} effects and reverts each element to its base
315 (unanimated) opacity --- which for \cs{reveal} elements is~1, i.e.\
316 fully visible. If a \cs{noanimate} fallback is present in the body, it
317 therefore becomes visible once the animation has finished, giving the
318 diagram a natural static resting state.
319
320 \begin{dispListing}
321 \begin{animate}[inactive opacity=0.08, loop=false]
322 %% Static resting state shown after the animation ends.
323 \noanimate{\fill[red!85!black] (0,2.2) circle[radius=0.85];}
324 \reveal{\fill[green!65!black] (0,-2.2) circle[radius=0.85];}
325 \animstep
326 \reveal{\fill[orange!90!black] (0, 0.0) circle[radius=0.85];}
327 \animstep
328 \reveal{\fill[red!85!black] (0, 2.2) circle[radius=0.85];}
329 \end{animate}
330 \end{dispListing}
331 \end{docKey}
332
333 \begin{docKey}[anim]{blink}{=\meta{seconds}}{no default}
334 Makes the element blink during its active step: the opacity alternates
335 between \docValue{blink on opacity} and \docValue{blink off opacity} at the
336 given period. The element is shown at \docValue{inactive opacity} during
337 all other steps.
338
339 The \meta{seconds} value is the \emph{full} blink period: the element is
340 visible for $\meta{seconds}/2$ seconds, then hidden for $\meta{seconds}/2$
341 seconds, then repeats.
342
343 If the step duration is not an exact multiple of $\meta{seconds}/2$, the
344 last partial half-period is included and cut at the step boundary.
345
346 \textbf{Note:} \texttt{blink} and \texttt{step} are mutually exclusive.
347 When both are specified, \texttt{blink} wins, \texttt{step} is ignored,
348 and a \texttt{PackageWarning} is issued.
349
350 \begin{dispListing}
351 \begin{animate}[duration=2, inactive opacity=0.15]
352 \reveal{\node at (0,1) {Step 1 — static};}
353 \animstep
354 \reveal[blink=0.4]{\node[fill=yellow] at (0,0) {Step 2 — blinks};}
355 \animstep
356 \reveal{\node at (0,-1) {Step 3 — static};}
357 \end{animate}
358 \end{dispListing}
359 \end{docKey}
360
361 \begin{docKey}[anim]{blink on opacity}{=\meta{value}}{initial: \texttt{1}}
362 Opacity used during the \emph{``on''} (visible) half-periods of a blink.
363 Defaults to \texttt{1} (fully opaque). Independent of \docValue{active opacity}.
364 \end{docKey}
365
366 \begin{docKey}[anim]{blink off opacity}{=\meta{value}}{initial: \texttt{0}}
367 Opacity used during the \emph{``off''} half-periods of the blink oscillation
368 \emph{within the active step}. Defaults to \texttt{0} (fully hidden).
369
370 Between steps the element uses \docValue{inactive opacity} as usual —
371 \docValue{blink off opacity} has no effect outside the active step.
372 To hide a blink element between steps, set \texttt{inactive opacity=0}
373 explicitly; the \docValue{static} key on the \texttt{animate} environment
374 ensures this does not suppress the element in the static display:
375
376 \begin{dispListing}
377 %% Hidden between steps; blinks between 1 (on) and 0.25 (off) during step 2.
378 \begin{animate}[duration=2]
379 \reveal{\node at (0,1) {Step 1};}
380 \animstep
381 \reveal[blink=0.4, inactive opacity=0, blink off opacity=0.25]{%
382 \node[fill=yellow] at (0,0) {Step 2 — dimmed blink};}
383 \animstep
384 \reveal{\node at (0,-1) {Step 3};}
385 \end{animate}
386 \end{dispListing}
387 \end{docKey}
388
389 \begin{docKey}[anim]{static}{(no value)}{default: not set}
390 Renders all \cs{reveal} elements at their natural (full) opacity without
391 emitting any SMIL keyframe animation. Equivalent to drawing all steps
392 simultaneously, which is useful for printed handouts and static overviews.
393
394 This key supersedes the older idiom of setting
395 \texttt{active opacity=1, inactive opacity=1,}
396 \texttt{blink on opacity=1, blink off opacity=1} at the environment level,
397 which failed whenever an element carried an explicit element-level override.
398
399 \begin{dispListing}
400 \begin{animate}[static]
401 \stepOne \animstep \stepTwo \animstep \stepThree
402 \end{animate}
403 \end{dispListing}
404 \end{docKey}
405
406 \begin{docKey}[anim]{step}{=\meta{spec}}{no default}
407 By default \cs{reveal} makes an element visible only during the \emph{current}
408 step (the step in which it appears in the source). The \texttt{step} key
409 overrides this: the element becomes visible during every step listed in
410 \meta{spec}, regardless of its position in the source.
411
412 \medskip
413 \noindent\textbf{Syntax of \meta{spec}:}
414 \begin{itemize}
415 \item Single step — \texttt{step=2}
416 \item Range — \texttt{step=2-5} (steps 2, 3, 4, 5)
417 \item List — \texttt{step=\{1,3\}} (braces required when listing multiple values)
418 \item Mix — \texttt{step=\{1,3-5\}} (braces required)
419 \end{itemize}
420
421 Consecutive steps in the specification are automatically merged into a single
422 animation window (no redundant keyframe at the shared boundary).
423
424 \begin{dispListing}
425 \begin{animate}[inactive opacity=0.08]
426 \reveal[step={1,3}]{\node[red] at (4,1) {visible in steps 1 and 3};}
427 \reveal[step=2-4]{ \node[blue] at (4,0) {visible in steps 2 through 4};}
428 \reveal[step={1,3-5}]{\node at (4,-1) {steps 1, 3, 4, 5};}
429 \end{animate}
430 \end{dispListing}
431 \end{docKey}
432
433 \begin{docKey}[anim]{noanimate}{(no value)}{default: not set}
434 When passed to \cs{reveal}, forces that element to render in PDF mode even
435 when \cs{noanimate} is present in the enclosing \env{animate} body. Has no
436 effect in SVG mode. Useful for elements that should appear in both the
437 animated SVG \emph{and} the static PDF fallback --- for example a transition
438 light that belongs to multiple steps and should also be visible in the PDF
439 snapshot.
440
441 \begin{dispListing}
442 \begin{animate}[inactive opacity=0.08]
443 \noanimate{\fill[red!85!black] (0,2.2) circle[radius=0.85];}
444 \reveal{\fill[green!65!black] (0,-2.2) circle[radius=0.85];}
445 \animstep
446 %% amber is both animated and shown in the PDF static frame
447 \reveal[noanimate]{\fill[orange!90!black] (0,0.0) circle[radius=0.85];}
448 \end{animate}
449 \end{dispListing}
450 \end{docKey}
451
452 %% ─────────────────────────────────────────────────────────────────────────────
453 \subsection{Static PDF output}
454 \label{sec:static}
455
456 The package exposes the boolean flag \texttt{\textbackslash if@anim@svgmode},
457 which is \texttt{true} only when compiling with \texttt{latex} in DVI mode
458 (the SVG pipeline). \cs{reveal} and \cs{noanimate} both query this flag; the
459 logic is summarised below.
460
461 \medskip
462 \begin{center}
463 \begin{tabular}{lcc}
464 \hline
465 & \textbf{SVG} & \textbf{PDF} \\
466 \hline
467 \cs{reveal}\texttt{\{...\}} (no \cs{noanimate} in body) & animated & rendered \\
468 \cs{reveal}\texttt{\{...\}} (\cs{noanimate} present) & animated & suppressed \\
469 \cs{reveal}\texttt{[noanimate]\{...\}} & animated & rendered \\
470 \cs{noanimate}\texttt{\{...\}} & ignored & rendered \\
471 \hline
472 \end{tabular}
473 \end{center}
474 \medskip
475
476 The \env{animate} environment scans its collected body for the token
477 \cs{noanimate} before executing any TikZ code, so the suppression decision is
478 made once per environment instance and does not require two separate document
479 structures.
480
481 %% ─────────────────────────────────────────────────────────────────────────────
482 \section{Example: traffic light}
483
484 The diagram animates a traffic light through four steps. The housing and lens
485 covers are static (always visible at full opacity). The lights are revealed
486 one at a time via \cs{reveal}; when inactive their opacity drops to
487 \texttt{0.08}, simulating an unlit bulb seen through dark glass.
488
489 The sequence demonstrates two features: per-step duration (step~2 lasts only
490 \texttt{0.5~s}) and multiple \cs{reveal} calls in a single step (step~2 shows
491 green and amber simultaneously as a transition):
492
493 \medskip
494 \begin{tabular}{clll}
495 \textbf{Step} & \textbf{Lights} & \textbf{Duration} & \textbf{Meaning} \\
496 \hline
497 1 & green & 1.5\,s & go \\
498 2 & green + amber & 0.5\,s & prepare to stop \\
499 3 & amber & 1.0\,s & caution \\
500 4 & red & 1.5\,s & stop \\
501 \end{tabular}
502 \medskip
503
504 The box below shows the complete \texttt{svg-animate-example.tex} source on the
505 left and the compiled PDF on the right. The \cs{noanimate} call selects the
506 red light as the static PDF frame; open \texttt{svg-animate-example.svg} in a
507 browser for the full animation.
508
509 \tcbinputlisting{
510 listing file = {svg-animate-example.tex},
511 comment = {\centering\includegraphics[width=\linewidth]{svg-animate-example.pdf}},
512 listing side comment,
513 righthand width = 3.2cm,
514 sidebyside gap = 4mm,
515 colback = gray!5,
516 colframe = gray!40,
517 fontupper = \small,
518 }
519
520 %% ─────────────────────────────────────────────────────────────────────────────
521 \section{Change log}
522
523 \begin{description}
524 \item[\normalfont\texttt{v1.1} (2026/04/28)]\leavevmode
525 \begin{itemize}
526 \item Added installation instructions (user-local \texttt{texmf} paths
527 and \texttt{TEXINPUTS}).
528 \item Rewrote the \cs{Ginclude@bitmap} override to detect the
529 \texttt{dvisvgm} version at compile time: the override is now only
530 applied with \texttt{dvisvgm}~$\geq 3.4$, which is the version
531 that added \texttt{--embed-bitmaps} support for
532 \verb|dvisvgm:img| specials.
533 \item Renamed \texttt{example.tex} and \texttt{test.tex} to
534 \texttt{svg-animate-example.tex} and \texttt{svg-animate-test.tex}
535 to avoid filename collisions on shared \TeX{} search paths
536 (CTAN requirement).
537 \end{itemize}
538
539 \item[\normalfont\texttt{v1.0} (2026/03/18)]\leavevmode
540 \begin{itemize}
541 \item Initial CTAN release.
542 \end{itemize}
543 \end{description}
544
545 \end{document}