differt.plotting module#
Plotting utilities for DiffeRT objects.
Tip
Unlike in other modules, plotting utilities also work
with NumPy arrays (np.ndarray)
Note
Backend names are case-sensitive.
Backend-specific notes#
Each backend comes with its own configuration options and outputs that the user should be aware of.
VisPy#
VisPy uses SceneCanvas objects
to display contents, on which a view is attached. The view
(ViewBox)
is what contains
the data to be plotted.
To reuse an existing canvas object, just pass it as a keyword
argument to any of the draw_* functions in this module, i.e.,
with draw_*(..., canvas=canvas).
In turn, each of those functions returns a figure on which you
can later add data.
It is also possible to pass an existing view
on which data will be plotted: draw_*(..., view=view).
If the jupyter_rfb module is installed, VisPy’s canvas integrate
nicely within Jupyter notebooks.
Matplotlib#
Matplotlib uses Figure objects
to display contents, on which multiple axes can be attached. In turn, each
axis can contain data to be plotted.
To reuse an existing figure object, just pass it as a keyword
argument to any of the draw_* functions in this module, i.e.,
with draw_*(..., figure=figure).
In turn, each of those functions returns a figure on which you
can later add data.
It is also possible to pass an existing axis
(Axes)
on which data will be plotted: draw_*(..., ax=ax).
Warning
By default, Matplotlib instantiates 2D axes, but this module extensively uses 3D plot methods. If an axis is provided, it is your responsibility to ensure that it can plot 3D data when needed.
By default, Matpotlib displays static images in Jupyter notebooks.
To make them interactive, install ipympl and load the corresponding
extension with %matplotlib widget.
Plotly#
Plotly is a dictionary-oriented library that produces HTML-based outputs. Hence, Plotly is a very good choice for publishing nice interactive plots on webpages.
Plots are fully contained inside
Figure objects, and can be nicely
displayed within Jupyter notebooks without further configuration.
To reuse an existing figure object, you can do the same as with
the Matplotlib backend.
Common utils
The following utilities allow you to modify the default behavior of plotting functions, either permanently or inside a given scope.
|
Create a context manager that will automatically reuse the current canvas / figure. |
|
Set default backend for future plotting utilities. |
|
Set default backend and keyword arguments for future plotting utilities. |
|
Update default backend and keyword arguments for future plotting utilities. |
|
Create a context manager that updates plotting defaults and returns the current default backend. |
Drawing functions
List of all drawing functions provided by this module.
Note
Some functions might not support all three backends. In such cases, it is indicated in their documentation.
|
Plot a 2D contour on a 3D canvas, at a fixed z-coordinate. |
|
Plot a 2D image on a 3D canvas, at a fixed z-coordinate. |
|
Plot markers and, optionally, their label. |
|
Plot a 3D mesh made of triangles. |
|
Plot a batch of paths of the same length. |
|
Plot a batch of rays. |
|
Plot a 3D surface. |
Extending this module
If you want to add new drawing functions, either locally or by contributing to this package, the following utilities might become handy.
|
Transform a function into a backend dispatcher for plot functions. |
|
Return the name of the backend to use. |
|
Process keyword arguments passed to some plotting utility. |
|
Process keyword arguments passed to some Matplotlib plotting utility. |
|
Process keyword arguments passed to some Plotly plotting utility. |
|
Process keyword arguments passed to some VisPy plotting utility. |
|
Return the view from the specified canvas. |
Note that all higher-level plotting functions, i.e., created outside of this module, should have the following return type.