ValidBboxesDataset

class movement.validators.datasets.ValidBboxesDataset(*, position_array, shape_array, confidence_array=None, individual_names=None, frame_array=None, fps=None, source_software=None)

Bases: object

Class for validating bounding boxes’ data for a movement dataset.

The validator considers 2D bounding boxes only. It ensures that within the movement bboxes dataset:

• The required position_array and shape_array are numpy arrays, with the space dimension containing 2 spatial coordinates.

• The optional confidence_array, if provided, is a numpy array with its shape matching that of the position_array, excluding the space dimension; otherwise, it defaults to an array of NaNs.

• The optional individual_names, if provided, match the number of individuals in the dataset; otherwise, default names are assigned.

• The optional frame_array, if provided, is a column vector with the frame numbers; otherwise, it defaults to an array of 0-based integers.

• The optional fps is a positive float; otherwise, it defaults to None.

• The optional source_software is a string; otherwise, it defaults to None.

position_array

Array of shape (n_frames, n_space, n_individuals) containing the tracks of the bounding boxes’ centroids.

Type:

np.ndarray

shape_array

Array of shape (n_frames, n_space, n_individuals) containing the shape of the bounding boxes. The shape of a bounding box is its width (extent along the x-axis of the image) and height (extent along the y-axis of the image).

Type:

np.ndarray

confidence_array

Array of shape (n_frames, n_individuals) containing the confidence scores of the bounding boxes. If None (default), the confidence scores are set to an array of NaNs.

Type:

np.ndarray, optional

individual_names

List of individual names for the tracked bounding boxes in the video. If None (default), bounding boxes are assigned names based on the size of the position_array. The names will be in the format of id_<N>, where <N> is an integer from 0 to position_array.shape[1]-1.

Type:

list of str, optional

frame_array

Array of shape (n_frames, 1) containing the frame numbers for which bounding boxes are defined. If None (default), frame numbers will be assigned based on the first dimension of the position_array, starting from 0.

Type:

np.ndarray, optional

fps

Frames per second defining the sampling rate of the data. Defaults to None.

Type:

float, optional

source_software

Name of the software that generated the data. Defaults to None.

Type:

str, optional

Raises:

ValueError – If the dataset does not meet the movement bboxes dataset requirements.