plotly

Plotly.io.to_image()

When working with Plotly’s graphs, you will encounter an instance where you need to export the plot into an image file. While you can dive into external tools to export the image, Plotly has built-in functionality to accomplish this.

Through this tutorial, you will learn how to use the plotly.io.to_image() function to save a figure as an image.

Plotly.io.to_image()

The plotly.io.to_image() function allows you to convert a specific plotly figure to a static image.

The function syntax is as shown:

plotly.io.to_image(fig, format=None, width=None, height=None, scale=None, validate=True, engine='auto')

 
The function accepts the parameters as shown:

    1. fig – represents the figure to be converted to a static image.
    2. format – this parameter defines the target image format. Supported values include: “png,” “jpg,” “jpeg,” “svg,” “webp,” “eps,” and “pdf.”
    3. width – specifies the width dimensions of the exported image. This value is provided in pixels.
    4. height – defines the height dimension of the image in pixels.
    5. scale – represents the scale factor when exporting the specific figure.
    6. validated – specifies if the image should be validated before converting to image. By default, this value is set to true.
    7. engine – used to define the image export engine. Supported engines include: “kaleido”, “orca”, and “auto.”

The function returns the image data in bytes.

Example #1

The following example code shows how to export a simple figure into a static image using the to_image.

import plotly.express as px
import numpy as np
x = np.random.randn(50)
y = np.random.randn(50)
fig = px.scatter(x=x, y=y)
fig.show()

 
In the code above, we use the Plotly Express module to create a simple scatter plot with random data from the NumPy randn function.

The resulting figure:


To export this figure, we can run the code as:

import plotly as plt
plt.io.to_image(fig, format='png')

 
The code above should return bytes data of the image as shown:

b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x02\xbc\x00\x00\x01\xf4\x08\x06\x00\x00\x00
\xdfY\xfe\xdf\x00\x00
----truncated

 
Note that you may sometimes face the kaleido required error when running the to_image() function.

You can resolve this by using the kaleido package with pip as:

$ pip install kaleido
$ pip3 install kaledio

 
Once installed, relaunch your development environment and re-run the code above.

Example 2 – Saving Bytes to File

In most cases, having bytes of data is not very useful. However, we can use this byte and write it to an image file as shown in the code:

import plotly as plt
with open("target_filename.png", 'wb') as f:
    f.write(plt.io.to_image(fig, format='png'))

 
In the example above, we use the Python file operation to create a file and write the bytes from the to_image() function. The above method should create a file with the specified filename and save the image.

The resulting image is as shown:

Example 3 – Specifying Image and Height Dimensions

To export the image with specific width and height dimensions, we can specify these parameters as shown:

import plotly as plt
with open("target_filename.png", 'wb') as f:
    f.write(plt.io.to_image(fig, width=1200, height=800, format='png'))

 
In the example above, we save the image in 1200×800 dimensions. We can verify this by running the command:

$ exiftool target_filename.png

 
This should return output as shown:


As we can see, the resulting image has 1200 x 800 dimensions.

Example 4 – Specify Image Export Engine

Plotly also allows you to specify the engine you wish to use when exporting the image. It supports kaleido and orca as the engines.

An example of how to specify the export engine is shown below.

Before specifying an engine, ensure it’s installed and available in the path of your system.

For example, to install kaleido, run the command:

$ sudo pip3 install kaleido

 
For Orca, run the command:

conda install -c plotly-orca psutil requests
$ pip3 install plotly-orca psutil requests

 
Example:

import plotly as plt
with open("target_filename.png", 'wb') as f:
    f.write(plt.io.to_image(fig, width=1200, height=800, format='png', engine="kaleido"))

 
The example above illustrates how to specify the image export engine to kaleido.

Keep in mind that Plotly will default to the auto value. This means, if kaleido is not installed, Plotly will use orca and vice versa.

Conclusion

In this article, we learned how we can export a figure into a static image as bytes using the io.to_image() function. We also learned how to specify a custom image size, write the bytes to disk as an image, etc.

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