Tree Visualization

Module for Optree and particle data visualization

Two different forms of visualization are supported: 3D plots from matplotlib, and interactive visualizations via pygfx. Plot functions that end in _poly create matplotlib figures, while functions that end in _mesh create pygfx canvases.

cubify_tree_Poly3D ¶

cubify_tree_Poly3D(tree, *, leaves_only=True, cmap=None)

Transform an octree into a dict of Poly3DCollections indexed by node depth

Each Poly3DCollection shares a single color, so we must return them separately.

Parameters:

tree (Octree | list[OctreeNode]) –

The octree (or list of OctreeNodes) to convert
leaves_only (bool, default: True ) –

Whether to only include leaves or the full tree. Default True
cmap (Colormap | None, default: None ) –

The colormap to use for the rendered octree. A string will be passed to the built-in colormaps (default is matplotlib.colormaps['plasma'])

Returns:

poly_dict ( dict[int, Poly3DCollection] ) –

Dictionary of Poly3DCollections

cubify_tree_geom ¶

cubify_tree_geom(tree, *, leaves_only=True, cmap=None)

Transform an octree into a dict of Meshes indexed by node depth

Each octree node is represented as a single Mesh geometry

Each Mesh shares a single material, so we must return them separately.

Parameters:

tree (Octree | list[OctreeNode]) –

The octree (or list of OctreeNodes) to convert
leaves_only (bool, default: True ) –

Whether to only include leaves or the full tree. Default True
cmap (Colormap | None, default: None ) –

The colormap to use for the rendered octree. A string will be passed to the built-in colormaps (default is matplotlib.colormaps['plasma'])

Returns:

mesh_dict ( dict[int, Mesh] ) –

Dictionary of Meshes

cubify_tree_mesh ¶

cubify_tree_mesh(tree, *, leaves_only=True, cmap=None)

Transform an octree into a dict of Meshes indexed by node depth

All octree nodes at the same depth are returned as a single Mesh.

Each Mesh shares a single material, so we must return them separately.

Parameters:

tree (Octree | list[OctreeNode]) –

The octree (or list of OctreeNodes) to convert
leaves_only (bool, default: True ) –

Whether to only include leaves or the full tree. Default True
cmap (str | Colormap | None, default: None ) –

The colormap to use for the rendered octree. A string will be passed to the built-in colormaps (default is matplotlib.colormaps['plasma'])

Returns:

mesh_dict ( dict[int, Mesh] ) –

Dictionary of Meshes

display_scene ¶

display_scene(canvas_scene)

Render scene

plot_box_mesh ¶

plot_box_mesh(box, *, canvas_scene=None, color=None, show_normals=True)

Plot a single BoundingBox

Creates a new canvas and scene if not provided

Parameters:

box (BoundingBox) –

The box to plot
canvas_scene (tuple[RenderCanvas, Scene] | None, default: None ) –

The Canvas and Scene to plot on. Default None
color (ColorType | None, default: None ) –

The color of the cube. Can be any valid matplotlib color (str, array, etc.) Default "green".
show_normals (bool | ColorType, default: True ) –

Whether to show cube normals. If True (default), normals are shown in red. Can instead specify a color to display normals in that color.

Returns:

canvas_scene ( tuple[Canvas, Scene] ) –

The canvas-scene tuple

plot_box_poly ¶

plot_box_poly(box, *, ax=None, color=None)

Plot a single BoundingBox

Creates a new figure if ax is not provided

Parameters:

box (BoundingBox) –

The box to plot
ax (Axes3D | None, default: None ) –

The 3D axes to plot on. Default None
color (ColorType | None, default: None ) –

The color of the cube. Can be any valid matplotlib color (str, array, etc.) Default "green".

Returns:

ax ( Axes3D ) –

plot_octree_mesh ¶

plot_octree_mesh(tree, *, canvas_scene=None, cmap=None, leaves_only=True)

Plot an Octree or other list of OctreeNodes

Creates a new canvas if canvas_scene is not provided.

Nodes are colored according to their depth, so all nodes at the same depth will have the same color.

Parameters:

tree (Octree | list[OctreeNode]) –

The tree or list of OctreeNodes to plot
canvas_scene (tuple[RenderCanvas, Scene] | None, default: None ) –

The 3D canvas to plot on. Default None
cmap (str | Colormap | None, default: None ) –

The colormap to use for plotting. Can be any valid matplotlib colormap (str, array, etc.) Default "plasma".
leaves_only (bool, default: True ) –

For Octrees, whether to plot only the leaves (Default) or the entire tree

Returns:

canvas_scene ( tuple[Canvas, Scene] ) –

The canvas-scene tuple

plot_octree_poly ¶

plot_octree_poly(tree, *, ax=None, cmap=None, leaves_only=True)

Plot an Octree or other list of OctreeNodes

Creates a new figure if ax is not provided.

Nodes are colored according to their depth, so all nodes at the same depth will have the same color.

Parameters:

tree (Octree | list[OctreeNode]) –

The tree or list of OctreeNodes to plot
ax (Axes3D | None, default: None ) –

The 3D axes to plot on. Default None
cmap (Colormap | None, default: None ) –

The colormap to use for plotting. Can be any valid matplotlib colormap (str, array, etc.) Default "plasma".
leaves_only (bool, default: True ) –

For Octrees, whether to plot only the leaves (Default) or the entire tree

Returns:

ax ( Axes3D ) –

plot_octreenode_mesh ¶

plot_octreenode_mesh(node, *, canvas_scene=None, color=None)

Plot a single OctreeNode

Effectively just plot_box_mesh(node.box, ...)

Parameters:

node (OctreeNode) –

The node to plot
canvas_scene (tuple[RenderCanvas, Scene] | None, default: None ) –

The Canvas and Scene to plot on. Default None
color (ColorType | None, default: None ) –

The color of the cube. Can be any valid matplotlib color (str, array, etc.) Default "green".

Returns:

canvas_scene ( tuple[Canvas, Scene] ) –

The canvas-scene tuple

plot_octreenode_poly ¶

plot_octreenode_poly(node, *, ax=None, color=None)

Plot a single OctreeNode

Effectively just plot_box_poly(node.box, ...) Creates a new figure if ax is not provided

Parameters:

node (OctreeNode) –

The node to plot
ax (Axes3D | None, default: None ) –

The 3D axes to plot on. Default None
color (ColorType | None, default: None ) –

The color of the cube. Can be any valid matplotlib color (str, array, etc.) Default "green".

Returns:

ax ( Axes3D ) –

plot_positions_mesh ¶

plot_positions_mesh(*, positions=None, ds=None, canvas_scene=None, sizes=None, colors=None)

Plot an 3D scatter plot of the positions in a dataset

Parameters:

positions (NDArray | None, default: None ) –

Array of 3D points to plot. If not provided will use ds.positions. Default None
ds (Dataset | None, default: None ) –

Dataset from which to pull positions from. Must be provided if positions is None. Default None
canvas_scene (tuple[RenderCanvas, Scene] | None, default: None ) –

The 3D canvas to plot on. Default None
sizes (NDArray | int | None, default: None ) –

Size of particles to plot. Can specify an array to have individual sizes. Default 3
colors (NDArray | None, default: None ) –

Array of per-particle colors. Defaults to xkcd:skyblue

Returns:

canvas_scene ( tuple[Canvas, Scene] ) –

The canvas-scene tuple

plot_positions_poly ¶

plot_positions_poly(*, positions=None, ds=None, ax=None)

Plot an 3D scatter plot of the positions in a dataset

Creates a new figure if ax is not provided.

Parameters:

positions (NDArray | None, default: None ) –

Array of 3D points to plot. If not provided will use ds.positions. Default None
ds (Dataset | None, default: None ) –

Dataset from which to pull positions from. Must be provided if positions is None. Default None
ax (Axes3D | None, default: None ) –

The 3D axes to plot on. Default None

Returns:

ax ( Axes3D ) –

setup_scene ¶

setup_scene()

Create a pygfx default scene