Session#

Warning

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

class idtrackerai.Session[source]#

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 diagonals of individual blob’s bounding boxes

identities_groups: dict#: Named groups of identities stored in the validation GUI. If exclusive ROI, the identities of each region will be saved here

length_calibrations: list[LengthCalibration]#: List of length calibrations containing two points (in pixels units) and the real distance between these two defined by the user in the Validator.

episodes: list[Episode]#: Indicates the starting and ending frames of each video episode. Video episodes are used for parallelization of 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 obtained by OpenCV from the video file

version: str#: Version of idtracker.ai

number_of_error_frames: int = -1#: The number of frames with more blobs than animals. Set on 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. It is reused at tracking time

video_paths: list[Path] = []#: List of paths to the different files the video is composed of. If the video is a single file, the list will have 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 on RAM and until used, never write them on 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][source]#

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 parameters names.

Return type:

set[str]

prepare_tracking() → None[source]#: Initializes the session object, checking all parameters

save() → None[source]#: 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[source]#

Load a session object stored in a JSON file

Parameters:

path (Path | str) – Path to the session JSON file to load from or to the session folder containing the JSON file.
video_paths_dir (Path | None, optional) –
Folder containing the video paths. If None (the default), they are expected to be in:
- 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 True.
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[source]#: Generates, saves and returns a Timer

__str__() → str[source]#: Return str(self).

set_id_image_size(median_body_length: float) → None[source]#

Sets the median_body_length and computes the appropiate identification image size and resolution reduction when needed and taking into account the existing user defined values.

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 splitted for parallel processing

property blobs_path: Path#: get the path to save the blob collection after segmentation. It checks that the segmentation has been successfully performed

property global_fragments_path: Path#: get the path to save the list of global fragments after fragmentation

property fragments_path: Path#: get the path to save the list of global fragments after fragmentation

update_paths(new_session_path: Path, user_video_paths_dir: Path | str | None = None) → None[source]#: Update paths of objects (e.g. blobs_path, preprocessing_folder…) according to the location of the new Session object given by new_session_path.

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

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]][source]#

Process the episodes by getting the number of frames in each video path and the tracking interval.

Episodes are used to compute processes in parallel for different parts of the video. They are a tuple with

local start frame
local end frame
video path index
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 the tracking interval

property length_unit: float | None#: Length calibration factor for translating pixel units to user defined units. Property set in the Validator. Returns None if there are no calibrations.

delete_data() → None[source]#

Deletes some folders with data, to make the outcome lighter.

Which folders are deleted depends on the constant DATA_POLICY

compress_data() → None[source]#: Compress the identification images h5py files