plenoptic.plot.animshow#

plenoptic.plot.animshow(video, framerate=2.0, repeat=False, vrange='indep1', zoom=None, title='', col_wrap=None, ax=None, cmap=None, plot_complex='rectangular', batch_idx=None, channel_idx=None, as_rgb=False, **kwargs)[source]#

Animate video(s), avoiding interpolation.

This function shows images carefully, avoiding interpolation: each element in the input image will correspond to a pixel or an integer number of pixels. When zoom<1, an integer number of input elements will be averaged into a single pixel.

Parameters:

  • video (Tensor | list[Tensor]) – The video(s) to display. Tensors should be 5d (batch, channel, time, height, width). List of tensors should be used for tensors of different height and width: all videos will automatically be rescaled so they’re displayed at the same height and width, thus, their heights and widths must be scalar multiples of each other. Videos must all have the same number of frames.

  • framerate (float (default: 2.0)) – Temporal resolution of the video, in Hz (frames per second).

  • repeat (bool (default: False)) – Whether to loop the animation or just play it once.

  • vrange (tuple[float, float] | str (default: 'indep1')) –

    If a 2-tuple, specifies the image values vmin/vmax that are mapped to the minimum and maximum value of the colormap, respectively. If a string:

    • "auto0": All images have same vmin/vmax, which have the same absolute value, and come from the minimum or maximum across all images, whichever has the larger absolute value.

    • "auto1": All images have same vmin/vmax, which are the minimum/maximum values across all images.

    • "auto2": All images have same vmin/vmax, which are the mean (across all images) minus/ plus 2 std dev (across all images).

    • "auto3": All images have same vmin/vmax, chosen so as to map the 10th/90th percentile values to the 10th/90th percentile of the display intensity range. For example: vmin is the 10th percentile image value minus 1/8 times the difference between the 90th and 10th percentile.

    • "indep0": Each image has an independent vmin/vmax, which have the same absolute value, which comes from either their minimum or maximum value, whichever has the larger absolute value.

    • "indep1": Each image has an independent vmin/vmax, which are their minimum/maximum values.

    • "indep2": Each image has an independent vmin/vmax, which is their mean minus/plus 2 std dev.

    • "indep3": Each image has an independent vmin/vmax, chosen so that the 10th/90th percentile values map to the 10th/90th percentile intensities.

  • zoom (float | None (default: None)) – Ratio of display pixels to image pixels. If greater than 1, must be an integer. If less than 1, must be 1/d where d is a a divisor of the size of the largest image. If None, we try to determine the best zoom.

  • title (str | list[str] | None (default: '')) –

    Title for the plot. In addition to the specified title, we add a subtitle giving the plotted range and dimensionality (with zoom).

    • If str, will put the same title on every plot.

    • If list, all values must be str, must be the same length as img, and each title will be assigned to corresponding plot.

    • If None, no title will be printed and subtitle will be removed.

  • col_wrap (int | None (default: None)) – Number of axes to have in each row. If None, will fit all axes in a single row.

  • ax (Axes | None (default: None)) – If None, we make the appropriate figure. Otherwise, we shrink the axes so that it’s the appropriate number of pixels.

  • cmap (Colormap | None (default: None)) – Colormap to use when showing these images. If None, then behavior is determined by vrange: if vmap in ["auto0", "indep0"], we use "RdBu_r", else we use "gray" (see matplotlib documentation).

  • plot_complex (Literal['rectangular', 'polar', 'logpolar'] (default: 'rectangular')) –

    Specifies handling of complex values.

    • "rectangular": plot real and imaginary components as separate images.

    • "polar": plot amplitude and phase as separate images.

    • "logpolar": plot log (base 2) amplitude and phase as separate images.

  • batch_idx (int | None (default: None)) – Which element from the batch dimension to plot. If None, we plot all.

  • channel_idx (int | None (default: None)) – Which element from the channel dimension to plot. If None, we plot all. Note if this is not None, then as_rgb=True will fail, because we restrict the channels.

  • as_rgb (bool (default: False)) – Whether to consider the channels as encoding RGB(A) values. If True, we attempt to plot the image in color, so your tensor must have 3 (or 4 if you want the alpha channel) elements in the channel dimension. If False, we plot each channel as a separate grayscale image.

  • **kwargs (Any) – Passed to matplotlib.pyplot.imshow.

Return type:

FuncAnimation

Returns:

anim – The animation object. In order to view, must convert to HTML or save.

Raises:

  • ValueError – If videos is not a 5d tensor or list of 4d tensors.

  • TypeError – If batch_idx or channel_idx takes an illegal value.

  • ValueError – If as_rgb=True and the input image does not have 3 or 4 channels.

  • ValueError – If as_rgb=False, image has more than one channel and one more than one batch and neither batch_idx nor channel_idx is set.

  • Exception – If plot_complex takes an illegal value.

See also

imshow

Display an image.

synthesis_animate

Animate synthesis process for a Metamer or a MADCompetition object.

Notes

  • This functions returns a matplotlib FuncAnimation object. See below for how to view to view it in a Jupyter notebook. See Examples section for how to save to disk. In either case, this can take a while and you’ll need the appropriate writer installed and on your path, e.g., ffmpeg, imagemagick, etc). See matplotlib documentation for more details.

  • Unless specified, we use the ffmpeg backend, which requires that you have ffmpeg installed and on your path (https://ffmpeg.org/download.html). To use a different, use the matplotlib rcParams: matplotlib.rcParams['animation.writer'] = writer, see matplotlib documentation for more details.

  • To view in a Jupyter notebook, we recommend adding the following to the first cell of your notebook (requires ffmpeg):

    import matplotlib.pyplot as plt
plt.rcParams["animation.html"] = "html5"
# use single-threaded ffmpeg for animation writer
plt.rcParams["animation.writer"] = "ffmpeg"
plt.rcParams["animation.ffmpeg_args"] = ["-threads", "1"]

  • This interpolation avoidance is only guaranteed for the saved image; it should generally hold in notebooks as well, but will fail if, e.g., you plot an image that’s 2000 pixels wide on an monitor 1000 pixels wide; the browser handles the rescaling in a way we can’t control.