pynaviz.video.video_plot.PlotVideo#

class pynaviz.video.video_plot.PlotVideo(video_path: str | Path, t: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, stream_index: int = 0, index=None, parent=None)[source]#

Bases: PlotBaseVideoTensor

Video visualization class for rendering video files synchronized with a time series.

This class uses shared memory and multiprocessing to efficiently stream frames from disk to GPU via pygfx. It also supports real-time interaction and frame-based control.

__init__(video_path: str | Path, t: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, stream_index: int = 0, index=None, parent=None)[source]#

Initialize the PlotVideo instance with a given video source.

Parameters:

  • video_path (str or pathlib.Path) – Path to the video file to be visualized.

  • t (NDArray, optional) – Optional time vector to use for syncing frames.

  • stream_index (int, default=0) – Index of the stream to read in the video file.

  • index (int, optional) – Controller ID index.

  • parent (object, optional) – Parent GUI container or widget.

Methods

__init__(video_path[, t, stream_index, ...])

Initialize the PlotVideo instance with a given video source.

add_interval_sets(epochs[, colors, alpha, ...])

animate()

Updates the positions of rulers and reference lines based on the current world coordinate bounds and triggers a re-render of the scene.

close()

Cleanly close shared memory, worker, and background thread.

color_by(metadata_name[, cmap_name, vmin, vmax])

Applies color mapping to plot elements based on a metadata field.

group_by(metadata_name[, spacing])

Placeholder for future metadata grouping method.

set_frame(target_time)

Set the video display to the frame closest to the target time.

show()

To show the canvas in case of GLFW context used

sort_by(metadata_name[, mode])

Placeholder for future metadata sorting method.

Attributes

cmap

data

Read-only access to the video data handler.
add_interval_sets(epochs: Iterable[IntervalSet] | IntervalSet, colors: Iterable | str | Color | None = None, alpha: Iterable[float] | float | None = None, labels: Iterable[str] | str | None = None)#
animate()#

Updates the positions of rulers and reference lines based on the current world coordinate bounds and triggers a re-render of the scene.

This method performs the following: - Computes the visible world coordinate bounds. - Updates the horizontal (x) and vertical (y) rulers accordingly. - Repositions the center time reference line in the scene. - Re-renders the scene using the current camera and canvas settings.

Notes

This method should be called whenever the visible region of the plot changes (e.g., after zooming, panning, or resizing the canvas).

close()[source]#

Cleanly close shared memory, worker, and background thread.

property cmap#
color_by(metadata_name: str, cmap_name: str = 'viridis', vmin: float = 0.0, vmax: float = 100.0) → None#

Applies color mapping to plot elements based on a metadata field.

This method retrieves values from the given metadata field and maps them to colors using the specified colormap and value range. The mapped colors are applied to each plot element’s material. If color mappings are still being computed in a background thread, the function retries after a short delay.

Parameters:

  • metadata_name (str) – Name of the metadata field used for color mapping.

  • cmap_name (str, default="viridis") – Name of the colormap to apply (e.g., “jet”, “plasma”, “viridis”).

  • vmin (float, default=0.0) – Minimum value for the colormap normalization.

  • vmax (float, default=100.0) – Maximum value for the colormap normalization.

Notes

  • If the color_mapping_thread is still running, the method defers execution by 25 milliseconds and retries automatically.

  • If no appropriate color map is found for the metadata, a warning is issued.

  • Requires self.data to support get_info() for metadata retrieval.

  • Triggers a canvas redraw by calling self.animate() after updating colors.

Warning

UserWarning

Raised when the specified metadata field has no associated color mapping.

property data#

Read-only access to the video data handler.

group_by(metadata_name: str, spacing: Optional = None)#

Placeholder for future metadata grouping method.

set_frame(target_time: float)#

Set the video display to the frame closest to the target time.

Parameters:

target_time (float) – Time in seconds to seek to.

show()#

To show the canvas in case of GLFW context used

sort_by(metadata_name: str, mode: str | None = 'ascending')#

Placeholder for future metadata sorting method.