pynaviz.video.video_handling#

Functions

ts_to_index(ts, time)

Return the index of the frame whose experimental time is just before (or equal to) ts.

Classes

VideoHandler(video_path[, stream_index, ...])

Class for getting video frames.
class pynaviz.video.video_handling.VideoHandler(video_path: str | Path, stream_index: int = 0, time: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, return_frame_array: bool = True)[source]#

Bases: object

Class for getting video frames.

close()[source]#

Close the video stream.

extract_keyframe_times_and_points(video_path: str | Path, stream_index: int = 0, first_only=False) → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None[source]#

Extract the indices and timestamps of keyframes from a video file.

This function decodes the video while skipping non-keyframes, and records: - The index of each keyframe in the full video frame sequence - The “Presentation Time Stamp” to each keyframe.

It is typically intended to run in a background thread during initialization of a VideoHandler, and supports optimized seeking:

  • When the requested frame (based on experimental time) is before the current playback position, seeking backward is necessary.

  • When the requested frame is beyond the next known keyframe, seeking forward to the closest keyframe is more efficient than decoding all intermediate frames.

Parameters:

  • video_path (str or pathlib.Path) – The path to the video file.

  • stream_index – The index of the video stream.

  • first_only – If true, return the first keypoint only. Used at initialization.

Returns:

  • keyframe_points (NDArray[float]) – The point number of the frame.

  • keyframe_timestamps (NDArray[float]) – The timestamp of the frame.

get(ts: float) → VideoFrame | ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]#
get_key_frame(backward) → VideoFrame | ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]#
get_slice(start: float, end: float = None)[source]#
property index#
property shape#
property t#
pynaviz.video.video_handling.ts_to_index(ts: float, time: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → int[source]#

Return the index of the frame whose experimental time is just before (or equal to) ts.

Parameters:

  • ts (float) – Experimental timestamp to match.

  • time (NDArray) – Array of experimental timestamps, assumed sorted in ascending order, with one entry per frame.

Returns:

idx – Index of the frame with time <= ts. Clipped to [0, len(time) - 1].

Return type:

int

Notes

  • If ts is smaller than all values in time, returns 0.

  • If ts is greater than all values in time, returns len(time) - 1.