Visualization#

PhysicsNeMo-Mesh supports two visualization backends:

Matplotlib

2D and 3D static plots. The default backend when PyVista is not available or when rendering in non-interactive environments (for example, Jupyter notebooks without a GPU display).

PyVista

Interactive 3D rendering with hardware acceleration. Preferred for exploratory visualization of large meshes.

The primary entry point is draw_mesh(), which is also accessible as the mesh.draw() method. The backend is selected automatically based on availability, or can be specified explicitly.

Scalar data can be visualized as colormapped overlays on points or cells. For vector fields, the L2 norm is computed automatically for colormapping.

from physicsnemo.mesh.primitives.surfaces import sphere_icosahedral

mesh = sphere_icosahedral.load(subdivisions=2)
mesh.point_data["height"] = mesh.points[:, 2]

# Quick visualization via Mesh method
mesh.draw(point_scalars="height", show_edges=True)

# Standalone function
from physicsnemo.mesh.visualization.draw_mesh import draw_mesh
draw_mesh(mesh, point_scalars="height")

API Reference#

Main entry point for mesh visualization with backend selection.

physicsnemo.mesh.visualization.draw_mesh.draw_mesh(
mesh: Mesh,
backend: Literal['matplotlib', 'pyvista', 'auto'] = 'auto',
show: bool = True,
point_scalars: None | Tensor | str | tuple[str, ...] = None,
cell_scalars: None | Tensor | str | tuple[str, ...] = None,
cmap: str = 'viridis',
vmin: float | None = None,
vmax: float | None = None,
alpha_points: float = 1.0,
alpha_cells: float = 1.0,
alpha_edges: float = 1.0,
show_edges: bool = True,
ax=None,
backend_options: dict[str, Any] | None = None,
)[source]#

Draw a mesh using matplotlib or PyVista backend.

This is the main visualization function for Mesh objects. It automatically selects the appropriate backend based on spatial dimensions, or allows explicit backend specification.

Parameters:

  • mesh (Mesh) – Mesh object to visualize.

  • backend ({"auto", "matplotlib", "pyvista"}) –

    Visualization backend to use: - “auto”: Automatically select based on n_spatial_dims

    (matplotlib for 0D/1D/2D, PyVista for 3D)

    • ”matplotlib”: Force matplotlib backend (supports 3D via mplot3d)

    • ”pyvista”: Force PyVista backend (requires n_spatial_dims <= 3)

  • show (bool) – Whether to display the plot immediately (calls plt.show() or plotter.show()). If False, returns the plotter/axes for further customization before display.

  • point_scalars (torch.Tensor or str or tuple[str, ...] or None, optional) –

    Scalar data to color points. Mutually exclusive with cell_scalars. Can be: - None: Points use neutral color (black) - torch.Tensor: Direct scalar values, shape (n_points,) or

    (n_points, …) where trailing dimensions are L2-normed

    • str or tuple[str, …]: Key to lookup in mesh.point_data

  • cell_scalars (torch.Tensor or str or tuple[str, ...] or None, optional) –

    Scalar data to color cells. Mutually exclusive with point_scalars. Can be: - None: Cells use neutral color (lightblue if no scalars,

    lightgray if point_scalars active)

    • torch.Tensor: Direct scalar values, shape (n_cells,) or (n_cells, …) where trailing dimensions are L2-normed

    • str or tuple[str, …]: Key to lookup in mesh.cell_data

  • cmap (str) – Colormap name for scalar visualization.

  • vmin (float or None, optional) – Minimum value for colormap normalization. If None, uses data min.

  • vmax (float or None, optional) – Maximum value for colormap normalization. If None, uses data max.

  • alpha_points (float) – Opacity for points, range [0, 1].

  • alpha_cells (float) – Opacity for cells/faces, range [0, 1].

  • alpha_edges (float) – Opacity for cell edges, range [0, 1].

  • show_edges (bool) – Whether to draw cell edges.

  • ax (matplotlib.axes.Axes, optional) – (matplotlib only) Existing matplotlib axes to plot on. If None, creates new figure and axes.

  • backend_options (dict[str, Any], optional) – Additional keyword arguments forwarded to the underlying visualization backend (e.g. PyVista’s plotter.add_mesh()).

Returns:

  • matplotlib backend: matplotlib.axes.Axes object

  • PyVista backend: pyvista.Plotter object

Return type:

matplotlib.axes.Axes or pyvista.Plotter

Raises:

  • ValueError – If both point_scalars and cell_scalars are specified, or if n_spatial_dims is not supported by the chosen backend, or if backend selection fails. or if ax is provided for PyVista backend.

  • ImportError – If the requested backend is not installed.

Examples

>>> # Draw mesh with automatic backend selection
>>> mesh.draw()
>>>
>>> # Color cells by pressure data
>>> mesh.draw(cell_scalars="pressure", cmap="coolwarm")
>>>
>>> # Color points by velocity magnitude (computing norm of vector field)
>>> mesh.draw(point_scalars="velocity")  # velocity is (n_points, 3)
>>>
>>> # Use nested TensorDict key
>>> mesh.draw(cell_scalars=("flow", "temperature"))
>>>
>>> # Customize and display later
>>> ax = mesh.draw(show=False, backend="matplotlib")
>>> ax.set_title("My Mesh")
>>> plt.show()
On this page