FuncAnimation

class PlasmaCalcs.plotting.movies.FuncAnimation(fig, func, *args_super, fps=UNSET, verbose=True, **kw_super)

Bases: PlotSettingsMixin, FuncAnimation

matplotlib.animation.FuncAnimation class with more methods / convenience.

verbose: bool: verbosity, e.g. during self.save.
progress_callback: UNSET, None, or callable (default: UNSET): called when rendering each frame of the animation, as:

progress_callback(current frame number, total number of frames).

UNSET –> default to lambda i, n: updater.print(‘saving frame ‘+str(i)+’ of ‘+str(n)),

where updater = ProgressUpdater(print_freq=1 if verbose else -1).

(Or use value from self.plot_settings, if provided)

None –> don’t call anything, regardless of self.verbose.
fps: UNSET, None, or number (default: UNSET): frames per second.

UNSET –> use DEFAULTS.PLOT.FPS (default: 30).

(Or use value from self.plot_settings, if provided.)

None –> use matplotlib defaults.

All other args and kwargs go to super(), probably mpl.animation.FuncAnimation.
For reference, docs for mpl.animation.FuncAnimation:
—————————————————-

TimedAnimation subclass that makes an animation by repeatedly calling

a function *func*.

.. 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

———-

fig~matplotlib.figure.Figure: The figure object used to get needed events, such as draw or resize.
funccallable: The function to call at each frame. The first argument will

be the next value in *frames*. Any additional positional

arguments can be supplied using functools.partial or via the *fargs*

parameter.

The required signature is::

def func(frame, *fargs) -> iterable_of_artists

It is often more convenient to provide the arguments using

functools.partial. In this way it is also possible to pass keyword

arguments. To pass a function with both positional and keyword

arguments, set all arguments as keyword arguments, just leaving the

*frame* argument unset::

def func(frame, art, *, y=None):

…

ani = FuncAnimation(fig, partial(func, art=ln, y=’foo’))

If `blit == True`, *func* must return an iterable of all artists

that were modified or created. This information is used by the blitting

algorithm to determine which parts of the figure have to be updated.

The return value is unused if `blit == False` and may be omitted in

that case.
framesiterable, 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, then equivalent to passing `range(frames)`

- If a generator function, then must have the signature::

def gen_function() -> obj

- If *None*, then equivalent to passing `itertools.count`.

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.
init_funccallable, 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.

The required signature is::

def init_func() -> iterable_of_artists

If `blit == True`, *init_func* must return an iterable of artists

to be re-drawn. This information is used by the blitting algorithm to

determine which parts of the figure have to be updated. The return

value is unused if `blit == False` and may be omitted in that case.
fargstuple or None, optional: Additional arguments to pass to each call to *func*. Note: the use of

functools.partial is preferred over *fargs*. See *func* for details.
save_countint, optional: Fallback for the number of values from *frames* to cache. This is

only used if the number of frames cannot be inferred from *frames*,

i.e. when it’s an iterator without length or a generator.
intervalint, default: 200: Delay between frames in milliseconds.
repeat_delayint, default: 0: The delay in milliseconds between consecutive animation runs, if

*repeat* is True.
repeatbool, default: True: Whether the animation repeats when the sequence of frames is completed.
blitbool, default: False: Whether blitting is used to optimize drawing. Note: when using

blitting, any animated artists will be drawn according to their zorder;

however, they will be drawn on top of any previous artists, regardless

of their zorder.
cache_frame_databool, default: True: Whether frame data is cached. Disabling cache might be helpful when

frames contain large objects.

To view or adjust plot settings in self, see self.plot_settings, or help(self.plot_settings).

Methods

`__init_subclass__`(args_super, *kw)	appends note about using self.plot_settings, to cls.__doc__.
`get_progress_callback`([progress_callback])	return the progress_callback to use for self.save, based on input & self.verbose.
`get_savefile`(filename[, ext])	return abspath of filename, with ext appended if not already there.
`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, progress_callback])	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])	Generate HTML representation of the animation.
`_progress_callback_default`()	return the default progress_callback for self.save.
`_progress_updater_finalize`(message)	finalize self._progress_updater, if it exists, with the given message.
`_repr_html_`()	IPython display hook for rendering.

classmethod __init_subclass__(*args_super, **kw): appends note about using self.plot_settings, to cls.__doc__.

if “PlotSettings” or “plot_settings” appears in cls.__doc__, do NOT append this note;

assuming instead that this means the doc already mentions how to use plot_settings.

_progress_callback_default(): return the default progress_callback for self.save.

also sets self._progress_updater to the new ProgressUpdater object.

_progress_updater_finalize(message): finalize self._progress_updater, if it exists, with the given message.

_repr_html_(): IPython display hook for rendering.

get_progress_callback(progress_callback=UNSET): return the progress_callback to use for self.save, based on input & self.verbose.

also, first deletes self._progress_updater if it exists.

get_savefile(filename, ext=UNSET): return abspath of filename, with ext appended if not already there.

if ext not provided, use DEFAULTS.PLOT.MOVIE_EXT.

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=None, *args_super, fps=UNSET, progress_callback=UNSET, **kw_super)

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

filename: str: output filename, e.g. ‘example_movie.mp4’.

if no extension provided, append DEFAULTS.PLOT.MOVIE_EXT.
writer: None, str, or MovieWriter: writer to use. passed directly to super().save.

if MovieWriter (i.e., not None or str), ignore any provided value for fps.
fps: UNSET, None, or number (default: UNSET): frames per second.

UNSET –> use DEFAULTS.PLOT.FPS (default: 30).

(Or use value from self.plot_settings, if provided.)

None –> use matplotlib defaults.
progress_callback: UNSET, None, or callable (default: UNSET): called when rendering each frame of the animation, as:

progress_callback(current frame number, total number of frames).

UNSET –> default to lambda i, n: updater.print(‘saving frame ‘+str(i)+’ of ‘+str(n)),

where updater = ProgressUpdater(print_freq=1 if verbose else -1).

(Or use value from self.plot_settings, if provided)

None –> don’t call anything, regardless of self.verbose.

returns abspath of the saved file.

All other args and kwargs go to super().save, probably mpl.animation.FuncAnimation.save.
For reference, docs for mpl.animation.FuncAnimation.save:
———————————————————

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

Parameters

———-

filenamestr: The output filename, e.g., :file:mymovie.mp4.
writerMovieWriter or str, default: :rc:animation.writer: A MovieWriter instance to use or a key that identifies a

class to use, such as ‘ffmpeg’.
fpsint, optional: Movie frame rate (per second). If not set, the frame rate from the

animation’s frame interval.
dpifloat, default: :rc:savefig.dpi: 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: :rc:animation.codec.: The video codec to use. Not all codecs are supported by a given

MovieWriter.
bitrateint, default: :rc:animation.bitrate: 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 :rc: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 ~.Figure.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)

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 :rc:animation.writer

and :rc:animation.bitrate. 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 :rc:animation.embed_limit = 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=UNSET, *args_super, **kw_super)

Generate HTML representation of the animation.

fps: UNSET, None, or number: frames per second.

UNSET –> default to DEFAULTS.PLOT.FPS.

(Or use value from self, if provided)

None –> use matplotlib defaults.

All other args and kwargs go to super().to_jshtml, probably mpl.animation.FuncAnimation.to_jshtml.
For reference, docs for mpl.animation.FuncAnimation.to_jshtml:
————————————————————–

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_frames : bool, optional default_mode : str, 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.