plenoptic.tools.display.imshow#

plenoptic.tools.display.imshow(image, 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]#

Show image(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:

  • image (Tensor | list[Tensor]) – The images to display. Tensors should be 4d (batch, channel, height, width). List of tensors should be used for tensors of different height and width: all images 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.

  • 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:

PyrFigure

Returns:

fig – Figure containing the plotted images.

Raises:

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

  • ValueError – If zoom 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.

Notes

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.