svganim 0.2.0

Turn a matplotlib figure and a per-frame update function into one self-contained, looping, animated SVG.

Why svganim

• A real image. One SVG file that works in an <img> tag and in GitHub READMEs. No JavaScript, no HTML page, no player.
• Vector. Sharp at any size, unlike a GIF.
• Only what changes is animated. Axes, labels and static data are written once, so files stay small.
• Reproducible. Same code and matplotlib version, same bytes.

What you give up: playback controls, and changes to the number of elements inside an artist, such as text that grows (see Limitations). If you need those, use HTMLWriter or to_jshtml.

Install

pip install svganim

Usage

import matplotlib.pyplot as plt
import numpy as np
from svganim import anim_to_svg

fig, ax = plt.subplots()
x = np.linspace(0, 2 * np.pi, 200)
(line,) = ax.plot(x, np.sin(x))


def update(i):
    line.set_ydata(np.sin(x + i / 10))


anim_to_svg(fig, update, n_frames=60, fps=20, hold=1.0, path="wave.svg")

<img src="wave.svg" alt="A moving sine wave">

In Jupyter and Quarto, end a cell with the call and the animation is displayed, also in the rendered HTML. Call plt.close(fig) first, or the notebook also shows matplotlib's static figure.

update changes the artists (set_data, set_offsets, set_color, ...). A line whose data grows is fine, so draw trails and curves with set_data on a single line. Artists can also come and go: create them once and show or hide them with set_visible.

anim_to_svg(fig, update, n_frames, fps=20, hold=1.0, path=None, *, precision=3, interpolate=False)

Returns the SVG as a string. Raises ValueError if the figure breaks a rule below; the message names the element that changed.

How it works

Each frame is rendered to SVG and the first one becomes the base document. Later frames are compared with it, and every attribute that changes gets a SMIL animation. Elements that never change are left untouched.

Limitations

• Artists can appear and disappear, but the number of SVG elements inside an artist must stay the same: no text that changes length, no axis limits that change the ticks, no imshow.
• There are no playback controls, only a loop.

Examples and docs

The documentation has a gallery of notebooks that explain each example, plus an API reference built from the docstrings. It also shows how animations display in Jupyter and Quarto.

Development

uv run pytest
# the browser tests render every frame in Chromium, and are skipped without it
uv run --group browser playwright install chromium-headless-shell
uv run --group browser pytest tests/test_browser.py
uv run sphinx-build -W docs docs/_build/html

License

MIT