Skip to content

Commit 31945aa

Browse files
jonmmeasejonmmease
committed
Update static image export notebook
1 parent d1ac927 commit 31945aa

File tree

1 file changed

+50
-83
lines changed

1 file changed

+50
-83
lines changed

‎notebooks/static-image-export.md

Lines changed: 50 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,21 @@ jupyter:
66
extension: .md
77
format_name: markdown
88
format_version: '1.1'
9-
jupytext_version: 1.1.1
9+
jupytext_version: 1.1.6
1010
kernelspec:
11-
display_name: Python 2
11+
display_name: Python 3
1212
language: python
13-
name: python2
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.7.3
1424
plotly:
1525
description: Plotly allows you to save static images of your plots. Save the image
1626
to your local computer, or embed it inside your Jupyter notebooks as a static
@@ -26,101 +36,82 @@ jupyter:
2636
permalink: python/static-image-export/
2737
thumbnail: thumbnail/static-image-export.png
2838
title: Static Image Export | plotly
39+
v4upgrade: true
2940
---
3041

31-
#### New to Plotly?
32-
Plotly's Python library is free and open source! [Get started](https://plot.ly/python/getting-started/) by downloading the client and [reading the primer](https://plot.ly/python/getting-started/).
33-
<br>You can set up Plotly to work in [online](https://plot.ly/python/getting-started/#initialization-for-online-plotting) or [offline](https://plot.ly/python/getting-started/#initialization-for-offline-plotting) mode, or in [jupyter notebooks](https://plot.ly/python/getting-started/#start-plotting-online).
34-
<br>We also have a quick-reference [cheatsheet](https://images.plot.ly/plotly-documentation/images/python_cheat_sheet.pdf) (new!) to help you get started!
35-
36-
### Version Check
37-
Note: The static image export API is available in version <b>3.2.0.+</b><br>
38-
39-
```python
40-
import plotly
41-
42-
plotly.__version__
43-
```
44-
4542
<!-- #region -->
4643
### Static Image Export
47-
New in version 3.2.0. It's now possible to programmatically export figures as high quality static images while fully offline.
44+
It's possible to programmatically export figures as high quality static images while fully offline.
4845

4946
#### Install Dependencies
50-
Static image generation requires the [orca](https://github.com/plotly/orca) commandline utility and the [psutil](https://github.com/giampaolo/psutil) Python library. There are 3 general approach to installing these dependencies.
47+
Static image generation requires the [orca](https://github.com/plotly/orca) commandline utility and the [psutil](https://github.com/giampaolo/psutil) and [requests](https://2.python-requests.org/en/master/) Python libraries. There are 3 general approach to installing these dependencies.
5148

5249
##### conda
5350
Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
5451
```
55-
$ conda install -c plotly plotly-orca psutil
52+
$ conda install -c plotly plotly-orca psutil requests
5653
```
5754

58-
**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](https://conda.io/miniconda.html) (~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.
55+
**Note:** Even if you do not 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](https://conda.io/miniconda.html) (~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.
5956

6057
##### npm + pip
6158
You can use the [npm](https://www.npmjs.com/get-npm) package manager to install `orca` (and its `electron` dependency), and then use pip to install `psutil`:
6259

6360
```
6461
$ npm install -g electron@1.8.4 orca
65-
$ pip install psutil
62+
$ pip install psutil requests
6663
```
6764

6865
##### Standalone Binaries + pip
6966
If you are unable to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca [README](https://github.com/plotly/orca) to install orca and add it to your system `PATH`. Then use pip to install `psutil`.
7067

7168
```
72-
$ pip install psutil
69+
$ pip install psutil requests
7370
```
7471
<!-- #endregion -->
7572

7673
### Create a Figure
7774
Now let's create a simple scatter plot with 100 random points of variying color and size.
7875

7976
```python
80-
from plotly.offline import iplot, init_notebook_mode
8177
import plotly.graph_objs as go
82-
import plotly.io as pio
83-
84-
import os
8578
import numpy as np
86-
```
87-
88-
We'll configure the notebook for use in [offline](https://plot.ly/python/getting-started/#initialization-for-offline-plotting) mode
89-
90-
```python
91-
init_notebook_mode(connected=True)
92-
```
9379

94-
```python
9580
N = 100
9681
x = np.random.rand(N)
9782
y = np.random.rand(N)
9883
colors = np.random.rand(N)
99-
sz = np.random.rand(N)*30
84+
sz = np.random.rand(N) * 30
10085

10186
fig = go.Figure()
102-
fig.add_scatter(x=x,
103-
y=y,
104-
mode='markers',
105-
marker={'size': sz,
106-
'color': colors,
107-
'opacity': 0.6,
108-
'colorscale': 'Viridis'
109-
})
110-
iplot(fig)
87+
fig.add_trace(go.Scatter(
88+
x=x,
89+
y=y,
90+
mode="markers",
91+
marker=go.scatter.Marker(
92+
size=sz,
93+
color=colors,
94+
opacity=0.6,
95+
colorscale="Viridis"
96+
)
97+
))
98+
99+
fig.show()
111100
```
112101

113102
### Write Image File
114-
The `plotly.io.write_image` function is used to write an image to a file or file-like python object.
103+
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.
115104

116105
Let's first create an output directory to store our images
117106

118107
```python
119-
if not os.path.exists('images'):
120-
os.mkdir('images')
108+
import os
109+
110+
if not os.path.exists("images"):
111+
os.mkdir("images")
121112
```
122113

123-
If you are running this notebook live, click to [open the output directory](./images) so you can examine the images as they're written.
114+
If you are running this notebook live, click to [open the output directory](./images) so you can examine the images as they are written.
124115

125116

126117
#### Raster Formats: PNG, JPEG, and WebP
@@ -129,19 +120,19 @@ If you are running this notebook live, click to [open the output directory](./im
129120
Orca can output figures to several raster image formats including **PNG**, ...
130121

131122
```python
132-
pio.write_image(fig, 'images/fig1.png')
123+
fig.write_image("images/fig1.png")
133124
```
134125

135126
**JPEG**, ...
136127

137128
```python
138-
pio.write_image(fig, 'images/fig1.jpeg')
129+
fig.write_image("images/fig1.jpeg")
139130
```
140131

141132
and **WebP**
142133

143134
```python
144-
pio.write_image(fig, 'images/fig1.webp')
135+
fig.write_image("images/fig1.webp")
145136
```
146137

147138
#### Vector Formats: SVG and PDF...
@@ -150,31 +141,31 @@ pio.write_image(fig, 'images/fig1.webp')
150141
Orca can also output figures in several vector formats including **SVG**, ...
151142

152143
```python
153-
pio.write_image(fig, 'images/fig1.svg')
144+
fig.write_image("images/fig1.svg")
154145
```
155146

156147
**PDF**, ...
157148

158149
```python
159-
pio.write_image(fig, 'images/fig1.pdf')
150+
fig.write_image("images/fig1.pdf")
160151
```
161152

162153
and **EPS** (requires the poppler library)
163154

164155
```python
165-
pio.write_image(fig, 'images/fig1.eps')
156+
fig.write_image("images/fig1.eps")
166157
```
167158

168159
**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.
169160

170161

171162
### Get Image as Bytes
172-
The `plotly.io.to_image` function is used to return an image as a bytes object.
163+
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.
173164

174165
Let convert the figure to a **PNG** bytes object...
175166

176167
```python
177-
img_bytes = pio.to_image(fig, format='png')
168+
img_bytes = fig.to_image(format="png")
178169
```
179170

180171
and then display the first 20 bytes.
@@ -195,35 +186,11 @@ Image(img_bytes)
195186
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.
196187

197188
```python
198-
img_bytes = pio.to_image(fig, format='png', width=600, height=350, scale=2)
189+
img_bytes = fig.to_image(format="png", width=600, height=350, scale=2)
199190
Image(img_bytes)
200191
```
201192

202193
### Summary
203-
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.
194+
In summary, to export high-quality static images from plotly.py, all you need to do is install orca, psutil, and requests 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).
204195

205196
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](../orca-management/) section.
206-
207-
```python
208-
from IPython.display import display, HTML
209-
210-
display(HTML('<link href="//fonts.googleapis.com/css?family=Open+Sans:600,400,300,200|Inconsolata|Ubuntu+Mono:400,700" rel="stylesheet" type="text/css" />'))
211-
display(HTML('<link rel="stylesheet" type="text/css" href="http://help.plot.ly/documentation/all_static/css/ipython-notebook-custom.css">'))
212-
213-
! pip install git+https://github.com/plotly/publisher.git --upgrade
214-
import publisher
215-
publisher.publish(
216-
'static-image-export.ipynb', 'python/static-image-export/', 'Static Image Export | plotly',
217-
'Plotly allows you to save static images of your plots. Save the image to your local computer, or embed it inside your Jupyter notebooks as a static image.',
218-
title = 'Static Image Export | plotly',
219-
name = 'Static Image Export',
220-
thumbnail='thumbnail/static-image-export.png',
221-
language='python',
222-
uses_plotly_offline=True,
223-
page_type='example_index', has_thumbnail='true', display_as='file_settings', order=1,
224-
ipynb='~notebook_demo/252')
225-
```
226-
227-
```python
228-
229-
```

0 commit comments

Comments
 (0)