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 (ndarray) – Array of shape (n_frames, n_space, n_individuals) containing the tracks of the bounding box centroids. It will be converted to a xarray.DataArray object named “position”.

  • shape_array (ndarray) – 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). It will be converted to a xarray.DataArray object named “shape”.

  • confidence_array (ndarray | None) – 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[str] | None) – 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 (ndarray | None) – 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 integers sorted in increasing order.

  • fps (float | None) – 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 | None) – 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:

Dataset

Examples

Create random position and shape data for two bounding boxes, tracked in 2D space for 100 frames. Confidence scores are omitted, so they default to NaN, and individuals are auto-named (“id_0”, “id_1”). Time coordinates default to consecutive 0-based frame numbers.

>>> import numpy as np
>>> from movement.io import load_bboxes
>>> rng = np.random.default_rng(seed=42)
>>> ds = load_bboxes.from_numpy(
...     position_array=rng.random((100, 2, 2)),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
... )

Create a dataset with the same data as above, but name the individuals Alice and Bob, and set all confidence scores to 0.5.

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

Create a dataset with the same data as above, but specify that the 100 frames are numbered from the start frame 1200 to the end frame 1299, instead of defaulting to 0-based frame numbers.

>>> ds = load_bboxes.from_numpy(
...     position_array=rng.random((100, 2, 2)),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["Alice", "Bob"],
...     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=rng.random((100, 2, 2)),
...     shape_array=np.ones((100, 2, 2)) * [40, 30],
...     confidence_array=np.ones((100, 2)) * 0.5,
...     individual_names=["Alice", "Bob"],
...     frame_array=np.arange(1200, 1300).reshape(-1, 1),
...     fps=60,
... )