Scene video class

class pyneon.Video(video_file: Path, timestamps: ndarray, info: dict)

Bases: VideoCapture

Loaded video file with timestamps.

Parameters:

video_filepathlib.Path

Path to the video file.

timestampsnumpy.ndarray

Timestamps of the video frames in nanoseconds. Must have the same length as the number of frames in the video.

infodict

Dictionary containing video info, including camera matrix and distortion coefficients.

Attributes:

timestampsnumpy.ndarray

Timestamps of the video frames in nanoseconds.

tsnumpy.ndarray

Alias for timestamps.

Methods

detect_apriltags([tag_family])	Detect AprilTags in the video frames.
get(propId)	. @brief Returns the specified VideoCapture property
getBackendName()	. @brief Returns used backend API name
getExceptionMode()
get_frame(timestamp)	Get the frame index corresponding to a given timestamp.
grab()	. @brief Grabs the next frame from video file or capturing device.
isOpened()	. @brief Returns true if video capturing has been initialized already.
open(filename[, apiPreference])	. @brief Opens a video file or a capturing device or an IP video stream for video capturing.
overlay_scanpath(scanpath[, circle_radius, ...])	Plot scanpath on top of the video frames.
plot_frame([index, ax, auto_title, show])	Plot a frame from the video on a matplotlib axis.
read([, image])	. @brief Grabs, decodes and returns the next video frame.
release()	. @brief Closes video file or capturing device.
retrieve([, image[, flag]])	. @brief Decodes and returns the grabbed video frame.
set(propId, value)	. @brief Sets a property in the VideoCapture.
setExceptionMode(enable)
undistort([output_video_path])	Undistort a video using the known camera matrix and distortion coefficients.
waitAny(streams[, timeoutNs])	. @brief Wait for ready frames from VideoCapture.

reset

property camera_matrix: ndarray

Camera matrix of the video camera.

detect_apriltags(tag_family: str = 'tag36h11') → DataFrame

Detect AprilTags in the video frames.

Parameters:

tag_familystr, optional

The AprilTag family to detect (default is ‘tag36h11’).

Returns:

pd.DataFrame

A DataFrame containing AprilTag detections, with columns: - ‘timestamp [ns]’: The timestamp of the frame in nanoseconds, as an index - ‘frame_idx’: The frame number - ‘tag_id’: The ID of the detected AprilTag - ‘corners’: A 4x2 array of the tag corner coordinates, in the order TL, TR, BR, BL. (x, y) from top-left corner of the video - ‘center’: A 1x2 array with the tag center coordinates. (x, y) from top-left corner of the video.

property distortion_coefficients: ndarray

Distortion coefficients of the video camera.

property fps: float

Frames per second of the video.

get_frame(timestamp: int | int64) → int

Get the frame index corresponding to a given timestamp.

Parameters:

timestampint

Timestamp in nanoseconds.

Returns:

int

Frame index corresponding to the timestamp.

property height: int

Height of the video frames in pixels.

overlay_scanpath(scanpath: DataFrame, circle_radius: int = 10, line_thickness: int = 2, max_fixations: int = 10, show_video: bool = False, video_output_path: Path | str = 'derivatives/scanpath.mp4') → None

Plot scanpath on top of the video frames. The resulting video can be displayed and/or saved.

Parameters:

scanpathpandas.DataFrame

DataFrame containing the fixations and gaze data.

circle_radiusint

Radius of the fixation circles in pixels. Defaults to 10.

line_thicknessint or None

Thickness of the lines connecting fixations. If None, no lines are drawn. Defaults to 2.

max_fixationsint

Maximum number of fixations to plot per frame. Defaults to 10.

show_videobool

Whether to display the video with fixations overlaid. Defaults to False.

video_output_pathpathlib.Path or str or None

Path to save the video with fixations overlaid. If None, the video is not saved. Defaults to ‘scanpath.mp4’.

plot_frame(index: int = 0, ax: Axes | None = None, auto_title: bool = True, show: bool = True)

Plot a frame from the video on a matplotlib axis.

Parameters:

indexint

Index of the frame to plot.

axmatplotlib.axes.Axes or None

Axis to plot the frame on. If None, a new figure is created. Defaults to None.

auto_titlebool

Whether to automatically set the title of the axis. The automatic title includes the video file name and the frame index. Defaults to True.

Returns:

figmatplotlib.figure.Figure

Figure object containing the plot.

axmatplotlib.axes.Axes

Axis object containing the plot.

undistort(output_video_path: Path | str | None = 'undistorted_video.mp4') → None

Undistort a video using the known camera matrix and distortion coefficients.

Parameters:

output_video_pathstr

Path to save the undistorted output video.

property width: int

Width of the video frames in pixels.