matplotlib.animation.Animation#

class matplotlib.animation.Animation(fig, event_source, blit=False)[source]#

Abstract base class for Animations.

Note

You must store the created Animation in a variable that lives as long as the animation should run. Otherwise, the Animation object will be garbage-collected and the animation stops.

Parameters:

figFigure

The figure object used to get needed events, such as draw or resize.

event_sourceobject

A class that can run a callback when desired events are generated, as well as be stopped and started.

Examples include timers (see TimedAnimation) and file system notifications.

blitbool, default: False

Whether blitting is used to optimize drawing. If the backend does not support blitting, then this parameter has no effect.

See also

FuncAnimation, ArtistAnimation

__init__(fig, event_source, blit=False)[source]#

Methods

__init__(fig,event_source[,blit])
new_frame_seq()	Return a new sequence of frame information.
new_saved_frame_seq()	Return a new sequence of saved/cached frame information.
pause()	Pause the animation.
resume()	Resume the animation.
save(filename[,writer,fps,dpi,codec,...])	Save the animation as a movie file by drawing every frame.
to_html5_video([embed_limit])	Convert the animation to an HTML5 <video> tag.
to_jshtml([fps,embed_frames,default_mode])	Generate HTML representation of the animation.

new_frame_seq()[source]#

Return a new sequence of frame information.

new_saved_frame_seq()[source]#

Return a new sequence of saved/cached frame information.

pause()[source]#

Pause the animation.

resume()[source]#

Resume the animation.

save(filename, writer=None, fps=None, dpi=None, codec=None, bitrate=None, extra_args=None, metadata=None, extra_anim=None, savefig_kwargs=None, *, progress_callback=None)[source]#

Save the animation as a movie file by drawing every frame.

Parameters:

filenamestr

The output filename, e.g., mymovie.mp4.

writerAbstractMovieWriter subclass or str, default: rcParams["animation.writer"] (default: 'ffmpeg')

The writer used to grab the frames and create the movie file. This can be an instance of an AbstractMovieWriter subclass or a string. The builtin writers are

str	class
'ffmpeg'	FFMpegWriter
'ffmpeg_file'	FFMpegFileWriter
'imagemagick'	ImageMagickWriter
'imagemagick_file'	ImageMagickFileWriter
'pillow'	PillowWriter
'html'	HTMLWriter

fpsint, optional

Movie frame rate (per second). If not set, the frame rate from the animation's frame interval.

dpifloat, default: rcParams["savefig.dpi"] (default: 'figure')

Controls the dots per inch for the movie frames. Together with the figure's size in inches, this controls the size of the movie.

codecstr, default: rcParams["animation.codec"] (default: 'h264').

The video codec to use. Not all codecs are supported by a given MovieWriter.

bitrateint, default: rcParams["animation.bitrate"] (default: -1)

The bitrate of the movie, in kilobits per second. Higher values means higher quality movies, but increase the file size. A value of -1 lets the underlying movie encoder select the bitrate.

extra_argslist of str or None, optional

Extra command-line arguments passed to the underlying movie encoder. These arguments are passed last to the encoder, just before the output filename. The default, None, means to use rcParams["animation.[name-of-encoder]_args"] for the builtin writers.

metadatadict[str, str], default: {}

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_animlist, default: []

Additional Animation objects that should be included in the saved movie file. These need to be from the same 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_kwargsdict, default: {}

Keyword arguments passed to each savefig call used to save the individual frames.

progress_callbackfunction, optional

A callback function that will be called for every frame to notify the saving progress. It must have the signature

def func(current_frame: int, total_frames: int) -> Any

where current_frame is the current frame number and total_frames is the total number of frames to be saved. total_frames is set to None, if the total number of frames cannot be determined. Return values may exist but are ignored.

Example code to write the progress to stdout:

progress_callback = lambda i, n: print(f'Saving frame {i}/{n}')

Notes

fps, codec, bitrate, extra_args and metadata are used to construct a MovieWriter instance and can only be passed if writer is a string. If they are passed as non-None and writer is a MovieWriter, a RuntimeError will be raised.

to_html5_video(embed_limit=None)[source]#

Convert the animation to an HTML5 <video> tag.

This saves the animation as an h264 video, encoded in base64 directly into the HTML5 video tag. This respects rcParams["animation.writer"] (default: 'ffmpeg') and rcParams["animation.bitrate"] (default: -1). This also makes use of the interval to control the speed, and uses the repeat parameter to decide whether to loop.

Parameters:

embed_limitfloat, optional

Limit, in MB, of the returned animation. No animation is created if the limit is exceeded. Defaults to rcParams["animation.embed_limit"] (default: 20.0) = 20.0.

Returns:

str

An HTML5 video tag with the animation embedded as base64 encoded h264 video. If the embed_limit is exceeded, this returns the string "Video too large to embed."

to_jshtml(fps=None, embed_frames=True, default_mode=None)[source]#

Generate HTML representation of the animation.

Parameters:

fpsint, optional

Movie frame rate (per second). If not set, the frame rate from the animation's frame interval.

embed_framesbool, optional

default_modestr, optional

What to do when the animation ends. Must be one of {'loop', 'once', 'reflect'}. Defaults to 'loop' if the repeat parameter is True, otherwise 'once'.

Returns:

str

An HTML representation of the animation embedded as a js object as produced with the HTMLWriter.