| jupyter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Plotly figures are interactive when viewed in a web browser: you can hover over data points, pan and zoom axes, and show and hide traces by clicking or double-clicking on the legend. You can export figures either to static image file formats like PNG, JPEG, SVG or PDF or you can export them to HTML files which can be opened in a browser and remain interactive. This page explains how to do the former.
Static image generation requires either Kaleido (recommended) or orca (legacy). The kaleido package can be installed using pip...
$ pip install -U kaleido
or conda.
$ conda install -c plotly python-kaleido
While Kaleido is now the recommended approach, image export can also be supported by the legacy orca command line utility. See the Orca Management section for instructions on installing, configuring, and troubleshooting orca.
Now let's create a simple scatter plot with 100 random points of varying color and size.
import plotly.graph_objects as go
import numpy as np
np.random.seed(1)
N = 100
x = np.random.rand(N)
y = np.random.rand(N)
colors = np.random.rand(N)
sz = np.random.rand(N) * 30
fig = go.Figure()
fig.add_trace(go.Scatter(
x=x,
y=y,
mode="markers",
marker=go.scatter.Marker(
size=sz,
color=colors,
opacity=0.6,
colorscale="Viridis"
)
))
fig.show()The plotly.io.write_image function is used to write an image to a file or file-like python object. You can also use the .write_image graph object figure method.
Let's first create an output directory to store our images
import os
if not os.path.exists("images"):
os.mkdir("images")If you are running this notebook live, click to open the output directory so you can examine the images as they are written.
plotly.py can output figures to several raster image formats including PNG, ...
fig.write_image("images/fig1.png")JPEG, ...
fig.write_image("images/fig1.jpeg")and WebP
fig.write_image("images/fig1.webp")plotly.py can also output figures in several vector formats including SVG, ...
fig.write_image("images/fig1.svg")PDF, ...
fig.write_image("images/fig1.pdf")and EPS (requires the poppler library)
fig.write_image("images/fig1.eps")Note: It is important to note that any figures containing WebGL traces (i.e. of type scattergl, heatmapgl, contourgl, scatter3d, surface, mesh3d, scatterpolargl, cone, streamtube, splom, or parcoords) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image.
The plotly.io.to_image function is used to return an image as a bytes object. You can also use the .to_image graph object figure method.
Let convert the figure to a PNG bytes object...
img_bytes = fig.to_image(format="png")and then display the first 20 bytes.
img_bytes[:20]A bytes object representing a PNG image can be displayed directly in the notebook using the IPython.display.Image class. This also works in the Qt Console for Jupyter!
from IPython.display import Image
Image(img_bytes)In addition to the image format, the to_image and write_image functions provide arguments to specify the image width and height in logical pixels. They also provide a scale parameter that can be used to increase (scale > 1) or decrease (scale < 1) the physical resolution of the resulting image.
img_bytes = fig.to_image(format="png", width=600, height=350, scale=2)
Image(img_bytes)If kaleido is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use orca instead. The engine argument to the to_image and write_image functions can be used to override this default behavior.
Here is an example of specifying that orca should be used:
fig.to_image(format="png", engine="orca")And, here is an example of specifying that Kaleido should be used:
fig.to_image(format="png", engine="kaleido")Various image export settings can be configured using the plotly.io.kaleido.scope object. For example, the default_format property can be used to specify that the default export format should be svg instead of png
import plotly.io as pio
pio.kaleido.scope.default_format = "svg"Here is a complete listing of the available image export settings:
default_width: The default pixel width to use on image export.default_height: The default pixel height to use on image export.default_scale: The default image scale factor applied on image export.default_format: The default image format used on export. One of"png","jpeg","webp","svg","pdf", or"eps".mathjax: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle.topojson: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the Plotly.js topojson files.mapbox_access_token: The default Mapbox access token.
See the Orca Management section for information on how to specify image export settings when using orca.
In summary, to export high-quality static images from plotly.py, all you need to do is install the kaleido package and then use the plotly.io.write_image and plotly.io.to_image functions (or the .write_image and .to_image graph object figure methods).