Visualisation¶

Underworld3 visualization utilities.

This module provides visualization tools for Underworld3 including: - PyVista-based 3D visualization (visualisation.py) - Parallel-safe matplotlib plotting (parallel.py)

Tools for visualising meshes, variables, and swarms using PyVista.

Mesh Conversion¶

Functions for converting Underworld3 objects to PyVista format.

mesh_to_pv_mesh¶

underworld3.visualisation.mesh_to_pv_mesh(mesh, jupyter_backend=None)[source]¶

Convert Underworld mesh to PyVista unstructured grid.

Parameters:

mesh (Mesh) – Underworld mesh to convert.
jupyter_backend (str, optional) – PyVista Jupyter backend to use.

Returns:

PyVista mesh with unit metadata attached.

Return type:

pyvista.UnstructuredGrid

meshVariable_to_pv_mesh_object¶

underworld3.visualisation.meshVariable_to_pv_mesh_object(meshVar, alpha=None)[source]¶

Convert mesh variable to Delaunay-triangulated PyVista mesh.

Creates a mesh by triangulating the mesh variable’s nodal points. Useful for higher-order elements where the base mesh doesn’t capture all data points.

Parameters:

meshVar (MeshVariable) – Underworld mesh variable.
alpha (float, optional) – Alpha parameter for Delaunay triangulation. If None, computed automatically from coordinate range.

Returns:

Triangulated mesh through the variable’s nodal points.

Return type:

pyvista.UnstructuredGrid

meshVariable_to_pv_cloud¶

underworld3.visualisation.meshVariable_to_pv_cloud(meshVar)[source]¶

Convert mesh variable node positions to PyVista point cloud.

Parameters:: meshVar (MeshVariable) – Underworld mesh variable.
Returns:: Point cloud at mesh variable nodal locations.
Return type:: pyvista.PolyData

swarm_to_pv_cloud¶

underworld3.visualisation.swarm_to_pv_cloud(swarm)[source]¶

Convert swarm particle positions to PyVista point cloud.

Parameters:: swarm (Swarm) – Underworld swarm object.
Returns:: Point cloud with particle positions.
Return type:: pyvista.PolyData

Function Sampling¶

Functions for sampling field values at points for visualisation.

scalar_fn_to_pv_points¶

underworld3.visualisation.scalar_fn_to_pv_points(pv_mesh, uw_fn, dim=None)[source]¶

Evaluate Underworld scalar function at PyVista mesh points.

Parameters:

pv_mesh (pyvista.DataSet) – PyVista mesh or point cloud to evaluate at.
uw_fn (sympy.Expr) – Underworld scalar function to evaluate.
dim (int, optional) – Dimensionality (2 or 3). Auto-detected if None.

Returns:

Scalar values at mesh points (units stripped for PyVista). The units string is stored as pv_mesh._last_scalar_units.

Return type:

numpy.ndarray

vector_fn_to_pv_points¶

underworld3.visualisation.vector_fn_to_pv_points(pv_mesh, uw_fn, dim=None)[source]¶

Evaluate Underworld vector function at PyVista mesh points.

Parameters:

pv_mesh (pyvista.DataSet) – PyVista mesh or point cloud to evaluate at.
uw_fn (sympy.Matrix) – Underworld vector function to evaluate.
dim (int, optional) – Dimensionality (not used, derived from function shape).

Returns:

Vector values at mesh points, shape (n_points, 3). Units string stored as pv_mesh._last_vector_units.

Return type:

numpy.ndarray

Plotting Utilities¶

Convenience functions for quick visualisation.

plot_mesh¶

underworld3.visualisation.plot_mesh(mesh, title='', clip_angle=0.0, cpos='xy', window_size=(750, 750), show_edges=True, save_png=False, dir_fname='')[source]¶

Plot a mesh with optional clipping, edge display, and saving functionality.

Parameters:¶

meshobject: The mesh object to be plotted. This should be in a format that can be converted into a PyVista mesh using vis.mesh_to_pv_mesh().
titlestr, optional: The title text to be displayed on the plot. Default is an empty string, meaning no title is shown.
clip_anglefloat, optional: The angle (in degrees) at which to clip the mesh. If set to 0.0, no clipping is applied. Clipping is performed using planes at the specified angle. Default is 0.0.
cposstr or list, optional: The camera position for viewing the mesh. It can be a string such as ‘xy’, ‘xz’, ‘yz’, or a list specifying the exact camera position. Default is ‘xy’.
window_sizetuple of int, optional: The size of the rendering window in pixels as (width, height). Default is (750, 750).
show_edgesbool, optional: Whether to display the edges of the mesh in the plot. If True, edges will be shown. Default is True.
save_pngbool, optional: Whether to save the plot as a PNG file. If True, the plot will be saved to the specified directory and filename. Default is False.
dir_fnamestr, optional: The directory and filename for saving the PNG image if save_png is True. If left empty, no file is saved. Default is an empty string.

Returns:¶

None: This function does not return any value. It displays the mesh plot in a PyVista window and optionally saves a screenshot.

plot_scalar¶

underworld3.visualisation.plot_scalar(mesh, scalar, scalar_name='', cmap='', clim='', window_size=(750, 750), title='', fmt='%10.7f', clip_angle=0.0, cpos='xy', show_edges=False, save_png=False, dir_fname='')[source]¶

Plot a scalar quantity from a mesh with options for clipping, colormap, and saving.

Parameters:¶

meshobject: The mesh object to be plotted. This should be in a format that can be converted into a PyVista mesh using vis.mesh_to_pv_mesh().
scalarmesh variable name or sympy expression: The scalar values associated with the mesh points. These values will be visualized on the mesh.
scalar_namestr, optional: The name of the scalar field to be used when adding it to the mesh. This name will also be used as the label for the scalar bar. Default is an empty string.
cmapstr, optional: The colormap to be used for visualizing the scalar values. This can be any colormap recognized by PyVista or Matplotlib. Default is an empty string, which uses the default colormap.
climtuple of float, optional: The scalar range to be used for coloring the mesh (e.g., (min_value, max_value)). If not provided, the range of the scalar values is used. Default is an empty string, which uses the full range of the scalar values.
window_sizetuple of int, optional: The size of the rendering window in pixels as (width, height). Default is (750, 750).
titlestr, optional: The title text to be displayed on the plot. Default is an empty string, meaning no title is shown.
fmtstr, optional: The format string for scalar values. This is typically used when displaying values on the scalar bar. Default is ‘%10.7f’.
clip_anglefloat, optional: The angle (in degrees) at which to clip the mesh. If set to 0.0, no clipping is applied. Clipping is performed using planes at the specified angle. Default is 0.0.
cposstr or list, optional: The camera position for viewing the mesh. It can be a string such as ‘xy’, ‘xz’, ‘yz’, or a list specifying the exact camera position. Default is ‘xy’.
show_edgesbool, optional: Whether to display the edges of the mesh in the plot. If True, edges will be shown. Default is False.
save_pngbool, optional: Whether to save the plot as a PNG file. If True, the plot will be saved to the specified directory and filename. Default is False.
dir_fnamestr, optional: The directory and filename for saving the PNG image if save_png is True. If left empty, no file is saved. Default is an empty string.

Returns:¶

None: This function does not return any value. It displays the scalar field on the mesh in a PyVista window and optionally saves a screenshot.

plot_vector¶

underworld3.visualisation.plot_vector(mesh, vector, vector_name='', cmap='', clim='', vmag='', vfreq='', save_png=False, dir_fname='', title='', fmt='%10.7f', clip_angle=0.0, show_arrows=False, cpos='xy', show_edges=False, window_size=(750, 750), scalar=None, scalar_name='')[source]¶

Plot a vector quantity from a mesh with options for clipping, colormap, vector magnitude, and saving.

Parameters:¶

meshobject: The mesh object to be plotted. This should be in a format that can be converted into a PyVista mesh using vis.mesh_to_pv_mesh().
vectormesh variable name or sympy expression: The symbolic representation of the vector field associated with the mesh points. This vector field will be visualized on the mesh.
vector_namestr, optional: The name of the vector field to be used when adding it to the mesh. This name will also be used as the label for the vector magnitude in the scalar bar. Default is an empty string.
cmapstr, optional: The colormap to be used for visualizing the vector magnitudes. This can be any colormap recognized by PyVista or Matplotlib. Default is an empty string, which uses the default colormap.
climtuple of float, optional: The scalar range to be used for coloring the mesh based on vector magnitudes (e.g., (min_value, max_value)). If not provided, the range of the vector magnitudes is used. Default is an empty string.
vmagfloat or str, optional: The scaling factor for the arrow magnitudes when plotting vectors as arrows. Default is an empty string, which uses the default scaling.
vfreqint, optional: The frequency of arrows to display when show_arrows is True. For example, if set to 10, every 10th vector will be plotted as an arrow. Default is an empty string, which uses the default frequency.
save_pngbool, optional: Whether to save the plot as a PNG file. If True, the plot will be saved to the specified directory and filename. Default is False.
dir_fnamestr, optional: The directory and filename for saving the PNG image if save_png is True. If left empty, no file is saved. Default is an empty string.
titlestr, optional: The title text to be displayed on the plot. Default is an empty string, meaning no title is shown.
fmtstr, optional: The format string for scalar values, typically used in the scalar bar. Default is ‘%10.7f’.
clip_anglefloat, optional: The angle (in degrees) at which to clip the mesh. If set to 0.0, no clipping is applied. Clipping is performed using planes at the specified angle. Default is 0.0.
show_arrowsbool, optional: Whether to display arrows representing the vector field on the mesh. If True, arrows will be shown. Default is False.
cposstr or list, optional: The camera position for viewing the mesh. It can be a string such as ‘xy’, ‘xz’, ‘yz’, or a list specifying the exact camera position. Default is ‘xy’.
show_edgesbool, optional: Whether to display the edges of the mesh in the plot. If True, edges will be shown. Default is False.
window_sizetuple of int, optional: The size of the rendering window in pixels as (width, height). Default is (750, 750).
scalarmesh variable name or sympy expression, optional: An optional scalar field associated with the mesh points. If provided, this scalar field will be used for coloring the mesh instead of the vector magnitude. Default is None.
scalar_namestr, optional: The name of the scalar field to be used when adding it to the mesh. This name will be used as the label for the scalar bar if scalar is provided. Default is an empty string.

Returns:¶

None: This function does not return any value. It displays the vector field on the mesh in a PyVista window and optionally saves a screenshot.

Notes

When the model uses physical units, arrows are drawn in the mesh coordinate space. A velocity of 1 cm/yr on a mesh in meters (extent ~1e6) produces arrows of length ~3e-10 in mesh units — effectively invisible. Adjust vmag to compensate:

# Scale arrows to ~5% of mesh extent
vmag = 0.05 * mesh_extent / max_velocity