Source code for mpltools.animation

Animation class.

This implementation is a interface for Matplotlib's FuncAnimation class, but
with different interface for:

* Easy reuse of animation code.

* Logical separation of setup parameter (passed to `__init__`) and animation
  parameters (passed to `animate`).

* Unlike Matplotlib's animation class, this Animation class clearly must be
  assigned to a variable (in order to call the `animate` method). The
  FuncAnimation object needs to be assigned to a variable so that it isn't
  garbage-collected, but this requirement is confusing, and easily forgotten,
  because the user never uses the animation object directly.

import warnings
import matplotlib.animation as _animation

__all__ = ['Animation']

[docs]class Animation(object): """Base class to create animation objects. To create an animation, simply subclass `Animation` and override the `__init__` method to create a plot (`self.fig` needs to be assigned to the figure object here), and override `update` with a generator that updates the plot: .. code-block:: python class RandomPoints(Animation): def __init__(self, width=10): self.fig, = plt.subplots() self.width = width[0, width, 0, width]) self.num_frames = 20 def update(self): artists = [] = [] # Clean up plot when repeating animation. for i in np.arange(self.num_frames): x, y = np.random.uniform(0, self.width, size=2) artists.append(, y, 'ro')) yield artists pts = RandomPoints() pts.animate() Note: if you want to use blitting (see docstring for `Animation.animate`), You must yield a sequence of artists in `update`. This Animation class does not subclass any of Matplotlib's animation classes because the `__init__` method takes arguments for creating the plot, while `animate` method is what accepts arguments that alter the animation. """
[docs] def __init__(self): """Initialize plot for animation. Replace this method to initialize the plot. The only requirement is that you must create a figure object assigned to `self.fig`. """ raise NotImplementedError
[docs] def init_background(self): """Initialize background artists. Note: This method is passed to `FuncAnimation` as `init_func`. """ pass
[docs] def update(self): """Update frame. Replace this method to with a generator that updates artists and calls an empty `yield` when updates are complete. """ raise NotImplementedError
[docs] def animate(self, **kwargs): """Run animation. Parameters ---------- interval : float, defaults to 200 Time delay, in milliseconds, between frames. repeat : {True | False} If True, repeat animation when the sequence of frames is completed. repeat_delay : None Delay in milliseconds before repeating the animation. blit : {False | True} If True, use blitting to optimize drawing. Unsupported by some backends. init_background : function If None, the results of drawing from the first item in the frames sequence will be used. This can also be added as a class method instead of passing to `animate`. save_count : int If saving a movie, `save_count` determines number of frames saved. If not defined, use `num_frames` attribute (if defined); otherwise, set to 100 frames. """ reusable_generator = lambda: iter(self.update()) kwargs['init_background'] = self.init_background self._warn_num_frames = False if hasattr(self, 'num_frames') and 'save_count' not in kwargs: kwargs['save_count'] = self.num_frames if 'save_count' not in kwargs: kwargs['save_count'] = 100 self._warn_num_frames = True self._ani = _GenAnimation(self.fig, reusable_generator, **kwargs)
[docs] def save(self, filename, **kwargs): """Saves a movie file by drawing every frame. Parameters ---------- filename : str The output filename. writer : :class:`matplotlib.animation.MovieWriter` or str Class for writing movie from animation. If string, must be 'ffmpeg' or 'mencoder', which identifies the MovieWriter class used. If None, use 'animation.writer' rcparam. fps : float The frames per second in the movie. If None, use the animation's specified `interval` to set the frames per second. dpi : int Dots per inch for the movie frames. codec : Video codec to be used. Not all codecs are supported by a given writer. If None, use 'animation.codec' rcparam. bitrate : int Kilobits per seconds in the movie compressed movie. A higher value gives a higher quality movie, but at the cost of increased file size. If None, use `animation.bitrate` rcparam. extra_args : list List of extra string arguments passed to the underlying movie utility. If None, use 'animation.extra_args' rcParam. metadata : dict Metadata to include in the output file. Some keys that may be of use include: title, artist, genre, subject, copyright, comment. """ if not hasattr(self, '_ani'): raise RuntimeError("Run `animate` method before calling `save`!") return if self._warn_num_frames: msg = "%s `num_frames` attribute. Animation may be truncated." warnings.warn(msg % self.__class__.__name__), **kwargs)
class _GenAnimation(_animation.FuncAnimation): def __init__(self, fig, frames, init_background=None, save_count=None, **kwargs): self._iter_gen = frames self._init_func = init_background self.save_count = save_count if save_count is not None else 100 # Dummy args and function for compatibility with FuncAnimation self._args = () self._func = lambda args: args self._save_seq = [] _animation.TimedAnimation.__init__(self, fig, **kwargs) # Clear saved seq since TimedAnimation.__init__ adds a single frame. self._save_seq = []