In this tutorial, we will learn how to display image data in Plotly using the Plotly.imshow() function.

We will start by discussing the function syntax, the required parameters, and the return value. We will then illustrate how to use the function to display images.

Let’s dive in.

When you need to display images in your plots, use the function. This can be useful when you need accompanying information with the code you are working on.

However, you can use the function to display other plots such as heatmaps in a Plotly environment.

The function syntax is as shown:, zmin=None, zmax=None, origin=None, labels={}, x=None, y=None, animation_frame=None, facet_col=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

Although the function may present a rather complex syntax, you will rarely need to use all the specified parameters.

The following are some of the important parameters with which you’ll need to interact.

  1. Img – Specifies the image data, such as an image file or an array of values. Supported array shapes include:
    1. (M,N) – image data as a scalar value
    2. (M,N,3) – image data as RGB value
    3. (M,N,4) – image data as RGBA values.
  2. Binary_format – specifies the compression format used to generate the base64 string. Supported values include:
    1. ‘png’ – lossless compression
    2. ‘jpg’ – lossy compression
  3. Binary_compression_level – specifies the PNG compression level passed to the backend when transforming the array to a PNG string. A higher value means a smaller size of the PNG string but more time.
  4. Width/height – specifies the figure width and height values in pixels.

The above are some of the useful parameters you will need to interact with. Keep in mind that different use cases may require you to make use of the other supported parameters.

However, the function will return a figure displaying the image as graph_objects.Figur type.

Example: Display an RGB Image with px.imshow()

Now that we have explored the function syntax, let us see how we can use it to perform something practical.

The first example we will look at is displaying an RGB image. We can do this by running the code as shown:

import as px
import numpy as np
img_data = np.array([[[111,232,122], [200, 23, 114], [122,145,138]],
                     [[222,133,54], [123,54,221], [232, 122, 56]]], dtype=np.uint8)
fig = px.imshow(img_data)

In the code above, we start by importing the Plotly express and numpy modules. Next, we provide the image data as an array of RGB values, specifying the data type as np.unit8.

Finally, we call the imshow() function to plot the image from the provided array. The resulting figure is as shown:

Example 2: Show Image from File

The most common use case of the imshow() function is displaying an image from a file. The example below shows how to do so using the imshow() function.

import as px
from skimage import io
img = io.imread('')
fig = px.imshow(img)

In the example above, we start by importing the Plotly express module. We also import the io module from skimage. This allows us to read the image file.

Finally, we show the image file using the imshow() function. This should show the image as shown:

Keep in mind that, depending on the renderer, Plotly allows you to interact with the image and crop various aspects.

For example, in Jupyter Notebook, we can do:

This allows us to select a specific section of the image and zoom in on it.

Example 3: Remove Tick Labels

In the previous example, we can see that the image contains a numerical scale on the x and y axis. These are known as tick labels. Although you may need them in some cases, they can be distracting for simple image displays.

To remove them, we can use the update_* functions. An example code is as shown:

import as px
from skimage import io
img = io.imread('')
fig = px.imshow(img)

In this example, we use the fig.update_xaxes and fig.update_yaxes functions to remove the tick labels from the x and y axes, respectively.

The resulting figure is as shown:

As we can see, the image is cleaner and easy to view.

Example 4: Specifying Compression Level

We can specify the compression format and level as shown in the code below:

import as px
from skimage import io
img = io.imread('')
fig = px.imshow(img, binary_format='png', binary_compression_level=4)

In this case, we specify the compression format as lossless compression (png) with a compression level of 4.


In this article, we discussed how to use the imshow() function to display image data in Plotly.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list