cedalion.vis.blocks

Blocks of plotting functionality to build visualizations.

Functions

camera_at_cog(plt, surface, rpos[, ...])

Point the camera at the center of gravity of the surface vertices.

plot_labeled_points(plotter, points[, ...])

Plots LabeledPoints with optional interaction for picking points.

plot_segments(ax, segments[, fmt, y, label])

Highlight time segments in line plots.

plot_stim_markers(ax, stim[, fmt, y])

Add stimulus indicators to an Axes.

plot_surface(plotter, surface[, color, ...])

Plots a surface mesh with optional landmark picking in a PyVista plotter.

plot_vector_field(plotter, points, vectors)

Plots a vector field on a PyVista plotter.
cedalion.vis.blocks.plot_stim_markers(
ax,
stim: DataFrame,
fmt: dict[str, dict] | None = None,
y: float = 0.03,
)[source]

Add stimulus indicators to an Axes.

For each trial a Rectangle is plotted in x from onset to onset+duration. The height of the rectangle is specified in axes coordinates. In the default setting a small bar at bottom of the axes is drawn. By setting y to 1. the stimulus marker covers the full height of the axes.

Parameters:

  • ax – the matplotlib axes to operate on

  • stim – a stimulas data frame

  • fmt – for each trial_type a dictioniary of keyword arguments can be provided. These kwargs are passed to matplotlib.patches.Rectangle to format the stimulus indicator.

  • y – the height of the Rectangle in axes coordinates.

Initial Contributors:
cedalion.vis.blocks.plot_segments(
ax,
segments: list[tuple[float, float]],
fmt: dict | None = None,
y: float = 1.0,
label: str | None = None,
)[source]

Highlight time segments in line plots.

cedalion.vis.blocks.plot_surface(
plotter: pv.Plotter,
surface: cdc.Surface,
color: pv.ColorLike | ArrayLike | None = None,
opacity: float = 1.0,
pick_landmarks: bool = False,
**kwargs,
)[source]

Plots a surface mesh with optional landmark picking in a PyVista plotter.

Parameters:

  • plotter – A PyVista plotter instance used for rendering the surface.

  • surface – The surface object to be plotted.

  • color – Color of the mesh.

  • opacity – Opacity of the mesh, ranging from 0 (transparent) to 1 (opaque). Default is 1.0.

  • pick_landmarks – If True, enables interactive picking of landmarks on the surface. Default is False.

  • **kwargs – Additional keyword arguments are passed to pv.add_mesh.

Returns:

If pick_landmarks is True, returns a function that when called, provides the current picked points and their labels. This function prints warnings if some labels are missing or are repeated.

Return type:

function

Initial Contributors:
cedalion.vis.blocks.plot_labeled_points(
plotter: pv.Plotter,
points: cdt.LabeledPoints,
color: pv.ColorLike | None = None,
show_labels: bool = False,
ppoints: bool = None,
labels: list[str] | None = None,
)[source]

Plots LabeledPoints with optional interaction for picking points.

This function visualizes a point cloud where each point can have a label. Points can be interactively picked if enabled. Picked point is indicated by increased radius.

Parameters:

  • plotter – A PyVista plotter instance used for rendering the points.

  • points – A labeled point cloud data structure containing points and optional labels.

  • color – Override color for all points. If None, colors are assigned based on point types.

  • show_labels – If True, labels are displayed next to the points.

  • ppoints – A list to store indices of picked points, enables picking if not None.

  • labels – List of labels to show if show_labels is True. If None and show_labels is True, the labels from points are used.

Initial Contributors:
cedalion.vis.blocks.plot_vector_field(
plotter: Plotter,
points: cdt.LabeledPoints,
vectors: DataArray,
ppoints=None,
)[source]

Plots a vector field on a PyVista plotter.

Parameters:

  • plotter (pv.Plotter) – A PyVista plotter instance used for rendering the vector field.

  • points (cdt.LabeledPoints) – A labeled point cloud data structure containing point coordinates.

  • vectors (xr.DataArray) – A data array containing the vector field.

  • ppoints (list, optional) – A list to store indices of picked points, enables picking if not None. Default is None.

cedalion.vis.blocks.camera_at_cog(
plt: Plotter,
surface: Surface,
rpos: tuple[float, float, float],
fp_offset: tuple[float, float, float] = (0, 0, 0),
up: tuple[float, float, float] = (0, 0, 1),
fit_scene: bool = False,
)[source]

Point the camera at the center of gravity of the surface vertices.

Parameters:

  • plt – the pyvista plotter

  • surface – the surface from which the COG should be calculated

  • rpos – positin of the camera relative to the COG

  • fp_offset – offset from the COG to calculate the focal point

  • up – direction of upwards.

  • fit_scene – if True the camera is moved along the position-to-focal-point line to fit all objects in the scene into the view.