Skip to content

Commit 09db45d

Browse files
kushalkolarclewis7
kushalkolar
and
clewis7
authored
better docs on use in jupyterlab and ipython (#843)
* betters on use in jupyterlab and ipython * unintended change to afile * unintended change to another file * more unintended change to another file * better explanation * see if this works to remove jupyter nb download button in gallery * clearer * heading underline * comment * Update docs/source/user_guide/guide.rst Co-authored-by: Caitlin Lewis <[email protected]> --------- Co-authored-by: Caitlin Lewis <[email protected]>
1 parent 15ab65f commit 09db45d

79 files changed

Lines changed: 206 additions & 174 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/source/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@
4949

5050
sphinx_gallery_conf = {
5151
"gallery_dirs": "_gallery",
52+
"notebook_extensions": {}, # remove the download notebook button
5253
"backreferences_dir": "_gallery/backreferences",
5354
"doc_module": ("fastplotlib",),
5455
"image_scrapers": ("pygfx",),

‎docs/source/user_guide/guide.rst‎

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -667,28 +667,61 @@ There are several spaces to consider when using ``fastplotlib``:
667667

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

670-
Using ``fastplotlib`` in an interactive shell
671-
---------------------------------------------
670+
JupyterLab and IPython
671+
----------------------
672672

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

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

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

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

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

688-
.. note::
689-
Do not mix between gui backends. For example, if you start the notebook using Qt, do not attempt to force using another backend such
690-
as ``jupyter_rfb`` later.
689+
You can make use of all `ipywidget layout <https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Layout.html>`_
690+
options to display multiple figures::
691+
692+
from ipywidgets import VBox, HBox
693+
694+
# stack figures vertically or horizontally
695+
VBox([fig1.show(), fig2.show()])
696+
697+
Again the ``VBox([...])`` call must be the last line in the code cell, or you can use ``display(VBox([...]))``
698+
699+
You can combine ipywidget layouting just like any other ipywidget::
700+
701+
# display a figure on top of two figures laid out horizontally
702+
703+
VBox([
704+
fig1.show(),
705+
HBox([fig2.show(), fig3.show()])
706+
])
707+
708+
Embedded figures will also render if you're using the notebook from a remote computer since rendering is done on the
709+
server side and the client only receives a jpeg stream of rendered frames. This allows you to visualize very large
710+
datasets on remote servers since the rendering is done remotely and you do not transfer any of the raw data to the
711+
client.
712+
713+
You can create dashboards or webapps with ``fastplotlib`` by running the notebook with
714+
`voila <https://github.com/voila-dashboards/voila>`_. This is great for sharing visualizations of very large datasets
715+
that are too large to share over the internet, and creating fast interactive applications for the analysis of very
716+
large datasets.
717+
718+
Qt windows in jupyter and IPython
719+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
691720

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

694-
Users can select between using a Qt backend or gflw using the same methods as above.
725+
Note that this only works if you are using jupyterlab or ipython locally, this cannot be used for remote rendering.
726+
You can forward windows (ex: X11 forwarding) but this is much slower than the remote rendering described in the
727+
previous section.

‎examples/controllers/specify_integers.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@
4343
figure.show(maintain_aspect=False)
4444

4545

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

‎examples/controllers/specify_names.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@
4040
figure.show(maintain_aspect=False)
4141

4242

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

‎examples/controllers/sync_all.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
figure.show(maintain_aspect=False)
2424

2525

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

‎examples/events/cmap_event.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,8 +68,8 @@ def cmap_changed(ev: fpl.GraphicFeatureEvent):
6868
# change the cmap of graphic image, triggers all other graphics to set the cmap
6969
figure["camera"].graphics[0].cmap = "jet"
7070

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

‎examples/events/drag_points.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,8 +92,8 @@ def end_drag(ev: pygfx.PointerEvent):
9292
figure.show()
9393

9494

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

‎examples/events/image_click.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ def click_event(ev: pygfx.PointerEvent):
3737
print(xy)
3838

3939

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

‎examples/events/image_data_event.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ def data_changed(ev: fpl.GraphicFeatureEvent):
4848
image_raw.data = img2
4949

5050

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

‎examples/events/key_events.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,8 @@ def handle_event(ev: pygfx.KeyboardEvent):
7777
figure = iw.figure # ignore, this is just so the docs gallery scraper picks up the figure
7878

7979

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

0 commit comments

Comments
 (0)