Scene video class#

class pyneon.SceneVideo(video_file: Path, timestamps_file: Path, info_file: Path)#

Bases: VideoCapture

Loaded video file with timestamps.

Parameters:

  • video_file (pathlib.Path) – Path to the video file.

  • timestamps_file (pathlib.Path) – Path to the timestamps file.

  • info_file (pathlib.Path) – Path to the scene camera info file.

timestamps#

Timestamps of the video frames in nanoseconds.

Type:

numpy.ndarray

ts#

Alias for timestamps.

Type:

numpy.ndarray

n_frames#

Number of frames in the video.

Type:

int

fps#

Frames per second of the video.

Type:

float

width#

Width of the video frames in pixels.

Type:

int

height#

Height of the video frames in pixels.

Type:

int

get_frame(timestamp: int | int64) → int#

Get the frame index corresponding to a given timestamp.

Parameters:

timestamp (int) – Timestamp in nanoseconds.

Returns:

Frame index corresponding to the timestamp.

Return type:

int

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:

  • index (int) – Index of the frame to plot.

  • ax (matplotlib.axes.Axes or None) – Axis to plot the frame on. If None, a new figure is created. Defaults to None.

  • auto_title (bool) – 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:

  • fig (matplotlib.figure.Figure) – Figure object containing the plot.

  • ax (matplotlib.axes.Axes) – Axis object containing the plot.

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

Detect AprilTags in the video frames.

Parameters:

tag_family (str, optional) – The AprilTag family to detect (default is ‘tag36h11’).

Returns:

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.

Return type:

pd.DataFrame

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:

  • scanpath (pandas.DataFrame) – DataFrame containing the fixations and gaze data.

  • circle_radius (int) – Radius of the fixation circles in pixels. Defaults to 10.

  • line_thickness (int or None) – Thickness of the lines connecting fixations. If None, no lines are drawn. Defaults to 2.

  • max_fixations (int) – Maximum number of fixations to plot per frame. Defaults to 10.

  • show_video (bool) – Whether to display the video with fixations overlaid. Defaults to False.

  • video_output_path (pathlib.Path or str or None) – Path to save the video with fixations overlaid. If None, the video is not saved. Defaults to ‘scanpath.mp4’.

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_path (str) – Path to save the undistorted output video.