Skip to content

Commit 6627b0b

Browse files
clewis7clewis7
committed
start guide based on new API changes
1 parent 9a309ef commit 6627b0b

6 files changed

Lines changed: 183 additions & 1 deletion

File tree

‎docs/source/_static/guide_hello_world.png‎

Lines changed: 3 additions & 0 deletions
Loading

‎docs/source/_static/guide_image_cmap.png‎

Lines changed: 3 additions & 0 deletions
Loading

‎docs/source/_static/guide_image_slice.png‎

Lines changed: 3 additions & 0 deletions
Loading

‎docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@
5252
intersphinx_mapping = {
5353
"python": ("https://docs.python.org/3", None),
5454
"numpy": ("https://numpy.org/doc/stable/", None),
55-
"pygfx": ("https://pygfx.readthedocs.io/en/latest", None),
55+
"pygfx": ("https://pygfx.com/stable/", None),
5656
"wgpu": ("https://wgpu-py.readthedocs.io/en/latest", None),
5757
}
5858

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Welcome to fastplotlib's documentation!
1111
:caption: User Guide
1212
:maxdepth: 2
1313

14+
Guide <user_guide/guide.rst>
1415
GPU Info <user_guide/gpu>
1516

1617
.. toctree::

‎docs/source/user_guide/guide.rst‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
The `fastplotlib` guide
2+
=======================
3+
4+
Installation
5+
------------
6+
7+
To install use pip:
8+
9+
.. code-block::
10+
11+
pip install -U fastplotlib
12+
13+
or install the bleeding edge from Github:
14+
15+
.. code-block::
16+
17+
pip install -U https://github.com/fastplotlib/fastplotlib/archive/main.zip
18+
19+
20+
What is `fastplotlib`?
21+
----------------------
22+
23+
`fastplotlib` is a cutting-edge plotting library built using the `pygfx <https://github.com/pygfx/pygfx>`_ rendering engine.
24+
The lower level details of the rendering process (i.e. defining a scene, camera, renderer, etc.) are abstracted away, allowing users to focus on their data.
25+
The fundamental goal of `fastplotlib` is to provide a high-level, expressive API that promotes large-scale explorative scientific visualization.
26+
27+
28+
How to use `fastplotlib`
29+
------------------------
30+
31+
Before giving a detailed overview of the library, here is a minimal example::
32+
33+
import fastplotlib as fpl
34+
import numpy as np
35+
36+
fig = fpl.Figure()
37+
38+
data = np.random.rand(512, 512)
39+
40+
image_graphic = fig[0,0].add_image(data=data)
41+
42+
fig.show()
43+
44+
if __name__ == "__main__":
45+
fpl.run()
46+
47+
.. image:: /_static/guide_hello_world.png
48+
49+
50+
This was a simple example of how the `fastplotlib` API works to create a plot, add some data to the plot, and then visualize it.
51+
However, this is just scratching the surface of what we can do with `fastplotlib`.
52+
Next, we will take a look at the building blocks of `fastplotlib` and how they can be used to create more complex visualizations.
53+
54+
**Figure**
55+
56+
The base of any visualization in `fastplotlib` is a `Figure` object. This can be a singular plot or a grid of subplots.
57+
The `Figure` object houses and takes care of the underlying rendering components such as the camera, controller, renderer, and canvas.
58+
59+
Initially, our figure is empty as we have not added any `Graphics`. After defining a `Figure`, we can begin to add `Graphic` objects.
60+
61+
**Graphics**
62+
63+
A `Graphic` can be an image, a line, a scatter, a collection of lines, and more. Graphics have what we like to call `GraphicFeatures` which
64+
are mutable, indexable properties that can be linked to events.
65+
66+
(1) Common `GraphicFeatures`
67+
68+
+--------------+--------------------------------------------------------------------------------------------------------------+
69+
| Feature Name | Description |
70+
+==============+==============================================================================================================+
71+
| Name | Graphic name |
72+
+--------------+--------------------------------------------------------------------------------------------------------------+
73+
| Offset | Offset position of the graphic, [x, y, z] |
74+
+--------------+--------------------------------------------------------------------------------------------------------------+
75+
| Rotation | Graphic rotation quaternion |
76+
+--------------+--------------------------------------------------------------------------------------------------------------+
77+
| Visible | Access or change the visibility |
78+
+--------------+--------------------------------------------------------------------------------------------------------------+
79+
| Deleted | Used when a graphic is deleted, triggers events that can be useful to indicate this graphic has been deleted |
80+
+--------------+--------------------------------------------------------------------------------------------------------------+
81+
82+
(2) Graphic-Specific `GraphicFeatures`
83+
84+
(a) `ImageGraphic`
85+
86+
+------------------------+------------------------------------+
87+
| Feature Name | Description |
88+
+========================+====================================+
89+
| data | Underlying image data |
90+
+------------------------+------------------------------------+
91+
| vmin | Lower contrast limit of an image |
92+
+------------------------+------------------------------------+
93+
| vmax | Upper contrast limit of an image |
94+
+------------------------+------------------------------------+
95+
| cmap | Colormap of an image |
96+
+------------------------+------------------------------------+
97+
98+
(b) `LineGraphic`, `LineCollection`, `LineStack`
99+
100+
+--------------+--------------------------------+
101+
| Feature Name | Description |
102+
+==============+================================+
103+
| data | underlying data of the line(s) |
104+
+--------------+--------------------------------+
105+
| colors | colors of the line(s) |
106+
+--------------+--------------------------------+
107+
| cmap | colormap of the line(s) |
108+
+--------------+--------------------------------+
109+
| thickness | thickness of the line(s) |
110+
+--------------+--------------------------------+
111+
112+
(c) `ScatterGraphic`
113+
114+
+--------------+---------------------------------------+
115+
| Feature Name | Description |
116+
+==============+=======================================+
117+
| data | underlying data of the scatter points |
118+
+--------------+---------------------------------------+
119+
| colors | colors of the scatter points |
120+
+--------------+---------------------------------------+
121+
| cmap | colormap of the scatter points |
122+
+--------------+---------------------------------------+
123+
| sizes | size of the scatter points |
124+
+--------------+---------------------------------------+
125+
126+
(d) `TextGraphic`
127+
128+
+-------------------+---------------------------+
129+
| Feature Name | Description |
130+
+===================+===========================+
131+
| text | data of the text |
132+
+-------------------+---------------------------+
133+
| font_size | size of the text |
134+
+-------------------+---------------------------+
135+
| face_color | color of the text face |
136+
+-------------------+---------------------------+
137+
| outline_color | color of the text outline |
138+
+-------------------+---------------------------+
139+
| outline_thickness | thickness of the text |
140+
+-------------------+---------------------------+
141+
142+
Using our example from above: once we add a `Graphic` to the figure, we can then begin to change its features. ::
143+
144+
image_graphic.cmap = "viridis"
145+
146+
.. image:: /_static/guide_image_cmap.png
147+
148+
`GraphicFeatures` also support slicing and indexing. For example ::
149+
150+
image_graphic.data[::15] = 1
151+
image_graphic.data[15::] = 1
152+
153+
.. image:: /_static/guide_image_slice.png
154+
155+
Now that we have the basics of creating a `Figure`, adding `Graphics` to the `Figure`, and working with `GraphicFeatures` to change or alter a `Graphic`.
156+
Let's take a look at how we can define events to like `Graphics` and their `GraphicFeatures` together.
157+
158+
Events
159+
------
160+
161+
162+
Selectors
163+
---------
164+
165+
`ImageWidget`
166+
-------------
167+
168+
Animations
169+
----------
170+
171+
172+

0 commit comments

Comments
 (0)