idtrackerai.extra_tools.video_generator#

Warning

The code reference is a work in progress and may contain inconsistencies.

The video generator tool is used to generate videos from the tracking data generated by the idtracker.ai software, see Video Generator.

idtrackerai.extra_tools.video_generator.generate_general_video(session: Session, trajectories_path: Path | str | None = None, draw_in_gray: bool = False, centroid_trace_length: int = 20, starting_frame: int = 0, ending_frame: int | None = None, labels: list[str] | None = None, resize_factor: float | None = None, callback: Callable | None = None, output_path: Path | str | None = None, colors: list[tuple[int, ...]] | None = None) → None[source]#

Generates a video with animal trajectories overlaid on the original video frames.

This function creates a new video file with the tracked trajectories of each animal drawn on top of the video frames. Optionally, the video can be rendered in grayscale, resized, and include labels for each animal. The output video is saved in the session folder with the suffix ‘_tracked.avi’.

See also

Video Generator in the documentation for more details.

Parameters:

  • session (Session) – The idtrackerai Session object containing video and experiment information.

  • trajectories_path (Path | str | None, optional) – Path to the trajectories file. If None, trajectories are loaded from the session folder.

  • draw_in_gray (bool, optional) – If True, the output video will be in grayscale. Default is False (color).

  • centroid_trace_length (int, optional) – Number of previous frames to show as a trace for each animal’s trajectory. Default is 20.

  • starting_frame (int, optional) – Index of the first frame to include in the output video. Default is 0.

  • ending_frame (int | None, optional) – Index of the last frame to include in the output video. If None, uses the last frame available.

  • labels (list[str] | None, optional) – List of labels to display for each animal. If None, no labels are shown.

  • resize_factor (float | None, optional) – Factor by which to resize the video frames. If None, automatically scales to fit within 1920x1080.

  • callback (Callable | None, optional) – Optional callback function for progress tracking (e.g., for GUI updates).

  • output_path (Path | str | None, optional) – Path where the output video will be saved. If None, saves in the session folder with the name ‘<original_video_name>_tracked.avi’.

Notes

The output video is saved in the session folder with the name ‘<original_video_name>_tracked.avi’.

idtrackerai.extra_tools.video_generator.generate_individual_video(session: Session, trajectories_path: Path | str | None = None, draw_in_gray: bool = False, starting_frame: int = 0, ending_frame: int | None = None, miniframe_size: float | None = None, labels: list[str] | None = None, callback: Callable | None = None, output_dir: Path | str | None = None) → None[source]#

Generates a set of videos showing the tracked individuals in a session.

This function creates:

  • A “general” video displaying all individuals in a grid layout, with each animal shown in a square “miniframe”.

  • Individual videos for each animal, showing only their own miniframe over time.

See also

Documentation for Video Generator

Parameters:

  • session (Session) – The Session instance containing video and tracking data.

  • trajectories_path (Path | str | None, optional) – Path to the trajectories file (NumPy .npy or .npz). If None, uses the session’s default trajectories folder.

  • draw_in_gray (bool, optional) – If True, output videos will be in grayscale. If False, videos will be in color. Default is False.

  • starting_frame (int, optional) – Index of the first frame to include in the output videos. Default is 0.

  • ending_frame (int | None, optional) – Index of the last frame to include (inclusive). If None, processes until the last frame in the trajectories. Default is None.

  • miniframe_size (float | None, optional) – Size (in pixels) of the square miniframe for each individual. If None, uses the session’s median body length. Default is None.

  • labels (list[str] | None, optional) – Optional list of labels (e.g., animal IDs or names) to display above each miniframe in the general video. Default is None.

  • callback (Callable | None, optional) – Optional callback function for progress tracking (e.g., for GUI updates). Default is None.

  • output_dir (Path | str | None, optional) – Directory where output videos will be saved. If None, saves to the session folder under “individual_videos”. Default is None.

  • Output

  • ------

  • directory (Saves AVI videos to the output) –

    • “general.avi”: grid video of all individuals.

    • ”individual_{id}.avi”: one video per animal, showing only their own miniframe.

Notes

  • The function handles missing or invalid frames by filling with black images.

  • The grid layout and miniframe size are automatically determined based on the number of animals and provided parameters.

  • Uses OpenCV for video writing and image processing.