FFFF better docs on use in jupyterlab and ipython by kushalkolar · Pull Request #843 · fastplotlib/fastplotlib · GitHub
[go: up one dir, main page]
Skip to content

better docs on use in jupyterlab and ipython #843

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.

Sign up for GitHub

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

Merged
clewis7 merged 10 commits into from
Jun 2, 2025
Merged

better docs on use in jupyterlab and ipython #843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8fe7681
betters on use in jupyterlab and ipython
kushalkolar May 30, 2025
e5e0aac
unintended change to afile
kushalkolar May 30, 2025
2ec842a
unintended change to another file
kushalkolar May 30, 2025
32175bf
more unintended change to another file
kushalkolar May 30, 2025
17d7d93
better explanation
kushalkolar May 30, 2025
d0f003c
see if this works to remove jupyter nb download button in gallery
kushalkolar May 30, 2025
38295b5
clearer
kushalkolar May 30, 2025
300b4a8
heading underline
kushalkolar May 30, 2025
7bb0e51
comment
kushalkolar May 30, 2025
90ed02a
Update docs/source/user_guide/guide.rst
kushalkolar Jun 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@

sphinx_gallery_conf = {
"gallery_dirs": "_gallery",
"notebook_extensions": {}, # remove the download notebook button
"backreferences_dir": "_gallery/backreferences",
"doc_module": ("fastplotlib",),
"image_scrapers": ("pygfx",),
Expand Down
67 changes: 50 additions & 17 deletions docs/source/user_guide/guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -667,28 +667,61 @@ There are several spaces to consider when using ``fastplotlib``:

For more information on the various spaces used by rendering engines please see this `article <https://learnopengl.com/Getting-started/Coordinate-Systems>`_

Using ``fastplotlib`` in an interactive shell
---------------------------------------------
JupyterLab and IPython
----------------------

There are multiple ways to use ``fastplotlib`` in interactive shells, such as ipython.
In ``jupyter lab`` you have the option to embed ``Figures`` in regular output cells, on the side with ``sidecar``,
or show figures in separate Qt windows. Note: Once you have selected a display mode, we do not recommend switching to
a different display mode. Restart the kernel to reliably choose a different display mode. By default, fastplotlib
figures will be embedded in the notebook cell's output.

1) Jupyter
The `quickstart example notebook <https://github.com/fastplotlib/fastplotlib/blob/main/examples/notebooks/quickstart.ipynb>`_
is also a great place to start.

On ``jupyter lab`` the jupyter backend (i.e. ``jupyter_rfb``) is normally selected. This works via
client-server rendering. Images generated on the server are streamed to the client (Jupyter) via a jpeg byte stream.
Events (such as mouse or keyboard events) are then streamed in the opposite direction prompting new images to be generated
by the server if necessary. This remote-frame-buffer approach makes the rendering process very fast. ``fastplotlib`` viusalizations
can be displayed in cell output or on the side using ``sidecar``.
Notebooks and remote rendering
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Qt backend can also optionally be used as well. If ``%gui qt`` is selected before importing ``fastplotlib`` then this backend
will be used instead.
To display the ``Figure`` in the notebook output, the ``fig.show()`` call must be the last line in the code cell. Or
you can use ipython's display call: ``display(fig.show())``.

Lastly, users can also force using ``glfw`` by specifying this as an argument when instantiating a ``Figure`` (i.e. ``Figure(canvas="gflw"``).
To display the figure on the side: ``fig.show(sidecar=True)``

.. note::
Do not mix between gui backends. For example, if you start the notebook using Qt, do not attempt to force using another backend such
as ``jupyter_rfb`` later.
You can make use of all `ipywidget layout <https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Layout.html>`_
options to display multiple figures::

from ipywidgets import VBox, HBox

# stack figures vertically or horizontally
VBox([fig1.show(), fig2.show()])

Again the ``VBox([...])`` call must be the last line in the code cell, or you can use ``display(VBox([...]))``

You can combine ipywidget layouting just like any other ipywidget::

# display a figure on top of two figures laid out horizontally

VBox([
fig1.show(),
HBox([fig2.show(), fig3.show()])
])

Embedded figures will also render if you're using the notebook from a remote computer since rendering is done on the
server side and the client only receives a jpeg stream of rendered frames. This allows you to visualize very large
datasets on remote servers since the rendering is done remotely and you do not transfer any of the raw data to the
client.

You can create dashboards or webapps with ``fastplotlib`` by running the notebook with
`voila <https://github.com/voila-dashboards/voila>`_. This is great for sharing visualizations of very large datasets
that are too large to share over the internet, and creating fast interactive applications for the analysis of very
large datasets.

Qt windows in jupyter and IPython
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2) IPython
Qt windows can also be used for displaying fastplotlib figures in an interactive jupyterlab or IPython. You must run
``%gui qt`` **before** importing ``fastplotlib`` (or ``wgpu``). This would typically be done at the very top of your
notebook.

Users can select between using a Qt backend or gflw using the same methods as above.
Note that this only works if you are using jupyterlab or ipython locally, this cannot be used for remote rendering.
You can forward windows (ex: X11 forwarding) but this is much slower than the remote rendering described in the
previous section.
4 changes: 2 additions & 2 deletions examples/controllers/specify_integers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@
figure.show(maintain_aspect=False)


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/controllers/specify_names.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@
figure.show(maintain_aspect=False)


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/controllers/sync_all.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
figure.show(maintain_aspect=False)


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/cmap_event.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,8 @@ def cmap_changed(ev: fpl.GraphicFeatureEvent):
# change the cmap of graphic image, triggers all other graphics to set the cmap
figure["camera"].graphics[0].cmap = "jet"

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/drag_points.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,8 @@ def end_drag(ev: pygfx.PointerEvent):
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/image_click.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ def click_event(ev: pygfx.PointerEvent):
print(xy)


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/image_data_event.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ def data_changed(ev: fpl.GraphicFeatureEvent):
image_raw.data = img2


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
Expand Down
4 changes: 2 additions & 2 deletions examples/events/key_events.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ def handle_event(ev: pygfx.KeyboardEvent):
figure = iw.figure # ignore, this is just so the docs gallery scraper picks up the figure


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
Expand Down
4 changes: 2 additions & 2 deletions examples/events/line_data_thickness_event.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ def change_data(ev: fpl.GraphicFeatureEvent):
# that causes the sine graphic's thickness to also be set from this value
cosine_graphic.thickness = 10

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/lines_mouse_nearest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ def highlight_nearest(ev: pygfx.PointerEvent):

figure.show()

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/paint_image.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ def on_pointer_up(ev: pygfx.PointerEvent):

figure.show()

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/scatter_click.py
View file
Open in desktop
< 42F0 td id="diff-1267de6c7780b1943d83642a5f3da0943f621db4b735ffde4d8081213f973461R64" data-line-number="64" class="blob-num blob-num-context js-linkable-line-number js-blob-rnum">
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ def highlight_point(ev: pygfx.PointerEvent):
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/scatter_hover.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ def highlight_point(ev: pygfx.PointerEvent):
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/events/scatter_hover_transforms.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,8 @@ def highlight_point(ev: pygfx.PointerEvent):

figure.show(maintain_aspect=False)

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/gridplot/gridplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/gridplot/gridplot_non_square.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/gridplot/gridplot_viewports_check.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/gridplot/multigraphic_gridplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,8 @@ def make_circle(center, radius: float, n_points: int = 75) -> np.ndarray:

figure.show()

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
Expand Down
4 changes: 2 additions & 2 deletions examples/guis/image_widget_imgui.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,8 @@ def process_image(self):
figure = iw.figure


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/guis/imgui_basic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ def _set_data(self):
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/guis/sine_cosine_funcs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,8 @@ def update(self):
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/heatmap/heatmap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@

figure.show()

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/image/image_cmap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@

image_graphic.cmap = "viridis"

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/image/image_rgb.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/image/image_rgbvminvmax.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
image_graphic.vmin = 0.5
image_graphic.vmax = 0.75

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
5 changes: 2 additions & 3 deletions examples/image/image_simple.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,8 @@

figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
5 changes: 2 additions & 3 deletions examples/image/image_small.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,8 @@

figure.show()


# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
4 changes: 2 additions & 2 deletions examples/image/image_vminvmax.py
View file
Open in desktop
221A
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
image_graphic.vmin = 0.5
image_graphic.vmax = 0.75

# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
# please see our docs for using fastplotlib interactively in ipython and jupyter
# NOTE: fpl.loop.run() should not be used for interactive sessions
# See the "JupyterLab and IPython" section in the user guide
if __name__ == "__main__":
print(__doc__)
fpl.loop.run()
Loading
0