Thanks to visit codestin.com
Credit goes to github.com

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

File tree

79 files changed

+206
-174
lines changed

Some content is hidden

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

79 files changed

+206
-174
lines changed

‎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()

‎examples/events/line_data_thickness_event.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ def change_data(ev: fpl.GraphicFeatureEvent):
7272
# that causes the sine graphic's thickness to also be set from this value
7373
cosine_graphic.thickness = 10
7474

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

‎examples/events/lines_mouse_nearest.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ def highlight_nearest(ev: pygfx.PointerEvent):
5555

5656
figure.show()
5757

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

‎examples/events/paint_image.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@ def on_pointer_up(ev: pygfx.PointerEvent):
6464

6565
figure.show()
6666

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

‎examples/events/scatter_click.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ def highlight_point(ev: pygfx.PointerEvent):
5959
figure.show()
6060

6161

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

‎examples/events/scatter_hover.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,8 @@ def highlight_point(ev: pygfx.PointerEvent):
6262
figure.show()
6363

6464

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

‎examples/events/scatter_hover_transforms.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,8 @@ def highlight_point(ev: pygfx.PointerEvent):
119119

120120
figure.show(maintain_aspect=False)
121121

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

‎examples/gridplot/gridplot.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@
2626
figure.show()
2727

2828

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

‎examples/gridplot/gridplot_non_square.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
figure.show()
2525

2626

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

‎examples/gridplot/gridplot_viewports_check.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@
3030
figure.show()
3131

3232

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

‎examples/gridplot/multigraphic_gridplot.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,8 +110,8 @@ def make_circle(center, radius: float, n_points: int = 75) -> np.ndarray:
110110

111111
figure.show()
112112

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

‎examples/guis/image_widget_imgui.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,8 @@ def process_image(self):
7575
figure = iw.figure
7676

7777

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

‎examples/guis/imgui_basic.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,8 @@ def _set_data(self):
116116
figure.show()
117117

118118

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

‎examples/guis/sine_cosine_funcs.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,8 +179,8 @@ def update(self):
179179
figure.show()
180180

181181

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

‎examples/heatmap/heatmap.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@
2626

2727
figure.show()
2828

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

‎examples/image/image_cmap.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@
2222

2323
image_graphic.cmap = "viridis"
2424

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

‎examples/image/image_rgb.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
figure.show()
2222

2323

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

‎examples/image/image_rgbvminvmax.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
image_graphic.vmin = 0.5
2424
image_graphic.vmax = 0.75
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/image/image_simple.py

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,8 @@
2020

2121
figure.show()
2222

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

‎examples/image/image_small.py

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@
2222

2323
figure.show()
2424

25-
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
25+
# NOTE: fpl.loop.run() should not be used for interactive sessions
26+
# See the "JupyterLab and IPython" section in the user guide
2827
if __name__ == "__main__":
2928
print(__doc__)
3029
fpl.loop.run()

‎examples/image/image_vminvmax.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
image_graphic.vmin = 0.5
2424
image_graphic.vmax = 0.75
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()

0 commit comments

Comments
 (0)