PlasmaCalcs.plotting.movies.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).

__init__(fig, func, *args_super, fps=UNSET, verbose=True, **kw_super)

Methods

__init__(fig, func, *args_super[, fps, verbose])
get_progress_callback([progress_callback])
get_savefile(filename[, ext])
new_frame_seq()
new_saved_frame_seq()
pause()
resume()
save(filename[, writer, fps, progress_callback])
to_html5_video([embed_limit])
to_jshtml([fps])

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.