<divid="unreleased-message"> You are reading an old version of the documentation (v2.0.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="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
<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, 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 <codeclass="xref py py-obj docutils literal"><spanclass="pre">functools.partial</span></code> 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>
<divclass="toctree-wrapper compound">
<ul>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/animate_decay.html">animation example code: animate_decay.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/bayes_update.html">animation example code: bayes_update.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/double_pendulum_animated.html">animation example code: double_pendulum_animated.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/dynamic_image.html">animation example code: dynamic_image.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/histogram.html">animation example code: histogram.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/rain.html">animation example code: rain.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/random_data.html">animation example code: random_data.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/simple_3danim.html">animation example code: simple_3danim.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/simple_anim.html">animation example code: simple_anim.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/strip_chart_demo.html">animation example code: strip_chart_demo.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/unchained.html">animation example code: unchained.py</a></li>
</ul>
</div>
</div>
</div>
<divclass="section" id="artistanimation">
<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>
<divclass="toctree-wrapper compound">
<ul>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/basic_example.html">animation example code: basic_example.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/basic_example_writer.html">animation example code: basic_example_writer.py</a></li>
<liclass="toctree-l1"><aclass="reference internal" href="../examples/animation/dynamic_image2.html">animation example code: dynamic_image2.py</a></li>
</ul>
</div>
</div>
</div>
</div>
<divclass="section" id="writer-classes">
<h2><aclass="toc-backref" href="#id3">Writer Classes</a><aclass="headerlink" href="#writer-classes" title="Permalink to this headline">¶</a></h2>
<p>The provided writers fall into two broad categories: pipe-based and
file-based. The pipe-based writers stream the captured frames over a
pipe to an external process. The pipe-based variants tend to be more
<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="figure_api.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>If using the writer classes directly (not through <aclass="reference internal" href="_as_gen/matplotlib.animation.Animation.save.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 <aclass="reference internal" href="_as_gen/matplotlib.animation.MovieWriter.saving.html#matplotlib.animation.MovieWriter.saving" title="matplotlib.animation.MovieWriter.saving"><codeclass="xref py py-obj docutils literal"><spanclass="pre">saving</span></code></a> context manager</p>
<p>to ensures that setup and cleanup are performed as necessary.</p>
<p><aclass="reference internal" href="../examples/animation/moviewriter.html#animation-moviewriter"><spanclass="std std-ref">animation example code: moviewriter.py</span></a></p>
</div>
<divclass="section" id="helper-classes">
<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.FileMovieWriter.html#matplotlib.animation.FileMovieWriter" target="_top" title="`MovieWriter` for writing to individual files and stitching at the end." alt="" coords="204,61,358,76"/>