Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add user guide documentation for bokeh.io.export #6292

Merged
merged 7 commits into from May 30, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions bokeh/io.py
Expand Up @@ -646,6 +646,9 @@ def export(obj, filename=None):
Responsive sizing_modes may generate layouts with unexpected size and
aspect ratios. It is recommended to use the default ``fixed`` sizing mode.

.. warning::
Glyphs that are rendered via webgl won't be included in the generated PNG.

'''
image = _get_screenshot_as_png(obj)

Expand Down
Binary file added sphinx/source/_images/unemployment.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions sphinx/source/_images/unemployment.svg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions sphinx/source/docs/user_guide.rst
Expand Up @@ -69,6 +69,9 @@ topic:
:ref:`userguide_extensions`
Adding new capability to Bokeh with custom user extensions.

:ref:`userguide_export`
Learn how to export Bokeh layouts as PNGs and SVGs.

:ref:`userguide_info`
See where to go next for more information and examples.

Expand Down
116 changes: 116 additions & 0 deletions sphinx/source/docs/user_guide/export.rst
@@ -0,0 +1,116 @@
.. _userguide_export:

Exporting Plots
===============

.. _userguide_export_png:

PNG Generation
--------------

Bokeh can generate RGBA-format Portable Network Graphics (PNG) images from
layouts using the |export| function. This functionality uses a headless browser
called WebKit to render the layout in memory and then capture a screenshot. The
generated image will be of the same dimensions as the source layout.

In order to create a PNG with a transparent background, users should set the
``Plot.background_fill_color`` and ``Plot.border_fill_color`` properties to
``None``.

Limitations
~~~~~~~~~~~

Responsive sizing_modes may generate layouts with unexpected size and aspect
ratios. It is recommended to use the default ``fixed`` sizing mode. Also,
glyphs that are rendered via webgl won't be included in the generated PNG, so
it's suggested to use the default ``Plot.webgl=True`` attribute.

Additional dependencies
~~~~~~~~~~~~~~~~~~~~~~~

In order to use the |export| function, users have to install some additional
dependencies. These dependencies can be installed via conda:

.. code-block:: sh

conda install selenium phantomjs pillow

Alternatively, you can install phantomjs from npm via

.. code-block:: sh

npm install -g phantomjs-prebuilt

Example usage
~~~~~~~~~~~~~

Usage is similar to the |save| and |show| functions.

.. code-block:: python

from bokeh.io import export

export(plot, filename="plot.png")

.. image:: /_images/unemployment.png

.. _userguide_export_svg:

SVG Generation
--------------

Bokeh also supports replacing the HTML5 Canvas plot output with an SVG element
that can be edited in image editing programs such as Adobe Illustrator and/or
converted to PDFs. This functionality uses a JavaScript library called
canvas2svg to mock the normal Canvas element and its methods with an SVG
element.

The SVG output isn't as performant as the default Canvas backend when it comes
to rendering large number of glyphs or handling lots of user interactions like
panning.

Like PNGs, in order to create a SVG with a transparent background, users
should set the ``Plot.background_fill_color`` and ``Plot.border_fill_color``
properties to ``None``.

Limitations
~~~~~~~~~~~

It's not possible to create a single SVG for a layout of plots, as each plot
is it's own distinct SVG element. Alternatively, it's possible to download a
SVG plot using a SaveTool from the toolbar. However, currently an SVG export
of a plot with a toolbar will have a blank area where the toolbar was rendered
in the browser.

Example usage
~~~~~~~~~~~~~

The SVG backend is activated by setting the ``Plot.output_backend`` attribute
to ``"svg"``.

.. code-block:: python

# option one
plot = Plot(output_backend="svg")
# option two
plot.output_backend = "svg"

.. image:: /_images/unemployment.svg

Exporting a SVG Image
~~~~~~~~~~~~~~~~~~~~~

The simplest way to export a SVG plot is to install a browser bookmarklet from
the New York Times called `SVG-Crowbar`_. When clicked, it runs a snippet of
JavaScript and adds a prompt on the page to download the plot. It's written to
work with Chrome and should work with Firefox in most cases.

Alternatively, it's possible to download a SVG plot using the ``SaveTool``, but
the toolbar isn't captured though it figures into the plot layout solver
calculations. It's not great, but a workable option.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is a bit awkward, maybe:

Alternatively, it's possible to download a SVG plot using a SaveTool from the toolbar. However, currently an SVG export of a plot with a toolbar will have a blank area where the toolbar was rendered in the browser.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed


.. |export| replace:: :func:`~bokeh.io.export`
.. |save| replace:: :func:`~bokeh.io.save`
.. |show| replace:: :func:`~bokeh.io.show`

.. _SVG-Crowbar: http://nytimes.github.io/svg-crowbar/
1 change: 1 addition & 0 deletions sphinx/source/index.rst
Expand Up @@ -43,6 +43,7 @@ the :ref:`devguide`.
docs/user_guide/cli
docs/user_guide/server
docs/user_guide/embed
docs/user_guide/export
docs/user_guide/webgl
docs/user_guide/geo
docs/user_guide/bokehjs
Expand Down