As of plotly.py version 3.2, it possible to export figures as high quality static images without making API requests to the plot.ly image servers.
Static image generation requires the orca commandline utility and the psutil Python library. There are 3 general approach to installing these dependencies.
Using the conda package manager, you can install these dependencies in a single command:
$ conda install -c plotly-orca psutil
Note: Even if you don't want to use conda to manage your Python dependencies, it is still useful as a cross platform tool for managing native libraries and command-line utilities (e.g. git, wget, graphviz, boost, gcc, nodejs, cairo, etc.). For this use-case, start with Miniconda (~60MB) and tell the installer to add itself to your system PATH
. Then run conda install plotly-orca
and the orca executable will be available system wide.
You can use the npm package manager to install orca
(and its electron
dependency), and then use pip to install psutil
:
$ npm install -g electron@1.8.4 orca
$ pip install psutil
If you are unable or unwilling to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca README to install orca and add it to your system PATH
. Then use pip to install psutil
.
$ pip install psutil
Now let's create a simple scatter plot with 100 random points of variying color and size.
import plotly.graph_objs as go
import plotly.io as pio
import os
import numpy as np
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.FigureWidget()
fig.add_scatter(x=x,
y=y,
mode='markers',
marker={'size': sz,
'color': colors,
'opacity': 0.6,
'colorscale': 'Viridis'
});
fig
FigureWidget({ 'data': [{'marker': {'color': array([0.38500549, 0.08262726, 0.33872947, 0.46764101, 0.7823…
The plotly.io.write_image
function is used to write an image to a file or file-like python object.
Let's first create an output directory to store our images
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're written.
Orca can output figures to several raster image formats including PNG, ...
pio.write_image(fig, 'images/fig1.png')
JPEG, ...
pio.write_image(fig, 'images/fig1.jpeg')
and WebP
pio.write_image(fig, 'images/fig1.webp')
Orca can also output figures in several vector formats including SVG, ...
pio.write_image(fig, 'images/fig1.svg')
PDF, ...
pio.write_image(fig, 'images/fig1.pdf')
and EPS (requires the poppler library)
pio.write_image(fig, 'images/fig1.eps')
The plotly.io.to_image
function is used to return an image as a bytes object.
Let convert the figure to a PNG bytes object...
img_bytes = pio.to_image(fig, format='png')
and then display the first 20 bytes.
img_bytes[:20]
b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x02\xbc'
IPython.display.Image
¶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 = pio.to_image(fig, format='png', width=600, height=350, scale=2)
Image(img_bytes)
In summary, to export high-quality static images from plotly.py all you need to do is install orca and psutil and then use the plotly.io.write_image
and plotly.io.to_image
functions.
If you want to know more about how the orca integration works, or if you need to troubleshoot an issue, please check out the Orca Management section.