You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* add engine kwarg to to_image/write_image functions
* Update Image renderers with engine parameter
* Don't auto-start orca when image renderer is activated because now
we might not end up using orca.
* Added kaleido engine tests
* Python 2.7 mock compatibility
* Update CHANGELOG.md
* Add kaleido test that actually calls Kaleido and checks that the
resulting bytes are reasonable
* Update image export documentation to recommend and describe Kaleido
* Add engine docstring to figure image export methods
* Change kaleido conda channel to plotly since it most likely won't be available on conda-forge initially
* Conda package renamed from kaleido -> python-kaleido
* in README: indicate that Keleido is new and improved and orca is legacy
* Add Kaleido note to orca-management section
* Fix JPEG typo
* Merge "Install Dependency" sections and better explain that Kaleido is new and recommended
* Replace Orca with plotly.py when discussing supported image export formats
Co-authored-by: NickE <[email protected]>
Co-authored-by: Nicolas Kruchten <[email protected]>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
6
6
7
7
### Added
8
8
9
+
- Added image export support using [Kaleido](https://github.com/plotly/Kaleido). The image export backend can be configured using the new `engine` argument to `plotly.io.to_image` and `plotly.io.write_image`. The `engine` argument may be set to `"kaleido"`, `"orca"`, or `"auto"`. The default is `engine="auto"`, in which case the Kaleido backend is enabled if the `kaleido` package from PyPI is installed, otherwise Orca is used. ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
9
10
-`px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
10
11
-`facet_row_spacing` and `facet_col_spacing` added to Plotly Express cartesian 2d functions ([#2614](https://github.com/plotly/plotly.py/pull/2614))
11
12
-`base` added to Plotly Express `bar` and `bar_polar` functions
@@ -30,7 +31,6 @@ This project adheres to [Semantic Versioning](http://semver.org/).
30
31
- Updated Plotly.js to version 1.54.5. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.5/CHANGELOG.md) for more information.
31
32
-`add_traces()` now accepts bare `int`-like values for `rows`/`cols` as well as lists thereof ([#2546](https://github.com/plotly/plotly.py/pull/2546)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!
32
33
33
-
34
34
### Fixed
35
35
36
36
-`row`/`col` now accept `int`-like values, not strictly `int` values ([#2451](https://github.com/plotly/plotly.py/pull/2451)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!
functions in the `plotly.io` module. This functionality requires the
140
+
[`kaleido`](https://github.com/plotly/Kaleido) package which can be installed
141
+
using pip...
142
+
143
+
```
144
+
$ pip install -U kaleido
145
+
```
146
+
147
+
or conda.
148
+
```
149
+
$ conda install -c plotly python-kaleido
150
+
```
151
+
152
+
### Static Image Export with Orca
153
+
While Kaleido is now the recommended image export approach because it is easier to install and more widely compatible, image export can also be supported
154
+
by the legacy [orca](https://github.com/plotly/orca) command line utility and the
Copy file name to clipboardExpand all lines: doc/python/orca-management.md
+61-5
Original file line number
Diff line number
Diff line change
@@ -34,16 +34,72 @@ jupyter:
34
34
---
35
35
36
36
### Overview
37
-
This section covers the lower-level details of how plotly.py uses orca to perform static image generation. Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
37
+
This section covers the lower-level details of how plotly.py can use orca to perform static image generation.
38
38
39
-
### What is Orca?
39
+
> Orca is no longer the recommended way to do static image export. We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section .
40
+
41
+
Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
42
+
43
+
### What is orca?
40
44
Orca is an [Electron](https://electronjs.org/) application that inputs plotly figure specifications and converts them into static images. Orca can run as a command-line utility or as a long-running server process. In order to provide the fastest possible image export experience, plotly.py launches orca in server mode, and communicates with it over a local port. See https://github.com/plotly/orca for more information.
41
45
42
46
By default, plotly.py launches the orca server process the first time an image export operation is performed, and then leaves it running until the main Python process exits. Because of this, the first image export operation in an interactive session will typically take a couple of seconds, but then all subsequent export operations will be significantly faster, since the server is already running.
43
47
48
+
### Installing orca
49
+
There are 3 general approaches to installing orca and its Python dependencies.
50
+
51
+
##### conda
52
+
Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
**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==1.2.1` and the orca executable will be available system wide.
58
+
59
+
##### npm + pip
60
+
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`:
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`.
Now let's create a simple scatter plot with 100 random points of variying color and size.
102
+
Now let's create a simple scatter plot with 100 random points of varying color and size.
47
103
48
104
```python
49
105
import plotly.graph_objects as go
@@ -198,7 +254,7 @@ In addition to the `executable` property, the `plotly.io.orca.config` object can
198
254
-**`timeout`**: The number of seconds of inactivity required before the orca server is shut down. For example, if timeout is set to 20, then the orca server will shutdown once is has not been used for at least 20 seconds. If timeout is set to `None` (the default), then the server will not be automatically shut down due to inactivity.
199
255
-**`default_width`**: The default pixel width to use on image export.
200
256
-**`default_height`**: The default pixel height to use on image export.
201
-
-**`default_scale`**: The default image scale facor applied on image export.
257
+
-**`default_scale`**: The default image scale factor applied on image export.
202
258
-**`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`.
203
259
-**`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.
204
260
-**`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](https://github.com/plotly/plotly.js/tree/master/dist/topojson).
@@ -207,4 +263,4 @@ In addition to the `executable` property, the `plotly.io.orca.config` object can
207
263
208
264
209
265
### Saving Configuration Settings
210
-
Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method. Saved setting will be automatically loaded at the start of future sessions.
266
+
Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method. Saved setting will be automatically loaded at the start of future sessions.
Copy file name to clipboardExpand all lines: doc/python/static-image-export.md
+51-52
Original file line number
Diff line number
Diff line change
@@ -37,39 +37,27 @@ jupyter:
37
37
38
38
### Interactive vs Static Export
39
39
40
-
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, JEPG, SVG or PDF or you can [export them to HTML files which can be opened in a browser and remain interactive](/python/interactive-html-export/). This page explains how to do the former.
40
+
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](/python/interactive-html-export/). This page explains how to do the former.
41
41
42
42
43
43
<!-- #region -->
44
44
#### Install Dependencies
45
-
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.
46
-
47
-
##### conda
48
-
Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
45
+
Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended) or [orca](https://github.com/plotly/orca) (legacy). The `kaleido` package can be installed using pip...
**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==1.2.1` and the orca executable will be available system wide.
54
-
55
-
##### npm + pip
56
-
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`:
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`.
55
+
While Kaleido is now the recommended approach, image export can also be supported by the legacy [orca](https://github.com/plotly/orca) command line utility. See the [Orca Management](/python/orca-management/) section for instructions on installing, configuring, and troubleshooting orca.
65
56
66
-
```
67
-
$ pip install psutil requests
68
-
```
69
57
<!-- #endregion -->
70
58
71
59
### Create a Figure
72
-
Now let's create a simple scatter plot with 100 random points of variying color and size.
60
+
Now let's create a simple scatter plot with 100 random points of varying color and size.
73
61
74
62
```python
75
63
import plotly.graph_objects as go
@@ -116,7 +104,7 @@ If you are running this notebook live, click to [open the output directory](./im
116
104
#### Raster Formats: PNG, JPEG, and WebP
117
105
118
106
119
-
Orca can output figures to several raster image formats including **PNG**, ...
107
+
plotly.py can output figures to several raster image formats including **PNG**, ...
**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.
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).
179
+
<!-- #region -->
180
+
### Specify Image Export Engine
181
+
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.
182
+
183
+
Here is an example of specifying that orca should be used:
184
+
```python
185
+
fig.to_image(format="png", engine="orca")
186
+
```
187
+
188
+
And, here is an example of specifying that Kaleido should be used:
189
+
```python
190
+
fig.to_image(format="png", engine="kaleido")
191
+
```
192
+
193
+
<!-- #endregion -->
220
194
221
-
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](/python/orca-management/) section.
195
+
<!-- #region -->
196
+
### Image Export Settings (Kaleido)
197
+
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`
198
+
199
+
```python
200
+
import plotly.io as pio
201
+
pio.kaleido.scope.default_format ="svg"
202
+
```
203
+
204
+
Here is a complete listing of the available image export settings:
205
+
206
+
-**`default_width`**: The default pixel width to use on image export.
207
+
-**`default_height`**: The default pixel height to use on image export.
208
+
-**`default_scale`**: The default image scale factor applied on image export.
209
+
-**`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`.
210
+
-**`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.
211
+
-**`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](https://github.com/plotly/plotly.js/tree/master/dist/topojson).
212
+
-**`mapbox_access_token`**: The default Mapbox access token.
213
+
214
+
<!-- #endregion -->
215
+
216
+
### Image Export Settings (Orca)
217
+
See the [Orca Management](/python/orca-management/) section for information on how to specify image export settings when using orca.
218
+
219
+
### Summary
220
+
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).
0 commit comments