plotly.express.imshow¶

plotly.express.imshow(img, zmin=None, zmax=None, origin=None, labels={}, x=None, y=None, animation_frame=None, facet_col=None, facet_row=None, facet_col_wrap=None, facet_col_spacing=None, facet_row_spacing=None, color_continuous_scale=None, color_continuous_midpoint=None, range_color=None, title=None, template=None, width=None, height=None, aspect=None, contrast_rescaling=None, binary_string=None, binary_backend='auto', binary_compression_level=4, binary_format='png', text_auto=False) → plotly.graph_objects._figure.Figure¶

Display an image, i.e. data on a 2D regular raster.

Parameters

• img (array-like image, or xarray) –

  The image data. Supported array shapes are

  • (M, N): an image with scalar data. The data is visualized using a colormap.

  • (M, N, 3): an image with RGB values.

  • (M, N, 4): an image with RGBA values, i.e. including transparency.

• zmin (scalar or iterable, optional) – zmin and zmax define the scalar range that the colormap covers. By default, zmin and zmax correspond to the min and max values of the datatype for integer datatypes (ie [0-255] for uint8 images, [0, 65535] for uint16 images, etc.). For a multichannel image of floats, the max of the image is computed and zmax is the smallest power of 256 (1, 255, 65535) greater than this max value, with a 5% tolerance. For a single-channel image, the max of the image is used. Overridden by range_color.

• zmax (scalar or iterable, optional) – zmin and zmax define the scalar range that the colormap covers. By default, zmin and zmax correspond to the min and max values of the datatype for integer datatypes (ie [0-255] for uint8 images, [0, 65535] for uint16 images, etc.). For a multichannel image of floats, the max of the image is computed and zmax is the smallest power of 256 (1, 255, 65535) greater than this max value, with a 5% tolerance. For a single-channel image, the max of the image is used. Overridden by range_color.

• origin (str, 'upper' or 'lower' (default 'upper')) – position of the [0, 0] pixel of the image array, in the upper left or lower left corner. The convention ‘upper’ is typically used for matrices and images.

• labels (dict with str keys and str values (default {})) – Sets names used in the figure for axis titles (keys x and y), colorbar title and hoverlabel (key color). The values should correspond to the desired label to be displayed. If img is an xarray, dimension names are used for axis titles, and long name for the colorbar title (unless overridden in labels). Possible keys are: x, y, and color.

• x (list-like, optional) – x and y are used to label the axes of single-channel heatmap visualizations and their lengths must match the lengths of the second and first dimensions of the img argument. They are auto-populated if the input is an xarray.

• y (list-like, optional) – x and y are used to label the axes of single-channel heatmap visualizations and their lengths must match the lengths of the second and first dimensions of the img argument. They are auto-populated if the input is an xarray.

• animation_frame (int or str, optional (default None)) – axis number along which the image array is sliced to create an animation plot. If img is an xarray, animation_frame can be the name of one the dimensions.

• facet_col (int or str, optional (default None)) – axis number along which the image array is sliced to create a facetted plot. If img is an xarray, facet_col can be the name of one the dimensions.

• facet_row (int or str, optional (default None)) – axis number along which the image array is sliced to create a vertically facetted plot. If img is an xarray, facet_row can be the name of one the dimensions.

• facet_col_wrap (int) – Maximum number of facet columns. Wraps the column variable at this width, so that the column facets span multiple rows. Ignored if facet_col is None or if facet_row is set.

• facet_col_spacing (float between 0 and 1) – Spacing between facet columns, in paper units. Default is 0.02.

• facet_row_spacing (float between 0 and 1) – Spacing between facet rows created when facet_col_wrap is used, in paper units. Default is 0.0.7.

• color_continuous_scale (str or list of str) – colormap used to map scalar data to colors (for a 2D image). This parameter is not used for RGB or RGBA images. If a string is provided, it should be the name of a known color scale, and if a list is provided, it should be a list of CSS- compatible colors.

• color_continuous_midpoint (number) – If set, computes the bounds of the continuous color scale to have the desired midpoint. Overridden by range_color or zmin and zmax.

• range_color (list of two numbers) – If provided, overrides auto-scaling on the continuous color scale, including overriding color_continuous_midpoint. Also overrides zmin and zmax. Used only for single-channel images.

• title (str) – The figure title.

• template (str or dict or plotly.graph_objects.layout.Template instance) – The figure template name or definition.

• width (number) – The figure width in pixels.

• height (number) – The figure height in pixels.

• aspect ('equal', 'auto', or None) –

  • ‘equal’: Ensures an aspect ratio of 1 or pixels (square pixels)

  • ’auto’: The axes is kept fixed and the aspect ratio of pixels is adjusted so that the data fit in the axes. In general, this will result in non-square pixels.

  • if None, ‘equal’ is used for numpy arrays and ‘auto’ for xarrays (which have typically heterogeneous coordinates)

• contrast_rescaling ('minmax', 'infer', or None) – how to determine data values corresponding to the bounds of the color range, when zmin or zmax are not passed. If minmax, the min and max values of the image are used. If infer, a heuristic based on the image data type is used.

• binary_string (bool, default None) – if True, the image data are first rescaled and encoded as uint8 and then passed to plotly.js as a b64 PNG string. If False, data are passed unchanged as a numerical array. Setting to True may lead to performance gains, at the cost of a loss of precision depending on the original data type. If None, use_binary_string is set to True for multichannel (eg) RGB arrays, and to False for single-channel (2D) arrays. 2D arrays are represented as grayscale and with no colorbar if use_binary_string is True.

• binary_backend (str, 'auto' (default), 'pil' or 'pypng') – Third-party package for the transformation of numpy arrays to png b64 strings. If ‘auto’, Pillow is used if installed, otherwise pypng.

• binary_compression_level (int, between 0 and 9 (default 4)) – png compression level to be passed to the backend when transforming an array to a png b64 string. Increasing binary_compression decreases the size of the png string, but the compression step takes more time. For most images it is not worth using levels greater than 5, but it’s possible to test len(fig.data[0].source) and to time the execution of imshow to tune the level of compression. 0 means no compression (not recommended).

• binary_format (str, 'png' (default) or 'jpg') – compression format used to generate b64 string. ‘png’ is recommended since it uses lossless compression, but ‘jpg’ (lossy) compression can result if smaller binary strings for natural images.

• text_auto (bool or str (default False)) – If True or a string, single-channel img values will be displayed as text. A string like '.2f' will be interpreted as a texttemplate numeric formatting directive.

Returns

fig

Return type

graph_objects.Figure containing the displayed image

See also

plotly.graph_objects.Image

image trace

plotly.graph_objects.Heatmap

heatmap trace

Notes

In order to update and customize the returned figure, use go.Figure.update_traces or go.Figure.update_layout.

If an xarray is passed, dimensions names and coordinates are used for axes labels and ticks.