Skip to content

Visualization

See visualization and video for rendering requirements, field selection, camera settings, fixed color limits, and output naming.

Mesh rendering

Visualization with pyvista.

Figure out how to add multiple layers to the visualization. E.g. streamlines in addition to other data.

DataRangeType

Bases: str, Enum

Enum for handling the data range.

Local: use the data range of every individual variable GLOBAL: use the global range over multiple variables

DataLayer dataclass 

DataLayer(sid, title, colormap='magma', viz_type=AttributeType.SCALAR, color_limits=None, scalar_bar=True, conversion_factor=None)

Data layer for plot.

Currently only a single data layer is supported but this will be extended to map multiple layers in a single visualiztion

Attributes:

Name Type Description
sid str

Name of the mesh data array to render.
title str

Scalar bar title.
colormap ColormapOptions

PyVista colormap name or definition.
viz_type AttributeType

Type of mesh attribute to activate.
color_limits tuple[float, float] | None

Fixed minimum and maximum scalar values.
scalar_bar bool

Whether to show a scalar bar.
conversion_factor float | None

Factor for converting data before plotting.

update_color_limits 

update_color_limits(data_limits, only_empty=True)

Update color limits.

Parameters:

Name Type Description Default
data_limits DataLimits

Available limits indexed by the data layer identifier.

 required
only_empty bool

Update only layers without existing limits when true.

 True

VisualizationSettings dataclass 

VisualizationSettings(window_size=(lambda: [1000, 1000])(), off_screen=True, camera_position=(0, 0.0003, 0.001), zoom=1.1)

General visualization settings for panel.

These should be determined once for a given geometry and then be used consistently.

visualize_data_layers 

visualize_data_layers(mesh, data_layers, output_dir, image_name, visualization_settings=None)

Visualize geometry with pyvista.

Parameters:

Name Type Description Default
mesh Mesh

Geometry and data for one time point.

 required
data_layers Iterable[DataLayer]

Layers to render as separate panels.

 required
output_dir Path

Directory for per-layer output folders.

 required
image_name str

Output image name without its extension.

 required
visualization_settings VisualizationSettings | None

Camera and rendering settings, or defaults.

 None

visualize_datalayers_timecourse 

visualize_datalayers_timecourse(xdmf_path, output_dir, data_layers, window_size=(600, 600))

Create visualizations for individual panels.

Parameters:

Name Type Description Default
xdmf_path Path

Input XDMF time course.

 required
output_dir Path

Directory for rendered panels.

 required
data_layers Iterable[DataLayer]

Layers to render separately for each time point.

 required
window_size tuple[int, int]

Width and height of each panel in pixels.

 (600, 600)

visualize_interactive 

visualize_interactive(mesh, data_layer, visualization_settings)

Visualize geometry with pyvista.

xdmf_to_mesh 

xdmf_to_mesh(xdmf_path, k=0)

XDMF to mesh.

create_combined_images 

create_combined_images(num_steps, output_dir, selection, direction, ncols=None, nrows=None)

Create combined images for all timepoints.

VTU conversion

Read VTU files for visualization.

vtu_to_xdmf 

vtu_to_xdmf(vtu_path, xdmf_path, *, overwrite=False)

Convert a static VTU mesh to XDMF/HDF and return the mesh.

Parameters:

Name Type Description Default
vtu_path Path

Input VTU mesh path.

 required
xdmf_path Path

Destination XDMF path. Its HDF sidecar stays beside it.

 required
overwrite bool

Explicitly allow replacement of existing regular output files.

 False

Returns:

Type Description
Mesh

The mesh read from the VTU file.

Matplotlib styling

Opt-in Matplotlib styling that restores the application's configuration.

plot_style 

plot_style()

Apply plot sizes within an explicit context and restore them afterward.

Image processing

Image manipulation.

Combine and annotate images using PIL.

merge_images 

merge_images(paths, output_path, direction='vertical', ncols=None, nrows=None)

Combine images into a vertical strip, horizontal strip, or grid.

Parameters:

Name Type Description Default
paths Iterable[Path]

Input images in panel order.

 required
output_path Path

Destination image path.

 required
direction str

Layout: "vertical", "horizontal", "square", or "custom".

 'vertical'
ncols int | None

Positive column count required for a custom grid.

 None
nrows int | None

Positive row count required for a custom grid.

 None

Raises:

Type Description
ValueError

If no images are supplied or the layout is invalid.

Annotate images with text.

annotate_image_text 

annotate_image_text(image_in_path, image_out_path, text, xy=(10, 10), *, font_path=None, font_size=40)

Annotate an image with a portable default font or an explicit TrueType font.

Video

These helpers require FFmpeg on PATH.

Tools related to videos.

Requires ffmpeg for video generation.

create_video 

create_video(image_pattern, video_path, frame_rate=30, codec='mpeg4', overwrite=True)

Create a video from image frames using ffmpeg.

Parameters:

Name Type Description Default
image_pattern str

ffmpeg input pattern for the image sequence.

 required
video_path Path

Destination video path.

 required
frame_rate int

Frames per second.

 30
codec str

ffmpeg video codec name.

 'mpeg4'
overwrite bool

Whether ffmpeg may overwrite an existing video.

 True

Raises:

Type Description
FileExistsError

If the destination exists and overwrite is false.
CalledProcessError

If ffmpeg fails.

create_gif_from_video 

create_gif_from_video(video_path, gif_path, overwrite=True)

Convert a video to a GIF using ffmpeg.

Parameters:

Name Type Description Default
video_path Path

Existing source video path.

 required
gif_path Path

Destination GIF path.

 required
overwrite bool

Whether ffmpeg may overwrite an existing GIF.

 True

Raises:

Type Description
OSError

If the source video does not exist.
FileExistsError

If the destination exists and overwrite is false.
CalledProcessError

If ffmpeg fails.