Skip to content

Commit e465fb7

Browse files
tacaswelltacaswell
committed
DOC: start to add animation prose
1 parent 24c7aad commit e465fb7

File tree

1 file changed

+161
-1
lines changed

1 file changed

+161
-1
lines changed

‎doc/api/animation_api.rst

+161-1
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,170 @@
22
``animation`` module
33
======================
44

5-
.. currentmodule:: matplotlib.animation
5+
.. automodule:: matplotlib.animation
6+
7+
.. contents:: Table of Contents
8+
:depth: 1
9+
:local:
10+
:backlinks: entry
611

712

813
Animation
914
=========
1015

16+
The easiest way to make a live animation in mpl is to use one of the
17+
`Animation` classes.
18+
1119
.. autosummary::
1220
:toctree: _as_gen
1321
:nosignatures:
1422

1523
FuncAnimation
1624
ArtistAnimation
25+
26+
In both cases it is critical to keep a reference to tho instance
27+
object. The animation is advanced by a timer (typically from the host
28+
GUI framework) which the `Animation` object holds the only reference
29+
to. If you do not hold a reference to the `Animation` object, it (and
30+
hence the timers), will be garbage collected which will stop the
31+
animation.
32+
33+
To save an animation use to disk use
34+
35+
.. autosummary::
36+
:toctree: _as_gen
37+
:nosignatures:
38+
1739
Animation.save
40+
Animation.to_html5_video
41+
42+
See :ref:`ani_writer_classes` below for details about what movie formats are supported.
43+
44+
45+
``FuncAnimation``
46+
-----------------
47+
48+
The inner workings of `FuncAnimation` is more-or-less::
49+
50+
for d in frames:
51+
arts = func(d, *fargs)
52+
fig.canvas.draw_idle()
53+
plt.pause(interval)
54+
55+
56+
with details to handle 'blitting' (to dramatically improve the live
57+
performance), to be non-blocking, handle repeats, multiple animated
58+
axes, and easily save the animation to a movie file.
59+
60+
'Blitting' is a `old technique
61+
<https://en.wikipedia.org/wiki/Bit_blit>`__ in computer graphics. The
62+
general gist is to take as existing bit map (in our case a mostly
63+
rasterized figure) and then 'blit' one more artist on top. Thus, by
64+
managing a saved 'clean' bitmap, we can only re-draw the few artists
65+
that are changing at each frame and possibly save significant amounts of
66+
time. When using blitting (by passing ``blit=True``) the core loop of
67+
`FuncAnimation` gets a bit more complicated ::
68+
69+
ax = fig.gca()
70+
71+
def update_blit(arts):
72+
fig.canvas.restore_region(bg_cache)
73+
for a in arts:
74+
a.axes.draw_artist(a)
75+
76+
ax.figure.canvas.blit(ax.bbox)
77+
78+
arts = init_func()
79+
80+
for a in arts:
81+
a.set_animated(True)
82+
83+
fig.canvas.draw()
84+
bg_cache = fig.canvas.copy_from_bbox(ax.bbox)
85+
86+
for f in frames:
87+
arts = func(f, *fargs)
88+
update_blit(arts)
89+
plt.pause(interval)
90+
91+
This is of course leaving out many details (such as updating the
92+
background when the figure is resized or fully re-drawn). However,
93+
this hopefully minimalist example gives a sense of how ``init_func``
94+
and ``func`` are used inside of `FuncAnimation` and the theory of how
95+
'blitting' works.
96+
97+
The expected signature on ``func`` and ``init_func`` is very simple to
98+
keep `FuncAnimation` out of your book keeping and plotting logic, but
99+
this means that the callable objects you pass in must know what
100+
artists they should be working on. There are several approaches to
101+
handling this, of varying complexity and encapsulation. The simplest
102+
approach, which works quite well in the case of a script, is to define the
103+
artist at a global scope and let Python sort things out. For example ::
104+
105+
import numpy as np
106+
import matplotlib.pyplot as plt
107+
from matplotlib.animation import FuncAnimation
108+
109+
fig, ax = plt.subplots()
110+
xdata, ydata = [], []
111+
ln, = plt.plot([], [], 'ro', animated=True)
112+
113+
def init():
114+
ax.set_xlim(0, 2*np.pi)
115+
ax.set_ylim(-1, 1)
116+
return ln,
117+
118+
def update(i):
119+
xdata.append(i)
120+
ydata.append(np.sin(i))
121+
ln.set_data(xdata, ydata)
122+
return ln,
123+
124+
ani = FuncAnimation(fig, update, frames=np.linspace(0, 2*np.pi, 128),
125+
init_func=init, blit=True)
126+
plt.show()
127+
128+
129+
The second method is to us `functools.partial` to 'bind' artists to
130+
function. A third method is to use closures to build up the required
131+
artists and functions. A forth method is to create a class.
132+
133+
134+
135+
136+
Examples
137+
~~~~~~~~
138+
139+
.. toctree::
140+
:maxdepth: 1
141+
142+
../examples/animation/animate_decay
143+
../examples/animation/bayes_update
144+
../examples/animation/double_pendulum_animated
145+
../examples/animation/dynamic_image
146+
../examples/animation/histogram
147+
../examples/animation/rain
148+
../examples/animation/random_data
149+
../examples/animation/simple_3danim
150+
../examples/animation/simple_anim
151+
../examples/animation/strip_chart_demo
152+
../examples/animation/unchained
153+
154+
``ArtistAnimation``
155+
-------------------
156+
157+
158+
Examples
159+
~~~~~~~~
160+
161+
.. toctree::
162+
:maxdepth: 1
163+
164+
../examples/animation/basic_example
165+
../examples/animation/basic_example_writer
166+
../examples/animation/dynamic_image2
167+
168+
18169

19170

20171
Writer Classes
@@ -33,6 +184,10 @@ Writer Classes
33184
ImageMagickFileWriter
34185
ImageMagickWriter
35186

187+
:ref:`animation-moviewriter`
188+
189+
190+
.. _ani_writer_classes:
36191

37192
Helper Classes
38193
==============
@@ -50,6 +205,11 @@ Animation Base Classes
50205
TimedAnimation
51206

52207

208+
Custom Animation classes
209+
------------------------
210+
211+
:ref:`animation-subplots`
212+
53213
Writer Registry
54214
---------------
55215

0 commit comments

Comments
 (0)