svganim 0.1.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. For the same 60-frame figure we got 91 KiB, against 1.1 MiB from matplotlib's HTMLWriter with SVG frames.
• Reproducible. Same code and matplotlib version, same bytes.

What you give up: playback controls, and changes to the number of elements or the text between frames (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">

update must change artists that already exist (set_data, set_offsets, set_color, ...), not create or remove them. A line whose data grows is fine, so draw trails and curves with set_data on a single line.

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

• The number of SVG elements must be the same in every frame: no new artists, no changing text, 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
uv run sphinx-build -W docs docs/_build/html

License

MIT