fastplotlib · kushalkolar · Apr 12, 2024 · Apr 7, 2024 · Apr 7, 2024 · Apr 7, 2024
@@ -58,9 +58,9 @@ Fastplotlib uses the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine
 plotting library. Some degree of familiarity with [`pygfx`](https://github.com/pygfx/pygfx) or rendering engines may 
 be useful depending on the type of contribution you're working on. 
 
-There are currently 2 major subpackages within `fastplotlib`, `layouts` and `graphics`. The two user-facing public 
-classes within `layouts` are `Plot` and `GridPlot`. A user is intended to create either a `Plot` or `GridPlot`, and 
-then add *Graphics* to that layout, such as an `ImageGraphic`, `LineGraphic`, etc. 
+There are currently 2 major subpackages within `fastplotlib`, `layouts` and `graphics`. The user-facing public 
+class within `layouts` is `Figure`. A user is intended to create a `Figure`, and 
+then add *Graphics* to subplots within that `Figure`. 
 
 ### Graphics
 
@@ -70,7 +70,7 @@ fastplotlib graphics, such as `ImageGraphic`, `ScatterGraphic`, etc. inherit fro
 These might change in the future (ex. `Graphic.position_x` etc.).
 
 All graphics can be given a string name for the user's convenience. This allows graphics to be easily accessed from 
-plots, ex: `plot["some_image"]`.
+plots, ex: `subplot["some_image"]`.
 
 All graphics contain a `world_object` property which is just the `pygfx.WorldObject` that this graphic uses. Fastplotlib 
 keeps a *private* global dictionary of all `WorldObject` instances and users are only given a weakref proxy to this world object. 
@@ -119,8 +119,8 @@ after the aforementioned `Input` class PR in `pygfx` and after https://github.co
 
 #### PlotArea
 
-This is the main base class within layouts. Every kind of "plot area", whether it's a single `Plot`, subplots within a 
-`GridPlot`, or `Dock` area, use `PlotArea` in some way.
+This is the main base class within layouts. Subplots within a `Figure` and `Dock` areas within a `Subplot`, 
+inherit from `PlotArea`.
 
 `PlotArea` has the following key properties that allow it to be a "plot area" that can be used to view graphical objects:
 
@@ -135,10 +135,10 @@ Abstract method that must be implemented in subclasses:
 
 * get_rect - musut return [x, y, width, height] that defines the viewport rect for this `PlotArea`
 
-Properties specifically used by subplots in a gridplot:
+Properties specifically used by subplots in a Figure:
 
-* parent - A parent if relevant, used by individual `Subplots` in `GridPlot`, and by `Dock` which are "docked" subplots at the edges of a subplot.
-* position - if a subplot within a gridplot, it is the position of this subplot within the `GridPlot`
+* parent - A parent if relevant, used by individual `Subplots` in `Figure`, and by `Dock` which are "docked" subplots at the edges of a subplot.
+* position - if a subplot within a Figure, it is the position of this subplot within the `Figure`
 
 Other important properties:
 
@@ -182,18 +182,13 @@ Subplot has one property that is not in `PlotArea`:
 
 The key method in `Subplot` is an implementation of `get_rect` that returns the viewport rect for this subplot.
 
-#### Plot, GridPlot, and Frame
+#### Figure
 
-Now that we have understood `PlotArea` and `Subplot` we need a way for the user to create either single plots or gridplots 
-and display them!
+Now that we have understood `PlotArea` and `Subplot` we need a way for the user to create them!
 
-There's one more class to talk about, `Frame`. This is a class that "frames" a `Plot` or `GridPlot`. Depending on 
-whether the plot's `Canvas` is a Qt or jupyter canvas, `Frame.show()` will create a plot toolbar and place this toolbar 
-below the `Canvas`. If using a glfw canvas it just returns the canvas.
-
-`Plot` and `GridPlot` both inherit from `Frame` which gives them `show()`. `Plot` is just a single `Subplot` with the 
-addition of `Frame`. `GridPlot.__init__` basically does a lot of parsing of user arguments to determine how to create 
-the subplots. All subplots within a `GridPlot` share the same canvas and use different viewports to create the subplots.
+A `Figure` contains a grid of subplot and has methods such as `show()` to output the figure.
+`Figure.__init__` basically does a lot of parsing of user arguments to determine how to create 
+the subplots. All subplots within a `Figure` share the same canvas and use different viewports to create the subplots.
 
 ## Tests in detail
 
@@ -216,6 +211,9 @@ ground-truth image are within that tolerance the test will pass.
 To run tests:
 
 ```bash
+# tests basic backend functionality
+WGPU_FORCE_OFFSCREEN=1 pytest -v -s tests/
+
 # desktop examples
 pytest -v examples
 

@@ -7,24 +7,23 @@
 [![CI](https://github.com/kushalkolar/fastplotlib/actions/workflows/ci.yml/badge.svg)](https://github.com/kushalkolar/fastplotlib/actions/workflows/ci.yml)
 [![PyPI version](https://badge.fury.io/py/fastplotlib.svg)](https://badge.fury.io/py/fastplotlib)
 [![Documentation Status](https://readthedocs.org/projects/fastplotlib/badge/?version=latest)](https://fastplotlib.readthedocs.io/en/latest/?badge=latest)
-[![Gitter](https://badges.gitter.im/fastplotlib/community.svg)](https://gitter.im/fastplotlib/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 [**Installation**](https://github.com/kushalkolar/fastplotlib#installation) | 
 [**GPU Drivers**](https://github.com/kushalkolar/fastplotlib#graphics-drivers) | 
 [**Documentation**](https://github.com/fastplotlib/fastplotlib#documentation) | 
 [**Examples**](https://github.com/kushalkolar/fastplotlib#examples) | 
 [**Contributing**](https://github.com/kushalkolar/fastplotlib#heart-contributing)
 
-Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine that can utilize [Vulkan](https://en.wikipedia.org/wiki/Vulkan), [DX12](https://en.wikipedia.org/wiki/DirectX#DirectX_12), or [Metal](https://developer.apple.com/metal/) via WGPU, so it is very fast! We also aim to be an expressive plotting library that enables rapid prototyping for large scale explorative scientific visualization.
+Next-gen plotting library built using the [`pygfx`](https://github.com/pygfx/pygfx) rendering engine that can utilize [Vulkan](https://en.wikipedia.org/wiki/Vulkan), [DX12](https://en.wikipedia.org/wiki/DirectX#DirectX_12), or [Metal](https://developer.apple.com/metal/) via WGPU, so it is very fast! `fastplotlib` also aims to be an expressive plotting library that enables rapid prototyping for large scale explorative scientific visualization.
 
 ![scipy-fpl](https://github.com/fastplotlib/fastplotlib/assets/9403332/b981a54c-05f9-443f-a8e4-52cd01cd802a)
 
 ### SciPy 2023 Talk
 
 [![fpl_thumbnail](http://i3.ytimg.com/vi/Q-UJpAqljsU/hqdefault.jpg)](https://www.youtube.com/watch?v=Q-UJpAqljsU)
 
-Notebooks from talk: https://github.com/fastplotlib/fastplotlib-scipy2023 
-
+Note that the API is currently evolving quickly. We recommend using the latest notebooks from the repo but the general 
+concepts are similar to those from the API shown in the video.
 
 # Supported frameworks
 
@@ -36,9 +35,9 @@ Notebooks from talk: https://github.com/fastplotlib/fastplotlib-scipy2023
 :heavy_check_mark: `wxPython`
 
 **Notes:**\
-:heavy_check_mark: Non-blocking Qt output is supported in ipython and notebooks by using [`%gui qt`](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-gui) before creating plots. This hook only supports pyqt6 at the moment.\
+:heavy_check_mark: Non-blocking Qt/PySide output is supported in ipython and notebooks by using [`%gui qt`](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-gui). This **must** be called *before* importing `fastplotlib`!
 :grey_exclamation: We do not officially support `jupyter notebook` through `jupyter_rfb`, this may change with notebook v7\
-:disappointed: [`jupyter_rfb`](https://github.com/vispy/jupyter_rfb) does not work in collab yet, see https://github.com/vispy/jupyter_rfb/pull/77 
+:disappointed: [`jupyter_rfb`](https://github.com/vispy/jupyter_rfb) does not work in collab, see https://github.com/vispy/jupyter_rfb/pull/77 
 
 > **Note**
 > 
@@ -169,4 +168,4 @@ WGPU uses Metal instead of Vulkan on Mac. You will need at least Mac OSX 10.13.
 
 We welcome contributions! See the contributing guide: https://github.com/kushalkolar/fastplotlib/blob/main/CONTRIBUTING.md
 
-You can also take a look at our [**Roadmap for 2024**](https://github.com/kushalkolar/fastplotlib/issues/55) and [**Issues**](https://github.com/kushalkolar/fastplotlib/issues) for ideas on how to contribute!
+You can also take a look at our [**Roadmap for 2025**](https://github.com/kushalkolar/fastplotlib/issues/55) and [**Issues**](https://github.com/kushalkolar/fastplotlib/issues) for ideas on how to contribute!
@@ -0,0 +1,33 @@
+.. _api.Deleted:
+
+Deleted
+*******
+
+=======
+Deleted
+=======
+.. currentmodule:: fastplotlib.graphics._features
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: Deleted_api
+
+    Deleted
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: Deleted_api
+
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: Deleted_api
+
+    Deleted.add_event_handler
+    Deleted.block_events
+    Deleted.clear_event_handlers
+    Deleted.remove_event_handler
+
@@ -20,3 +20,4 @@ Graphic Features
     to_gpu_supported_dtype
     LinearSelectionFeature
     LinearRegionSelectionFeature
+    Deleted
@@ -21,10 +21,12 @@ Properties
     :toctree: HeatmapGraphic_api
 
     HeatmapGraphic.children
+    HeatmapGraphic.name
     HeatmapGraphic.position
     HeatmapGraphic.position_x
     HeatmapGraphic.position_y
     HeatmapGraphic.position_z
+    HeatmapGraphic.rotation
     HeatmapGraphic.visible
     HeatmapGraphic.world_object
 
@@ -37,5 +39,6 @@ Methods
     HeatmapGraphic.add_linear_selector
     HeatmapGraphic.link
     HeatmapGraphic.reset_feature
+    HeatmapGraphic.rotate
     HeatmapGraphic.set_feature
 
@@ -21,10 +21,12 @@ Properties
     :toctree: ImageGraphic_api
 
     ImageGraphic.children
+    ImageGraphic.name
     ImageGraphic.position
     ImageGraphic.position_x
     ImageGraphic.position_y
     ImageGraphic.position_z
+    ImageGraphic.rotation
     ImageGraphic.visible
     ImageGraphic.world_object
 
@@ -37,5 +39,6 @@ Methods
     ImageGraphic.add_linear_selector
     ImageGraphic.link
     ImageGraphic.reset_feature
+    ImageGraphic.rotate
     ImageGraphic.set_feature
 
@@ -24,10 +24,12 @@ Properties
     LineCollection.cmap
     LineCollection.cmap_values
     LineCollection.graphics
+    LineCollection.name
     LineCollection.position
     LineCollection.position_x
     LineCollection.position_y
     LineCollection.position_z
+    LineCollection.rotation
     LineCollection.visible
     LineCollection.world_object
 
@@ -42,5 +44,6 @@ Methods
     LineCollection.link
     LineCollection.remove_graphic
     LineCollection.reset_feature
+    LineCollection.rotate
     LineCollection.set_feature
 
@@ -21,10 +21,12 @@ Properties
     :toctree: LineGraphic_api
 
     LineGraphic.children
+    LineGraphic.name
     LineGraphic.position
     LineGraphic.position_x
     LineGraphic.position_y
     LineGraphic.position_z
+    LineGraphic.rotation
     LineGraphic.visible
     LineGraphic.world_object
 
@@ -37,5 +39,6 @@ Methods
     LineGraphic.add_linear_selector
     LineGraphic.link
     LineGraphic.reset_feature
+    LineGraphic.rotate
     LineGraphic.set_feature
 
@@ -24,10 +24,12 @@ Properties
     LineStack.cmap
     LineStack.cmap_values
     LineStack.graphics
+    LineStack.name
     LineStack.position
     LineStack.position_x
     LineStack.position_y
     LineStack.position_z
+    LineStack.rotation
     LineStack.visible
     LineStack.world_object
 
@@ -42,5 +44,6 @@ Methods
     LineStack.link
     LineStack.remove_graphic
     LineStack.reset_feature
+    LineStack.rotate
     LineStack.set_feature
 
@@ -21,10 +21,12 @@ Properties
     :toctree: ScatterGraphic_api
 
     ScatterGraphic.children
+    ScatterGraphic.name
     ScatterGraphic.position
     ScatterGraphic.position_x
     ScatterGraphic.position_y
     ScatterGraphic.position_z
+    ScatterGraphic.rotation
     ScatterGraphic.visible
     ScatterGraphic.world_object
 
@@ -33,4 +35,5 @@ Methods
 .. autosummary::
     :toctree: ScatterGraphic_api
 
+    ScatterGraphic.rotate
 
@@ -22,12 +22,14 @@ Properties
 
     TextGraphic.children
     TextGraphic.face_color
+    TextGraphic.name
     TextGraphic.outline_color
     TextGraphic.outline_size
     TextGraphic.position
     TextGraphic.position_x
     TextGraphic.position_y
     TextGraphic.position_z
+    TextGraphic.rotation
     TextGraphic.text
     TextGraphic.text_size
     TextGraphic.visible
@@ -38,4 +40,5 @@ Methods
 .. autosummary::
     :toctree: TextGraphic_api
 
+    TextGraphic.rotate
 
@@ -0,0 +1,44 @@
+.. _api.Figure:
+
+Figure
+******
+
+======
+Figure
+======
+.. currentmodule:: fastplotlib
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: Figure_api
+
+    Figure
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: Figure_api
+
+    Figure.cameras
+    Figure.canvas
+    Figure.controllers
+    Figure.names
+    Figure.output
+    Figure.renderer
+    Figure.shape
+    Figure.toolbar
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: Figure_api
+
+    Figure.add_animations
+    Figure.clear
+    Figure.close
+    Figure.remove_animation
+    Figure.render
+    Figure.show
+    Figure.start_render
+