Layouts#
PlotArea#
This is the main base class within layouts. A Figure
and Dock
are areas within a Subplot
that
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:
scene - instance of
pygfx.Scene
canvas - instance of
WgpuCanvas
renderer - instance of
pygfx.WgpuRenderer
viewport - instance of
pygfx.Viewport
camera - instance of
pygfx.PerspectiveCamera
, we always just usePerspectiveCamera
and just setcamera.fov = 0
for orthographic projectionscontroller - instance of
pygfx.Controller
If these concepts are unfamiliar to you we recommend learning about how rendering engines work, the pygfx guide is a great place to start! https://docs.pygfx.org/stable/guide.html
Here is also a short video that goes through the basic concepts: https://www.youtube.com/watch?v=cvcAjgMUPUA
Abstract method that must be implemented in subclasses:
get_rect - must return [x, y, width, height] that defines the viewport rect for this
PlotArea
Properties specifically used by subplots in a Figure:
parent - A parent if relevant, used by individual
Subplots
inFigure
, and byDock
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 theFigure
Other important properties:
graphics - a tuple of weakref proxies to all
Graphics
within thisPlotArea
, users are only given weakref proxies toGraphic
objects, allGraphic
objects are stored in a private global dict.selectors - a tuple of weakref proxies to all selectors within this
PlotArea
legend - a tuple of weakref proxies to all legend graphics within this
PlotArea
name - plot areas are allowed to have names that the user can use for their convenience
Important methods:
add_graphic - add a
Graphic
to thePlotArea
, append to the end of thePlotArea._graphics
listinsert_graphic - insert a
Graphic
to thePlotArea
, insert to a specific position of thePlotArea._graphics
listremove_graphic - remove a graphic from the
Scene
, does not delete itdelete_graphic - delete a graphic from the
PlotArea
, performs garbage collectionclear - deletes all graphics from the
PlotArea
center_graphic - center camera w.r.t. a
Graphic
center_scene - center camera w.r.t. entire
Scene
auto_scale - Auto-scale the camera w.r.t to the
Scene
In addition, PlotArea
supports __getitem__
, so you can do: plot_area["graphic_name"]
to retrieve a Graphic
by
name.
You can also check if a PlotArea
has certain graphics, ex: "some_image_name" in plot_area
, or graphic_instance in plot_area
Subplot#
This class inherits from PlotArea
and GraphicMethodsMixin
.
GraphicMethodsMixin
is a simple class that just has all the add_<graphic>
methods. It is autogenerated by a utility script like this:
python scripts/generate_add_methods.py
Each add_<graphic>
method basically creates an instance of Graphic
, adds it to the Subplot
, and returns the Graphic
.
Subplot
has one property that is not in PlotArea
:
docks: a
dict
ofPlotAreas
which are located at the “top”, “right”, “left”, and “bottom” edges of aSubplot
.
By default their size is 0
. They are useful for putting things like histogram LUT tools.
The key method in Subplot
is an implementation of get_rect
that returns the viewport rect for this subplot.
Figure#
Now that we have understood PlotArea
and Subplot
we need a way for the user to create them!
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.