matthewplotlib.animations

Temporally stack plots into an animation.

The third stacking operation, alongside hstack (+) and vstack (/): where those lay plots out across the screen, this one lays them out in time. The result is a value, not an action -- nothing is printed until you play it or savegif it.

Inputs:

• *plots : plot | tstack. The frames, in order. Any tstack among them is spliced in frame by frame, so tstack(a, b) concatenates two animations and tstack(a, still) appends a frame to one.
• fps : optional float. The rate this animation is meant to play at, used as the default by both play and savegif. An upper bound rather than a promise: see animate. Defaults to the frame rate of the first tstack among the inputs, so concatenating and slicing preserve it, or to 12.0 if there is none.
• durations : optional sequence of float. How long each frame was on screen, in milliseconds, if this animation was recorded from a live run. Supplied by animate.frames, which is the only thing that can know it, and read back by savegif(fps="achieved"). Must have one entry per frame.

Examples:

# build one frame at a time
a = mp.tstack(*[
    mp.image(field(t)) for t in np.linspace(0, 1, 60)
], fps=30)

# 60 frames, 20 rows, 40 columns
len(a), a.height, a.width

# every frame, in a titled border
a = a.map(lambda p: mp.border(p, title=" diffusion "))

# the second half, backwards
a[len(a)//2:][::-1].play()

Notes:

• Frames do not have to be the same size going in: they are padded with blank space to the largest, aligned at the top left, so an animation never changes shape while it plays. Differential redraw makes that free -- the padding is blank in every frame, so no cell of it is ever sent twice.

An animation from an array with a time axis: image, one dimension up.

Takes exactly what image takes with a leading frame index, so a field evolving over time goes straight to the screen without a loop in sight.

Inputs:

• ims : float[t,h,w] | float[t,h,w,rgb] | int[t,h,w] | int[t,h,w,rgb]. The frames. As for image, floats are clipped to the unit interval and integers to 0..255, and the second and third axes are the image's rows and columns -- each pair of rows becomes one row of half-block characters, so a 2n row image is n character rows tall.
• colormap : optional ColorMap. Applied to a scalar array to colour it, exactly as in image. Applied to the whole tensor in one call, which is both faster than doing it frame by frame and the only way to be sure every frame is coloured on the same scale.
• fps : optional float (default 12.0). The rate the animation is meant to play at.

Examples:

# a diffusing blob, straight from the array
mp.animation(field, colormap=mp.viridis, fps=30).play()

# a video, as uint8 RGB
mp.animation(video).savegif("video.gif")

A context manager that owns the terminal while an animation runs.

Inside the block, each call to update writes one frame:

with mp.animate(fps=20) as anim:
    while running:
        anim.update(mp.axes(...))

which is the print(plot - prev) loop with the parts that are about terminals rather than about plots taken over: the prev sentinel and the assignment that maintains it, the frame clock, and separating whatever comes next on the screen from the plot on the way out.

Everything beyond that first job is opt-in, because a context manager takes over the caller's control flow and this library would rather be a library than a framework. The plain loop remains fully supported and is what the quickstart teaches.

Inputs:

• fps : optional float. If given, cap the frame rate: update sleeps off whatever is left of the previous frame's budget before writing. An upper bound, not a guarantee -- a frame that takes longer than 1/fps to compute simply takes longer, and the clock picks up from there rather than trying to catch up. If omitted, update returns as soon as it has written.
• record : bool (default False). If true, keep every frame, readable afterwards as anim.frames. Opt-in because holding an entire animation in memory is a real cost and a while True loop would never stop paying it.
• stop_on_interrupt : bool (default False). If true, Ctrl-C ends the animation quietly: the with block exits and the statements after it still run, so a recording survives to be saved. Off by default because swallowing KeyboardInterrupt is precisely the kind of control flow a library should not take without being asked.

Attributes, readable during the block and after it:

• frames : tstack. The recorded animation, with the frame timings attached. Raises unless record=True was passed.
• achieved_fps : float | None. The frame rate actually managed so far, or None before the second frame. Worth printing after a run that felt sluggish: asking for 20 and getting 6 is not otherwise visible.

• out : a writable text stream. anim.print as a file, for the things that want somewhere to write rather than something to call:

  print("step", step, file=anim.out)
  logging.basicConfig(stream=anim.out)
  

  Line buffered, since the plot moves out of the way a line at a time. Redirecting sys.stdout to it for the whole block routes every print in the program, including ones inside libraries you did not write:

  with mp.animate(fps=20) as anim, contextlib.redirect_stdout(anim.out):
      ...
  

  which works because the session captured the real stdout on the way in.

Notes:

• A plot has to fit the terminal with a row to spare for the newline that print appends, so at most rows - 1 of it will render. If the first frame does not fit, and stdout is a terminal that can be measured, this warns once.
• The cursor is left visible. It sits in the plot and blinks there, which is a fair trade for never leaving a terminal with an invisible cursor.