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.

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

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

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.

fargs : tuple 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_count : int, 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.

interval : int, default: 200

Delay between frames in milliseconds.

repeat_delay : int, default: 0

The delay in milliseconds between consecutive animation runs, if

*repeat* is True.

repeat : bool, default: True

Whether the animation repeats when the sequence of frames is completed.

blit : bool, 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_data : bool, 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

———-

filename : str

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

writer : MovieWriter or str, default: :rc:animation.writer

A MovieWriter instance to use or a key that identifies a

class to use, such as ‘ffmpeg’.

fps : int, optional

Movie frame rate (per second). If not set, the frame rate from the

animation’s frame interval.

dpi : float, 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.

codec : str, default: :rc:animation.codec.

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

MovieWriter.

bitrate : int, 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_args : list 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.

metadata : dict[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_anim : list, 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_kwargs : dict, default: {}

Keyword arguments passed to each ~.Figure.savefig call used to

save the individual frames.

progress_callback : function, 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_limit : float, 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

———-

fps : int, 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.