Session

Warning

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

class idtrackerai.Session

A class containing the main features of the session.

This class includes properties of the video by itself, user defined parameters for the tracking, and other properties that are generated throughout the tracking process.

We use this class as a storage of data coming from different processes. However, this is bad practice and it will change in the future.

median_body_length: float

Median of the bounding box diagonals of the individual blobs

identities_groups: dict

Named groups of identities stored in the validation GUI. With exclusive_rois, the identities of each region are saved here

length_calibrations: list[LengthCalibration]

List of length calibrations defined by the user in the Validator, each one containing two points (in pixel units) and the real distance between them.

episodes: list[Episode]

Starting and ending frames of each video episode. Video episodes are used to parallelize some processes

width: int

Video width in pixels

height: int

Video height in pixels

frames_per_second: float

Video frame rate in frames per second, read by OpenCV from the video file

version: str

Version of idtracker.ai

number_of_error_frames: int = -1

Number of frames with more blobs than animals. Set during animals detection.

identities_labels: list[str] | None = None

A list with a name for every identity. Defined and used in validator

identities_colors: list[str] | None = None

A list with a color for every identity. Defined and used in validator

background_from_segmentation_gui: Path | None = None

Path to the background computed by the segmentation app, reused at tracking time

video_paths: list[Path] = []

List of paths to the files the video is composed of. If the video is a single file, the list has length 1

id_image_size: list[int] = []

Shape of the Blob’s identification images (width, height, n_channels)

trajectories_formats: Sequence[Literal['h5', 'npy', 'csv', 'csv_tidy', 'pickle', 'parquet']] = ['h5', 'npy', 'csv']

A sequence of strings defining in which formats the trajectories should be saved

exclusive_rois: bool = False

Treat each separate ROI as closed identities groups

identity_transfer_succeeded: bool = False

True if the identity transfer has been done successfully

bounding_box_images_in_ram: bool = False

Keep bounding box images in RAM until used instead of writing them to disk

last_validated: datetime | None = None

Last time this session was validated using the Validator

silhouette_score: float | None = None

Silhouette score reached at the end of the contrastive step

fragment_connectivity: float | None = None

Connectivity of the fragments used in the contrastive step

set_parameters(reset: bool = False, **parameters) → set[str]

Sets parameters to self only if they are present in the class annotations.

Parameters:

• reset (bool, optional) – If True, resets the session parameters before setting new ones, by default False.

• **parameters (dict) – Arbitrary keyword arguments representing the parameters to set.

Returns:

The set of non-recognized parameter names.

Return type:

set[str]

prepare_tracking() → None

Initializes the session object, checking all parameters

save() → None

Saves the instantiated Session object

classmethod load(path: Path | str, video_paths_dir: Path | str | None = None, allow_not_found_video_files: bool = True) → Session

Loads a session object stored in a JSON file

Parameters:

• path (Path | str) – Path to the session JSON file or to the session folder containing it.

• video_paths_dir (Path | str | None, optional) –

  Extra folder where to look for the video files. Apart from this one, the video files are always searched:

  • In the same location where they were during the tracking

  • In the parent folder of the JSON file being loaded

  • In the double-parent folder of the JSON file being loaded

  • In the parent folder of the original path of the JSON file

  • In the double-parent folder of the original path of the JSON file

  • In the current working directory

• allow_not_found_video_files (bool, optional) – If False, an IdtrackeraiError exception is raised if the video files couldn’t be found, by default True.

Returns:

Instance of Session from the loaded JSON file.

Return type:

Session

Raises:

• FileNotFoundError – If the JSON couldn’t be found.

• IdtrackeraiError – If the video files couldn’t be found and allow_not_found_video_files is False.

• ValueError – If the input file is not JSON readable. If the session being loaded is from version 4 or lower of idtracker.ai.

new_timer(name: str) → Timer

Generates, saves and returns a Timer

__str__() → str

Return str(self).

set_id_image_size(median_body_length: float) → None

Sets median_body_length and computes the appropriate identification image size and resolution reduction, respecting the values already defined by the user.

Parameters:

median_body_length (float) – Median body length of all individual blobs in the video

property number_of_episodes: int

Number of episodes in which the video is split for parallel processing

property blobs_path: Path

Path to the ListOfBlobs saved after segmentation

property global_fragments_path: Path

Path to the list of global fragments saved after fragmentation

property fragments_path: Path

Path to the list of fragments saved after fragmentation

classmethod defaults() → dict[str, Any]

Class-level default values of the Session attributes

update_paths(new_session_path: Path, user_video_paths_dir: Path | str | None = None) → None

Sets the session folder to new_session_path and looks for the video files in a set of candidate folders (see load()). The session is saved if any path has changed.

static get_info_from_video_paths(video_paths: Iterable[Path | str]) → tuple[int, int, float]

Gets some information about the video from the video file itself.

Returns:

int, height: int, fps: float

Return type:

width

static get_processing_episodes(video_paths: Sequence[Path | str], frames_per_episode: float, tracking_intervals=None) → tuple[int, list[int], list[list[int]], list[Episode]]

Splits the video into episodes using the number of frames of each video path and the tracking intervals.

Episodes are used to compute processes in parallel for different parts of the video. Each Episode contains

• index

• local start frame

• local end frame

• video path

• global start frame

• global end frame

where “local” means in the specific video path and “global” means in the whole (multi path) video.

Episodes are guaranteed to belong to a single video path and to have all of their frames (end not included) inside a tracking interval.

Returns:

The total number of frames, the number of frames of each video path, the tracking intervals and the list of episodes.

property length_unit: float | None

Length calibration factor for translating pixel units to user defined units, averaged over all length_calibrations defined in the Validator. None if there are no calibrations.

delete_data() → None

Deletes some data folders to make the session lighter.

Which folders are deleted depends on data_policy

compress_data() → None

Compresses the identification images HDF5 files with gzip