from_numpy#

movement.io.load_bboxes.from_numpy(position_array, shape_array, confidence_array=None, individual_names=None, frame_array=None, fps=None, source_software=None)[source]#

Create a movement bounding boxes dataset from NumPy arrays.

Parameters:

position_array (np.ndarray) – Array of shape (n_frames, n_individuals, n_space) containing the tracks of the bounding boxes’ centroids. It will be converted to a xarray.DataArray object named “position”.
shape_array (np.ndarray) – Array of shape (n_frames, n_individuals, n_space) 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). It will be converted to a xarray.DataArray object named “shape”.
confidence_array (np.ndarray, optional) – 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. It will be converted to a xarray.DataArray object named “confidence”.
individual_names (list of str, optional) – 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 (i.e., “id_0”, “id_1”…).
frame_array (np.ndarray, optional) – 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. If a specific array of frame numbers is provided, these need to be consecutive integers.
fps (float, optional) – The video sampling rate. If None (default), the time coordinates of the resulting movement dataset will be in frame numbers. If fps is provided, the time coordinates will be in seconds. If the time coordinates are in seconds, they will indicate the elapsed time from the capture of the first frame (assumed to be frame 0).
source_software (str, optional) – Name of the software that generated the data. Defaults to None.

Returns:

movement dataset containing the position, shape, and confidence scores of the tracked bounding boxes, and any associated metadata.

Return type:

xarray.Dataset

Examples

Create random position data for two bounding boxes, id_0 and id_1, with the same width (40 pixels) and height (30 pixels). These are tracked in 2D space for 100 frames, which are numbered from the start frame 1200 to the end frame 1299. The confidence score for all bounding boxes is set to 0.5.

>>> import numpy as np
>>> from movement.io import load_bboxes
>>> ds = load_bboxes.from_numpy(
...     position_array=np.random.rand(100, 2, 2),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["id_0", "id_1"],
...     frame_array=np.arange(1200, 1300).reshape(-1, 1),
... )

Create a dataset with the same data as above, but with the time coordinates in seconds. We use a video sampling rate of 60 fps. The time coordinates in the resulting dataset will indicate the elapsed time from the capture of the 0th frame. So for the frames 1200, 1201, 1203,… 1299 the corresponding time coordinates in seconds will be 20, 20.0167, 20.033,… 21.65 s.

>>> ds = load_bboxes.from_numpy(
...     position_array=np.random.rand(100, 2, 2),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["id_0", "id_1"],
...     frame_array=np.arange(1200, 1300).reshape(-1, 1),
...     fps=60,
... )

Create a dataset with the same data as above, but express the time coordinate in frames, and assume the first tracked frame is frame 0. To do this, we simply omit the frame_array input argument.

>>> ds = load_bboxes.from_numpy(
...     position_array=np.random.rand(100, 2, 2),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["id_0", "id_1"],
... )

Create a dataset with the same data as above, but express the time coordinate in seconds, and assume the first tracked frame is captured at time = 0 seconds. To do this, we omit the frame_array input argument and pass an fps value.

>>> ds = load_bboxes.from_numpy(
...     position_array=np.random.rand(100, 2, 2),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["id_0", "id_1"],
...     fps=60,
... )