Kaleido docs updates for v1 #5111
Conversation
…ly.py into kaleido-docs-updates
|
|
||
| `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. | ||
|
|
There was a problem hiding this comment.
TODO: Confirm status of mathjax and topojson before full release and adjust docs.
| ``` | ||
|
|
||
| #### Display Bytes as Image Using `IPython.display.Image` | ||
| ### Display Bytes as Image Using `IPython.display.Image` |
There was a problem hiding this comment.
Wondering if we still need this section... can't you achieve (roughly) the same thing by doing fig.show(renderer="png")?
There was a problem hiding this comment.
Yes, I think you could achieve roughly the same thing fig.show(renderer="png"). I wonder if there's another use case for something you'd do with the output of fig.to_image(format="png"). I will look into it.
| 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](https://qtconsole.readthedocs.io/en/stable/)! | ||
|
|
||
| ```python | ||
| from IPython.display import Image | ||
| Image(img_bytes) | ||
| ``` | ||
|
|
||
| ### Change Image Dimensions and Scale | ||
| ## Change Image Dimensions and Scale | ||
| 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. |
There was a problem hiding this comment.
What is a "logical pixel"?
Does it have something to do with the fact that vector images don't have a pixel width/height? I am honestly still not QUITE sure how the width and height parameters are used when exporting to SVG or PDF (though I can tell the resulting image has the right aspect ratio).
|
This looks great @LiamConnors. It would also be great to add a page summarizing the changes in Plotly 6.1 / Kaleido v1 and how to migrate existing code. (Along the lines of https://plotly.com/python/mapbox-to-maplibre/) |
Co-authored-by: Emily KL <[email protected]>
Co-authored-by: Emily KL <[email protected]>
Co-authored-by: Emily KL <[email protected]>
Co-authored-by: Emily KL <[email protected]>
Thanks @emilykl. I created this page here https://github.com/plotly/plotly.py/pull/5111/files#diff-e643b2817374c0b1c375f9cf88532be52a149fca8dda66fb0054d8ad031c29d8 |
|
Sorry @LiamConnors, missed that page! Thanks! |
|
|
||
| ## Engine Parameter | ||
|
|
||
| The `engine` parameter on static image export methods and functions is deprecated with this Plotly.py release and will be removed after September 2025. You'll need to update your code to remove references to this parameter. For example, `fig.to_image(format="png", engine="orca")` or `fig.to_image(format="png", engine="kaleido")` needs to be updated to `fig.to_image(format="png")`. This change applies to: `fig.to_image`, `fig.write_image`, `plotly.io.to_image`, and `plotly.io.write_image`. |
There was a problem hiding this comment.
Maybe add an additional sentence here clarifying which engine is used when the 'engine' parameter is not provided:
- If Kaleido is installed, Kaleido is used
- Otherwise:
- Currently: If Orca is installed, Orca is used (with a deprecation warning).
- Once Orca support is dropped, an error will be raised.
There was a problem hiding this comment.
I added a note that it will use Kaleido after the engine parameter is removed if Kaleido is installed and otherwise will raise an error.
Co-authored-by: Emily KL <[email protected]>
…ly.py into kaleido-docs-updates
This PR adds changes for Kaleido v1