<divid="unreleased-message"> You are reading an old version of the documentation (v2.1.2). For the latest version see <ahref="https://matplotlib.org/stable/api/animation_api.html">https://matplotlib.org/stable/api/animation_api.html</a></div>
<spanid="animation-module"></span><h1><codeclass="docutils literal"><spanclass="pre">animation</span></code> module<aclass="headerlink" href="#module-matplotlib.animation" title="Permalink to this headline">¶</a></h1>
<divclass="contents local topic" id="table-of-contents">
<td>Animation using a fixed set of <codeclass="xref py py-obj docutils literal"><spanclass="pre">Artist</span></code> objects.</td>
</tr>
</tbody>
</table>
<p>In both cases it is critical to keep a reference to the instance
object. The animation is advanced by a timer (typically from the host
GUI framework) which the <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation" title="matplotlib.animation.Animation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Animation</span></code></a> object holds the only reference
to. If you do not hold a reference to the <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation" title="matplotlib.animation.Animation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Animation</span></code></a> object, it (and
hence the timers), will be garbage collected which will stop the
animation.</p>
<p>To save an animation to disk use <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation.save" title="matplotlib.animation.Animation.save"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Animation.save</span></code></a> or <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation.to_html5_video" title="matplotlib.animation.Animation.to_html5_video"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Animation.to_html5_video</span></code></a></p>
<p>See <aclass="reference internal" href="#ani-writer-classes"><spanclass="std std-ref">Helper Classes</span></a> below for details about what movie formats are
supported.</p>
<divclass="section" id="funcanimation">
<h3><codeclass="docutils literal"><spanclass="pre">FuncAnimation</span></code><aclass="headerlink" href="#funcanimation" title="Permalink to this headline">¶</a></h3>
<p>The inner workings of <aclass="reference internal" href="_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation" title="matplotlib.animation.FuncAnimation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">FuncAnimation</span></code></a> is more-or-less:</p>
<p>with details to handle ‘blitting’ (to dramatically improve the live
performance), to be non-blocking, not repeatedly start/stop the GUI
event loop, handle repeats, multiple animated axes, and easily save
the animation to a movie file.</p>
<p>‘Blitting’ is a <aclass="reference external" href="https://en.wikipedia.org/wiki/Bit_blit">old technique</a> in computer graphics. The
general gist is to take an existing bit map (in our case a mostly
rasterized figure) and then ‘blit’ one more artist on top. Thus, by
managing a saved ‘clean’ bitmap, we can only re-draw the few artists
that are changing at each frame and possibly save significant amounts of
time. When using blitting (by passing <codeclass="docutils literal"><spanclass="pre">blit=True</span></code>) the core loop of
<aclass="reference internal" href="_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation" title="matplotlib.animation.FuncAnimation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">FuncAnimation</span></code></a> gets a bit more complicated</p>
<p>This is of course leaving out many details (such as updating the
background when the figure is resized or fully re-drawn). However,
this hopefully minimalist example gives a sense of how <codeclass="docutils literal"><spanclass="pre">init_func</span></code>
and <codeclass="docutils literal"><spanclass="pre">func</span></code> are used inside of <aclass="reference internal" href="_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation" title="matplotlib.animation.FuncAnimation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">FuncAnimation</span></code></a> and the theory of how
‘blitting’ works.</p>
<p>The expected signature on <codeclass="docutils literal"><spanclass="pre">func</span></code> and <codeclass="docutils literal"><spanclass="pre">init_func</span></code> is very simple to
keep <aclass="reference internal" href="_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation" title="matplotlib.animation.FuncAnimation"><codeclass="xref py py-obj docutils literal"><spanclass="pre">FuncAnimation</span></code></a> out of your book keeping and plotting logic, but
this means that the callable objects you pass in must know what
artists they should be working on. There are several approaches to
handling this, of varying complexity and encapsulation. The simplest
approach, which works quite well in the case of a script, is to define the
artist at a global scope and let Python sort things out. For example</p>
<p>The second method is to us <aclass="reference external" href="https://docs.python.org/3/library/functools.html#functools.partial" title="(in Python v3.6)"><codeclass="xref py py-obj docutils literal"><spanclass="pre">functools.partial</span></code></a> to ‘bind’ artists to
function. A third method is to use closures to build up the required
artists and functions. A fourth method is to create a class.</p>
<divclass="section" id="examples">
<h4>Examples<aclass="headerlink" href="#examples" title="Permalink to this headline">¶</a></h4>
<h3><codeclass="docutils literal"><spanclass="pre">ArtistAnimation</span></code><aclass="headerlink" href="#artistanimation" title="Permalink to this headline">¶</a></h3>
<divclass="section" id="id1">
<h4>Examples<aclass="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
<p>Fundamentally, a <aclass="reference internal" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" title="matplotlib.animation.MovieWriter"><codeclass="xref py py-obj docutils literal"><spanclass="pre">MovieWriter</span></code></a> provides a way to grab sequential frames
from the same underlying <aclass="reference internal" href="_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Figure</span></code></a> object. The base
class <aclass="reference internal" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" title="matplotlib.animation.MovieWriter"><codeclass="xref py py-obj docutils literal"><spanclass="pre">MovieWriter</span></code></a> implements 3 methods and a context manager. The
only difference between the pipe-based and file-based writers is in the
arguments to their respective <codeclass="docutils literal"><spanclass="pre">setup</span></code> methods.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">setup()</span></code> method is used to prepare the writer (possibly opening
a pipe), successive calls to <codeclass="docutils literal"><spanclass="pre">grab_frame()</span></code> capture a single frame
at a time and <codeclass="docutils literal"><spanclass="pre">finish()</span></code> finalizes the movie and writes the output
<p>If using the writer classes directly (not through <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation.save" title="matplotlib.animation.Animation.save"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Animation.save</span></code></a>), it is strongly encouraged
to use the <codeclass="xref py py-obj docutils literal"><spanclass="pre">saving</span></code> context manager</p>
<spanid="ani-writer-classes"></span><h2><aclass="toc-backref" href="#id4">Helper Classes</a><aclass="headerlink" href="#helper-classes" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="animation-base-classes">
<h3>Animation Base Classes<aclass="headerlink" href="#animation-base-classes" title="Permalink to this headline">¶</a></h3>
<td><aclass="reference internal" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" title="matplotlib.animation.MovieWriter"><codeclass="xref py py-obj docutils literal"><spanclass="pre">MovieWriter</span></code></a> for writing to individual files and stitching at the end.</td>
<p>See the source code for how to easily implement new <aclass="reference internal" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" title="matplotlib.animation.MovieWriter"><codeclass="xref py py-obj docutils literal"><spanclass="pre">MovieWriter</span></code></a>
classes.</p>
</div>
</div>
<divclass="section" id="inheritance-diagrams">
<h2><aclass="toc-backref" href="#id5">Inheritance Diagrams</a><aclass="headerlink" href="#inheritance-diagrams" title="Permalink to this headline">¶</a></h2>
<imgsrc="../_images/inheritance-3d770d91db12b7ba71313f03e0382aa6506036be.png" alt="Inheritance diagram of matplotlib.animation.FuncAnimation, matplotlib.animation.ArtistAnimation" usemap="#inheritance95f52c58c5" class="inheritance"/>
<areashape="rect" id="node1" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation" target="_top" title="This class wraps the creation of an animation using matplotlib." alt="" coords="5,27,208,49"/>
<areashape="rect" id="node2" href="_as_gen/matplotlib.animation.ArtistAnimation.html#matplotlib.animation.ArtistAnimation" target="_top" title="Animation using a fixed set of `Artist` objects." alt="" coords="530,5,763,27"/>
<areashape="rect" id="node4" href="_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation" target="_top" title="Makes an animation by repeatedly calling a function ``func``." alt="" coords="533,48,760,70"/>
<areashape="rect" id="node7" href="_as_gen/matplotlib.animation.AbstractMovieWriter.html#matplotlib.animation.AbstractMovieWriter" target="_top" title="Abstract base class for writing movies. Fundamentally, what a MovieWriter" alt="" coords="2,48,139,60"/>
<areashape="rect" id="node9" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" target="_top" title="Base class for writing movies." alt="" coords="171,48,283,60"/>
<areashape="rect" id="node8" href="_as_gen/matplotlib.animation.FileMovieWriter.html#matplotlib.animation.FileMovieWriter" target="_top" title="`MovieWriter` for writing to individual files and stitching at the end." alt="" coords="321,48,443,60"/>