diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst index d43dc351abae..3519bca48c23 100644 --- a/doc/api/animation_api.rst +++ b/doc/api/animation_api.rst @@ -1,12 +1,332 @@ -********* -animation -********* +====================== + ``animation`` module +====================== +.. automodule:: matplotlib.animation -:mod:`matplotlib.animation` -=========================== +.. contents:: Table of Contents + :depth: 1 + :local: + :backlinks: entry -.. automodule:: matplotlib.animation - :members: - :undoc-members: - :show-inheritance: + +Animation +========= + +The easiest way to make a live animation in matplotlib is to use one of the +`Animation` classes. + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + FuncAnimation + ArtistAnimation + +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 `Animation` object holds the only reference +to. If you do not hold a reference to the `Animation` object, it (and +hence the timers), will be garbage collected which will stop the +animation. + +To save an animation to disk use + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + Animation.save + Animation.to_html5_video + +See :ref:`ani_writer_classes` below for details about what movie formats are supported. + + +``FuncAnimation`` +----------------- + +The inner workings of `FuncAnimation` is more-or-less:: + + for d in frames: + artists = func(d, *fargs) + fig.canvas.draw_idle() + plt.pause(interval) + + +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. + +'Blitting' is a `old technique +`__ 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 ``blit=True``) the core loop of +`FuncAnimation` gets a bit more complicated :: + + ax = fig.gca() + + def update_blit(artists): + fig.canvas.restore_region(bg_cache) + for a in artists: + a.axes.draw_artist(a) + + ax.figure.canvas.blit(ax.bbox) + + artists = init_func() + + for a in artists: + a.set_animated(True) + + fig.canvas.draw() + bg_cache = fig.canvas.copy_from_bbox(ax.bbox) + + for f in frames: + artists = func(f, *fargs) + update_blit(artists) + plt.pause(interval) + +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 ``init_func`` +and ``func`` are used inside of `FuncAnimation` and the theory of how +'blitting' works. + +The expected signature on ``func`` and ``init_func`` is very simple to +keep `FuncAnimation` 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 :: + + import numpy as np + import matplotlib.pyplot as plt + from matplotlib.animation import FuncAnimation + + fig, ax = plt.subplots() + xdata, ydata = [], [] + ln, = plt.plot([], [], 'ro', animated=True) + + def init(): + ax.set_xlim(0, 2*np.pi) + ax.set_ylim(-1, 1) + return ln, + + def update(frame): + xdata.append(frame) + ydata.append(np.sin(frame)) + ln.set_data(xdata, ydata) + return ln, + + ani = FuncAnimation(fig, update, frames=np.linspace(0, 2*np.pi, 128), + init_func=init, blit=True) + plt.show() + + +The second method is to us `functools.partial` 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. + + + + +Examples +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + ../examples/animation/animate_decay + ../examples/animation/bayes_update + ../examples/animation/double_pendulum_animated + ../examples/animation/dynamic_image + ../examples/animation/histogram + ../examples/animation/rain + ../examples/animation/random_data + ../examples/animation/simple_3danim + ../examples/animation/simple_anim + ../examples/animation/strip_chart_demo + ../examples/animation/unchained + +``ArtistAnimation`` +------------------- + + +Examples +~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + ../examples/animation/basic_example + ../examples/animation/basic_example_writer + ../examples/animation/dynamic_image2 + + + + +Writer Classes +============== + + + +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 +performant, but may not work on all systems. + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + + FFMpegWriter + ImageMagickFileWriter + AVConvWriter + +Alternatively the file-based writers save temporary files for each +frame which are stitched into a single file at the end. Although +slower, these writers can be easier to debug. + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + FFMpegFileWriter + ImageMagickWriter + AVConvFileWriter + + +Fundamentally, a `MovieWriter` provides a way to grab sequential frames +from the same underlying `~matplotlib.figure.Figure` object. The base +class `MovieWriter` 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 ``setup`` methods. + + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + MovieWriter.setup + FileMovieWriter.setup + MovieWriter.grab_frame + MovieWriter.finish + MovieWriter.saving + + +The ``setup()`` method is used to prepare the writer (possibly opening +a pipe), successive calls to ``grab_frame()`` capture a single frame +at a time and ``finish()`` finalizes the movie and writes the output +file to disk. For example :: + + moviewriter = MovieWriter(...) + moviewriter.setup(fig=fig, 'my_movie.ext', dpi=100) + for j in range(n): + update_figure(n) + moviewriter.grab_frame() + moviewriter.finish() + + +If using the writer classes directly (not through `Animation.save`), it is strongly encouraged +to use the `~MovieWriter.saving` context manager :: + + with moviewriter.saving(fig, 'myfile.mp4', dpi=100): + for j in range(n): + update_figure(n) + moviewriter.grab_frame() + + +to ensures that setup and cleanup are performed as necessary. + + +:ref:`animation-moviewriter` + + +.. _ani_writer_classes: + +Helper Classes +============== + + +Animation Base Classes +---------------------- + + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + Animation + TimedAnimation + + +Custom Animation classes +------------------------ + +:ref:`animation-subplots` + +Writer Registry +--------------- + +A module-level registry is provided to map between the name of the +writer and the class to allow a string to be passed to +`Animation.save` instead of a writer instance. + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + MovieWriterRegistry + +Writer Base Classes +------------------- + +To reduce code duplication base classes + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + MovieWriter + FileMovieWriter + +and mixins are provided + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + AVConvBase + FFMpegBase + ImageMagickBase + +See the source code for how to easily implement new `MovieWriter` +classes. + + +Inheritance Diagrams +==================== + +.. inheritance-diagram:: matplotlib.animation.FuncAnimation matplotlib.animation.ArtistAnimation + :private-bases: + +.. inheritance-diagram:: matplotlib.animation.AVConvFileWriter matplotlib.animation.AVConvWriter matplotlib.animation.FFMpegFileWriter matplotlib.animation.FFMpegWriter matplotlib.animation.ImageMagickFileWriter matplotlib.animation.ImageMagickWriter + :private-bases: + + + +Deprecated +========== + + +.. autosummary:: + :toctree: _as_gen + :nosignatures: + + MencoderBase + MencoderFileWriter + MencoderWriter diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py index b4f1b77bb967..7588dcd41ca5 100644 --- a/lib/matplotlib/animation.py +++ b/lib/matplotlib/animation.py @@ -68,6 +68,7 @@ def adjusted_figsize(w, h, dpi, n): # A registry for available MovieWriter classes class MovieWriterRegistry(object): + '''Registry of available writer classes by human readable name.''' def __init__(self): self.avail = dict() self._registered = dict() @@ -109,6 +110,16 @@ def list(self): return list(self.avail.keys()) def is_available(self, name): + '''Check if given writer is available by name. + + Parameters + ---------- + name : str + + Returns + ------- + available : bool + ''' self.ensure_not_dirty() return name in self.avail @@ -122,29 +133,29 @@ def __getitem__(self, name): class MovieWriter(object): - ''' - Base class for writing movies. Fundamentally, what a MovieWriter does - is provide is a way to grab frames by calling grab_frame(). setup() - is called to start the process and finish() is called afterwards. - This class is set up to provide for writing movie frame data to a pipe. - saving() is provided as a context manager to facilitate this process as:: + '''Base class for writing movies. - with moviewriter.saving('myfile.mp4'): - # Iterate over frames - moviewriter.grab_frame() + This class is set up to provide for writing movie frame data to a + pipe. See examples for how to use these classes. - The use of the context manager ensures that setup and cleanup are - performed as necessary. + Attributes + ---------- - frame_format: string + frame_format : str The format used in writing frame data, defaults to 'rgba' + + fig : `~matplotlib.figure.Figure` + The figure to capture data from. + This must be provided by the sub-classes. + ''' def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None, metadata=None): - ''' - Construct a new MovieWriter object. + '''MovieWriter + Parameters + ---------- fps: int Framerate for movie. codec: string or None, optional @@ -210,11 +221,14 @@ def setup(self, fig, outfile, dpi): ''' Perform setup for writing the movie file. - fig: `matplotlib.Figure` instance + Parameters + ---------- + + fig : `matplotlib.Figure` instance The figure object that contains the information for frames - outfile: string + outfile : string The filename of the resulting movie file - dpi: int + dpi : int The DPI (or resolution) for the file. This controls the size in pixels of the resulting movie file. ''' @@ -262,6 +276,7 @@ def finish(self): def grab_frame(self, **savefig_kwargs): ''' Grab the image information from the figure and save as a movie frame. + All keyword arguments in savefig_kwargs are passed on to the 'savefig' command that saves the figure. ''' @@ -329,29 +344,34 @@ def isAvailable(cls): class FileMovieWriter(MovieWriter): - '`MovieWriter` subclass that handles writing to a file.' + '''`MovieWriter` for writing to individual files and stitching at the end. + This must be sub-classed to be useful. + ''' def __init__(self, *args, **kwargs): MovieWriter.__init__(self, *args, **kwargs) self.frame_format = rcParams['animation.frame_format'] def setup(self, fig, outfile, dpi, frame_prefix='_tmp', clear_temp=True): - ''' - Perform setup for writing the movie file. + '''Perform setup for writing the movie file. + + Parameters + ---------- + fig : matplotlib.figure.Figure + The figure to grab the rendered frames from. + outfile : str + The filename of the resulting movie file. + dpi : number + The dpi of the output file. This, with the figure size, + controls the size in pixels of the resulting movie file. + frame_prefix : str, optional + The filename prefix to use for temporary files. Defaults to + '_tmp'. + clear_temp : bool, optional + If the temporary files should be deleted after stitching + the final result. Setting this to `False` can be useful for + debugging. Defaults to `True`. - fig: `matplotlib.Figure` instance - The figure object that contains the information for frames - outfile: string - The filename of the resulting movie file - dpi: int - The DPI (or resolution) for the file. This controls the size - in pixels of the resulting movie file. - frame_prefix: string, optional - The filename prefix to use for the temporary files. Defaults - to '_tmp' - clear_temp: bool - Specifies whether the temporary files should be deleted after - the movie is written. (Useful for debugging.) Defaults to True. ''' self.fig = fig self.outfile = outfile @@ -463,6 +483,12 @@ def cleanup(self): # Base class of ffmpeg information. Has the config keys and the common set # of arguments that controls the *output* side of things. class FFMpegBase(object): + '''Mixin class for FFMpeg output. + + To be useful this must be multiply-inherited from with a + `MovieWriterBase` sub-class. + ''' + exec_key = 'animation.ffmpeg_path' args_key = 'animation.ffmpeg_args' @@ -490,6 +516,11 @@ def output_args(self): # Combine FFMpeg options with pipe-based writing @writers.register('ffmpeg') class FFMpegWriter(MovieWriter, FFMpegBase): + '''Pipe-based ffmpeg writer. + + Frames are streamed directly to ffmpeg via a pipe and written in a single + pass. + ''' def _args(self): # Returns the command line parameters for subprocess to use # ffmpeg to create a movie using a pipe. @@ -506,6 +537,12 @@ def _args(self): # Combine FFMpeg options with temp file-based writing @writers.register('ffmpeg_file') class FFMpegFileWriter(FileMovieWriter, FFMpegBase): + '''File-based ffmpeg writer. + + Frames are written to temporary files on disk and then stitched + together at the end. + + ''' supported_formats = ['png', 'jpeg', 'ppm', 'tiff', 'sgi', 'bmp', 'pbm', 'raw', 'rgba'] @@ -520,6 +557,12 @@ def _args(self): # Base class of avconv information. AVConv has identical arguments to # FFMpeg class AVConvBase(FFMpegBase): + '''Mixin class for avconv output. + + To be useful this must be multiply-inherited from with a + `MovieWriterBase` sub-class. + ''' + exec_key = 'animation.avconv_path' args_key = 'animation.avconv_args' @@ -527,13 +570,22 @@ class AVConvBase(FFMpegBase): # Combine AVConv options with pipe-based writing @writers.register('avconv') class AVConvWriter(AVConvBase, FFMpegWriter): - pass + '''Pipe-based avconv writer. + + Frames are streamed directly to avconv via a pipe and written in a single + pass. + ''' # Combine AVConv options with file-based writing @writers.register('avconv_file') class AVConvFileWriter(AVConvBase, FFMpegFileWriter): - pass + '''File-based avconv writer. + + Frames are written to temporary files on disk and then stitched + together at the end. + + ''' # Base class of mencoder information. Contains configuration key information @@ -616,6 +668,12 @@ def _args(self): # Base class for animated GIFs with convert utility class ImageMagickBase(object): + '''Mixin class for ImageMagick output. + + To be useful this must be multiply-inherited from with a + `MovieWriterBase` sub-class. + ''' + exec_key = 'animation.convert_path' args_key = 'animation.convert_args' @@ -648,7 +706,7 @@ def _init_from_registry(cls): @classmethod def isAvailable(cls): ''' - Check to see if a ImageMagickWriter is actually available + Check to see if a ImageMagickWriter is actually available. Done by first checking the windows registry (if applicable) and then running the commandline tool. @@ -667,6 +725,12 @@ def isAvailable(cls): # former. @writers.register('imagemagick') class ImageMagickWriter(ImageMagickBase, MovieWriter): + '''Pipe-based animated gif. + + Frames are streamed directly to ImageMagick via a pipe and written + in a single pass. + + ''' def _args(self): return ([self.bin_path(), '-size', '%ix%i' % self.frame_size, '-depth', '8', @@ -681,6 +745,13 @@ def _args(self): # former. @writers.register('imagemagick_file') class ImageMagickFileWriter(ImageMagickBase, FileMovieWriter): + '''File-based animated gif writer. + + Frames are written to temporary files on disk and then stitched + together at the end. + + ''' + supported_formats = ['png', 'jpeg', 'ppm', 'tiff', 'sgi', 'bmp', 'pbm', 'raw', 'rgba'] @@ -691,19 +762,34 @@ def _args(self): class Animation(object): - ''' - This class wraps the creation of an animation using matplotlib. It is - only a base class which should be subclassed to provide needed behavior. + '''This class wraps the creation of an animation using matplotlib. + + It is only a base class which should be subclassed to provide + needed behavior. + + This class is not typically used directly. + + Parameters + ---------- + fig : matplotlib.figure.Figure + The figure object that is used to get draw, resize, and any + other needed events. + + event_source : object, optional + A class that can run a callback when desired events + are generated, as well as be stopped and started. + + Examples include timers (see :class:`TimedAnimation`) and file + system notifications. - *fig* is the figure object that is used to get draw, resize, and any - other needed events. + blit : bool, optional + controls whether blitting is used to optimize drawing. Defaults + to `False`. - *event_source* is a class that can run a callback when desired events - are generated, as well as be stopped and started. Examples include timers - (see :class:`TimedAnimation`) and file system notifications. + See Also + -------- + FuncAnimation, ArtistAnimation - *blit* is a boolean that controls whether blitting is used to optimize - drawing. ''' def __init__(self, fig, event_source=None, blit=False): self._fig = fig @@ -758,55 +844,72 @@ def _stop(self, *args): def save(self, filename, writer=None, fps=None, dpi=None, codec=None, bitrate=None, extra_args=None, metadata=None, extra_anim=None, savefig_kwargs=None): - ''' - Saves a movie file by drawing every frame. - - *filename* is the output filename, e.g., :file:`mymovie.mp4` - - *writer* is either an instance of :class:`MovieWriter` or a string - key that identifies a class to use, such as 'ffmpeg' or 'mencoder'. - If nothing is passed, the value of the rcparam `animation.writer` is - used. - - *dpi* controls the dots per inch for the movie frames. This combined - with the figure's size in inches controls the size of the movie. - - *savefig_kwargs* is a dictionary containing keyword arguments to be - passed on to the 'savefig' command which is called repeatedly to save - the individual frames. This can be used to set tight bounding boxes, - for example. - - *extra_anim* is a list of additional `Animation` objects that should - be included in the saved movie file. These need to be from the same - `matplotlib.Figure` instance. Also, animation frames will just be - simply combined, so there should be a 1:1 correspondence between - the frames from the different animations. - - These remaining arguments are used to construct a :class:`MovieWriter` - instance when necessary and are only considered valid if *writer* is - not a :class:`MovieWriter` instance. - - *fps* is the frames per second in the movie. Defaults to None, - which will use the animation's specified interval to set the frames - per second. - - *codec* is the video codec to be used. Not all codecs are supported - by a given :class:`MovieWriter`. If none is given, this defaults to the - value specified by the rcparam `animation.codec`. - - *bitrate* specifies the amount of bits used per second in the - compressed movie, in kilobits per second. A higher number means a - higher quality movie, but at the cost of increased file size. If no - value is given, this defaults to the value given by the rcparam - `animation.bitrate`. - - *extra_args* is a list of extra string arguments to be passed to the - underlying movie utility. The default is None, which passes the - additional arguments in the 'animation.extra_args' rcParam. - - *metadata* is a dictionary of keys and values for metadata to include - in the output file. Some keys that may be of use include: - title, artist, genre, subject, copyright, srcform, comment. + '''Saves a movie file by drawing every frame. + + Parameters + ---------- + + filename : str + The output filename, e.g., :file:`mymovie.mp4` + + writer : :class:`MovieWriter` or str, optional + A `MovieWriter` instance to use or a key that identifies a + class to use, such as 'ffmpeg' or 'mencoder'. If `None`, + defaults to ``rcParams['animation.writer']`` + + fps : number, optional + frames per second in the movie. Defaults to None, + which will use the animation's specified interval to set + the frames per second. + + dpi : number, optional + Controls the dots per inch for the movie frames. This + combined with the figure's size in inches controls the size of + the movie. If None, defaults to ``rcparam['savefig.dpi']`` + + codec : str, optional + The video codec to be used. Not all codecs are supported by + a given :class:`MovieWriter`. If `None`, + default to ``rcParams['animation.codec']`` + + bitrate : number, optional + Specifies the number of bits used per second in the + compressed movie, in kilobits per second. A higher number + means a higher quality movie, but at the cost of increased + file size. If `None`, defaults to + ``rcParam['animation.bitrate']`` + + extra_args : list, optional + List of extra string arguments to be passed to the + underlying movie utility. If `None`, defaults to + ``rcParams['animation.extra_args']`` + + metadata : dict, optional + Dictionary of keys and values for metadata to include in + the output file. Some keys that may be of use include: + title, artist, genre, subject, copyright, srcform, comment. + + extra_anim : list, optional + Additional `Animation` objects that should be included in + the saved movie file. These need to be from the same + `matplotlib.Figure` instance. Also, animation frames will + just be simply combined, so there should be a 1:1 + correspondence between the frames from the different + animations. + + savefig_kwargs : dict, optional + Is a dictionary containing keyword arguments to be passed + on to the 'savefig' command which is called repeatedly to + save the individual frames. + + Notes + ----- + fps, codec, bitrate, extra_args, metadata are used to + construct a :class:`MovieWriter` instance and can only be + passed if `writer` is a string. If they are passed as + non-`None` and ``writer`` is a :class:`MovieWriter`, a + `RuntimeError` will be raised. + ''' # If the writer is None, use the rc param to find the name of the one # to use @@ -1081,15 +1184,31 @@ def _repr_html_(self): class TimedAnimation(Animation): - ''' - :class:`Animation` subclass that supports time-based animation, drawing - a new frame every *interval* milliseconds. + ''':class:`Animation` subclass for time-based animation. + + A new frame is drawn every *interval* milliseconds. + + Parameters + ---------- + fig : matplotlib.figure.Figure + The figure object that is used to get draw, resize, and any + other needed events. - *repeat* controls whether the animation should repeat when the sequence - of frames is completed. + interval : number, optional + Delay between frames in milliseconds. Defaults to 200. + + repeat_delay : number, optional + If the animation in repeated, adds a delay in milliseconds + before repeating the animation. Defaults to `None`. + + repeat : bool, optional + Controls whether the animation should repeat when the sequence + of frames is completed. Defaults to `True`. + + blit : bool, optional + Controls whether blitting is used to optimize drawing. Defaults + to `False`. - *repeat_delay* optionally adds a delay in milliseconds before repeating - the animation. ''' def __init__(self, fig, interval=200, repeat_delay=None, repeat=True, event_source=None, *args, **kwargs): @@ -1147,13 +1266,38 @@ def _loop_delay(self, *args): class ArtistAnimation(TimedAnimation): - ''' - Before calling this function, all plotting should have taken place + '''Animation using a fixed set of `Artist` objects. + + Before creating an instance, all plotting should have taken place and the relevant artists saved. - *artists* is a list, with each list entry a collection of artists that - represent what needs to be enabled on each frame. These will be disabled - for other frames. + + Parameters + ---------- + fig : matplotlib.figure.Figure + The figure object that is used to get draw, resize, and any + other needed events. + + artists : list + Each list entry a collection of artists that represent what + needs to be enabled on each frame. These will be disabled for + other frames. + + interval : number, optional + Delay between frames in milliseconds. Defaults to 200. + + repeat_delay : number, optional + If the animation in repeated, adds a delay in milliseconds + before repeating the animation. Defaults to `None`. + + repeat : bool, optional + Controls whether the animation should repeat when the sequence + of frames is completed. Defaults to `True`. + + blit : bool, optional + Controls whether blitting is used to optimize drawing. Defaults + to `False`. + ''' def __init__(self, fig, artists, *args, **kwargs): # Internal list of artists drawn in the most recent frame. @@ -1203,24 +1347,76 @@ def _draw_frame(self, artists): class FuncAnimation(TimedAnimation): ''' - Makes an animation by repeatedly calling a function *func*, passing in - (optional) arguments in *fargs*. + Makes an animation by repeatedly calling a function ``func``. + + + Parameters + ---------- + fig : matplotlib.figure.Figure + The figure object that is used to get draw, resize, and any + other needed events. + + func : callable + The function to call at each frame. The first argument will + be the next value in ``frames``. Any additional positional + arguments can be supplied via the ``fargs`` parameter. + + The required signature is :: + + def func(fr: object, *fargs) -> iterable_of_artists: + + frames : iterable, int, generator function, or None, optional + Source of data to pass ``func`` and each frame of the animation + + If an iterable, then simply use the values provided. If the + iterable has a length, it will override the ``save_count`` kwarg. + + If an integer, equivalent to passing ``range(frames)`` + + If a generator function, then must have the signature :: + + def gen_function() -> obj: + + In all of these cases, the values in `frames` is simply + passed through to the user-supplied `func` and thus can be + of any type. + + If `None`, then equivalent to passing ``itertools.count``. + + init_func : callable, optional + A function used to draw a clear frame. If not given, the + results of drawing from the first item in the frames sequence + will be used. This function will be called once before the + first frame. + + If blit=True, ``init_func`` must return an iterable of artists + to be re-drawn. + + The required signature is :: + + def init_func() -> iterable_of_artists: + + fargs : tuple or None, optional + Additional arguments to pass to each call to ``func`` + + save_count : int, optional + The number of values from `frames` to cache. + + interval : number, optional + Delay between frames in milliseconds. Defaults to 200. - *frames* can be a generator, an iterable, or a number of frames. + repeat_delay : number, optional + If the animation in repeated, adds a delay in milliseconds + before repeating the animation. Defaults to `None`. - *init_func* is a function used to draw a clear frame. If not given, the - results of drawing from the first item in the frames sequence will be - used. This function will be called once before the first frame. + repeat : bool, optional + Controls whether the animation should repeat when the sequence + of frames is completed. Defaults to `True`. - If blit=True, *func* and *init_func* must return an iterable of - artists to be re-drawn. + blit : bool, optional + Controls whether blitting is used to optimize drawing. Defaults + to `False`. - *kwargs* include *repeat*, *repeat_delay*, and *interval*: - *interval* draws a new frame every *interval* milliseconds. - *repeat* controls whether the animation should repeat when the sequence - of frames is completed. - *repeat_delay* optionally adds a delay in milliseconds before repeating - the animation. ''' def __init__(self, fig, func, frames=None, init_func=None, fargs=None, save_count=None, **kwargs):