pynaviz.audiovideo.video_plot.PlotVideo#

class pynaviz.audiovideo.video_plot.PlotVideo(video, t=None, buffer_size_sec=1.0, stream_index=0, index=None, start_worker=True, parent=None)[source]#

Bases: PlotBaseVideoTensor

Visualization 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.

Parameters:

video (str | Path | VideoHandler)
t (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
buffer_size_sec (float)
stream_index (int)
start_worker (bool)

__init__(video, t=None, buffer_size_sec=1.0, stream_index=0, index=None, start_worker=True, parent=None)[source]#

Initialize the PlotVideo instance with a given video source.

Parameters:

video (str or pathlib.Path or VideoHandler) – Path to the video file to be visualized or a VideoHandler object.
t (numpy.typing.NDArray, optional) – Time vector to use for syncing frames.
buffer_size_sec (float) – Duration of the recently-decoded frame cache in seconds (default 1 s). Frames within this window are returned instantly on re-access without any seek or decode. Larger values improve responsiveness during scrubbing at the cost of additional memory.
stream_index (int, default 0) – Index of the stream to read in the video file.
index (int, optional) – Controller ID index.
start_worker (bool, optional) – Start the worker thread. This should be set to true when used in GUI but for speeding up tests, should be set to False.
parent (object, optional) – Parent GUI container or widget.

Methods

`__init__`(video[, t, buffer_size_sec, ...])	Initialize the PlotVideo instance with a given video source.
`add_interval_sets`(epochs[, colors, alpha, ...])
`animate`()	Main render loop callback for pygfx.
`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.
`from_state`(state, available_vars)	Restore the full plot state from a previously saved dict.
`get_plot_state`()	Return plot-type-specific display state for serialization.
`get_state`()	Return the full serializable state of this plot.
`group_by`(metadata_name[, spacing])	Placeholder for future metadata grouping method.
`jump_to_next_epoch`()	Jump to the start of the next superposed epoch (across all added interval sets).
`jump_to_previous_epoch`()	Jump to the start of the previous superposed epoch (across all added interval sets).
`remove_interval_set`(label)	Remove an interval set from the plot.
`set_frame`(target_time)	Set the video display to the frame closest to the target time.
`set_plot_state`(state, available_vars)	Restore plot-type-specific display state produced by `get_plot_state()`.
`show`()	To show the canvas in case of GLFW context used
`sort_by`(metadata_name[, mode])	Placeholder for future metadata sorting method.
`superpose_points`(tsdframe[, color, ...])	Superpose a set of points on top of the video plot.
`update_interval_set`(name, colors, alpha)	Update the color and transparency of an existing interval set.

Attributes

`cmap`
`data`	Read-only access to the video data handler.

add_interval_sets(epochs, colors=None, alpha=None, labels=None)#

Parameters:

epochs (Iterable[IntervalSet] | IntervalSet)
colors (Iterable | str | Color | None)
alpha (Iterable[float] | float | None)
labels (Iterable[str] | str | None)

animate()[source]#

Main render loop callback for pygfx.

Handles texture and text update, syncing, and redraw triggering.

close()[source]#: Cleanly close shared memory, worker, and background thread.

property cmap#

color_by(metadata_name, cmap_name='viridis', vmin=0.0, vmax=100.0)#

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.

Return type:

None

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.

from_state(state, available_vars)#

Restore the full plot state from a previously saved dict.

Guards against missing keys so that layouts saved by older versions of pynaviz can still be loaded without error.

Parameters:

state (dict) – Dictionary produced by get_state().
available_vars (dict) – Mapping of variable name → nap variable used to look up overlays by name.

get_plot_state()#

Return plot-type-specific display state for serialization.

Subclasses override this to capture whatever is needed to restore the current visual appearance — e.g. display mode and scale for PlotTsdFrame, or marker sizes for PlotTsGroup. The base implementation returns None (no plot-specific state).

Return type:: dict or None

get_state()#

Return the full serializable state of this plot.

Aggregates three layers:

"manager": sort_by / group_by / color_by actions.
"interval_sets": overlay color and alpha keyed by label.
"plot": plot-type-specific state (mode, scale, clim, …).

Return type:: dict

group_by(metadata_name, spacing=None)#

Placeholder for future metadata grouping method.

Parameters:

metadata_name (str)
spacing (Optional)

jump_to_next_epoch()#

Jump to the start of the next superposed epoch (across all added interval sets).

Return type:: None

jump_to_previous_epoch()#

Jump to the start of the previous superposed epoch (across all added interval sets).

Return type:: None

remove_interval_set(label)#

Remove an interval set from the plot.

Parameters:: label (str) – The label of the interval set to be removed.
Return type:: None

set_frame(target_time)#

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

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

set_plot_state(state, available_vars)#

Restore plot-type-specific display state produced by get_plot_state().

Parameters:

state (dict or None) – Value previously returned by get_plot_state().
available_vars (dict) – The available nap variables.

show()#: To show the canvas in case of GLFW context used

sort_by(metadata_name, mode='ascending')#

Placeholder for future metadata sorting method.

Parameters:

metadata_name (str)
mode (str | None)

superpose_points(tsdframe, color=None, markersize=10, thickness=2, label=None)#

Superpose a set of points on top of the video plot. Argument tsdframe should be a nap.Tsdframe with multiple of 2 columns (x1, y1, x2, y2, …). The label of the columns doesn’t matter.

Parameters:

tsdframe (nap.TsdFrame) – Time series data to overlay.
color (str or rgba tuple, optional) – Color of the set of points.
markersize (float, default 10) – Size of the set of points.
thickness (float, default 2) – Thickness of the lines connecting the points.
label (str, optional) – Label for the set of points. If None, a default label is assigned.

update_interval_set(name, colors, alpha)#

Update the color and transparency of an existing interval set.

Parameters:

name (str) – The label of the interval set to be updated.
colors (str | Color) – The new color of the interval set.
alpha (float) – The new transparency level, between 0 and 1.

Return type:

None