, zmin=None, zmax=None, origin=None, labels={}, x=None, y=None, color_continuous_scale=None, color_continuous_midpoint=None, range_color=None, title=None, template=None, width=None, height=None, aspect=None)

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

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

  • zmax (zmin,) – 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.

  • y (x,) – 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.

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



Return type

graph_objects.Figure containing the displayed image

See also


image trace


heatmap trace


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.