<divid="unreleased-message"> You are reading an old version of the documentation (v3.3.0). 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="matplotlib-animation"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.animation</span></code><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 <aclass="reference internal" href="artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Artist</span></code></a> 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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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">
<spanid="func-animation"></span><h3><codeclass="docutils literal notranslate"><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 notranslate"><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">standard 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 we use blitting (by passing <codeclass="docutils literal notranslate"><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 notranslate"><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 notranslate"><spanclass="pre">init_func</span></code>
and <codeclass="docutils literal notranslate"><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 notranslate"><spanclass="pre">FuncAnimation</span></code></a> and the theory of how
'blitting' works.</p>
<p>The expected signature on <codeclass="docutils literal notranslate"><spanclass="pre">func</span></code> and <codeclass="docutils literal notranslate"><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 notranslate"><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 use <aclass="reference external" href="https://docs.python.org/3/library/functools.html#functools.partial" title="(in Python v3.8)"><codeclass="xref py py-obj docutils literal notranslate"><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 notranslate"><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>
<divclass="toctree-wrapper compound">
<ul>
<liclass="toctree-l1"><aclass="reference internal" href="../gallery/animation/dynamic_image.html">Animated image using a precomputed list of images</a></li>
</ul>
</div>
</div>
</div>
</div>
<divclass="section" id="writer-classes">
<h2><aclass="toc-backref" href="#id4">Writer Classes</a><aclass="headerlink" href="#writer-classes" title="Permalink to this headline">¶</a></h2>
<p>The provided writers fall into a few broad categories.</p>
<p>The Pillow writer relies on the Pillow library to write the animation, keeping
<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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><spanclass="pre">setup</span></code> methods.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">setup()</span></code> method is used to prepare the writer (possibly opening
a pipe), successive calls to <codeclass="docutils literal notranslate"><spanclass="pre">grab_frame()</span></code> capture a single frame
at a time and <codeclass="docutils literal notranslate"><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 notranslate"><spanclass="pre">Animation.save</span></code></a>), it is
strongly encouraged to use the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">saving</span></code> context manager</p>
<spanid="ani-writer-classes"></span><h2><aclass="toc-backref" href="#id5">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 notranslate"><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 notranslate"><spanclass="pre">MovieWriter</span></code></a> classes.</p>
</div>
</div>
<divclass="section" id="inheritance-diagrams">
<h2><aclass="toc-backref" href="#id6">Inheritance Diagrams</a><aclass="headerlink" href="#inheritance-diagrams" title="Permalink to this headline">¶</a></h2>
<divclass="graphviz"><imgsrc="../_images/inheritance-17f6bb8a86dccb6f6064b90758fa11f4fb9d1f45.png" alt="Inheritance diagram of matplotlib.animation.FuncAnimation, matplotlib.animation.ArtistAnimation" usemap="#inheritancece9d8276cb" class="inheritance graphviz" /></div>
<areashape="rect" id="node1" href="_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation" target="_top" title="A base class for Animations." alt="" coords="5,35,137,69"/>
<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="432,5,621,40"/>
<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="435,64,618,99"/>
<areashape="rect" id="node8" 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="65,47,190,65"/>
<areashape="rect" id="node2" href="_as_gen/matplotlib.animation.AVConvBase.html#matplotlib.animation.AVConvBase" target="_top" title="[*Deprecated*] Mixin class for avconv output." alt="" coords="523,77,605,95"/>
<areashape="rect" id="node10" href="_as_gen/matplotlib.animation.MovieWriter.html#matplotlib.animation.MovieWriter" target="_top" title="Base class for writing movies." alt="" coords="231,47,310,65"/>
<areashape="rect" id="node9" 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="363,47,459,65"/>