from_numpy#

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

Create a movement poses dataset from NumPy arrays.

Parameters:

  • position_array (ndarray) – Array of shape (n_frames, n_space, n_keypoints, n_individuals) containing the poses. It will be converted to a xarray.DataArray object named “position”.

  • confidence_array (ndarray | None) – Array of shape (n_frames, n_keypoints, n_individuals) containing the point-wise confidence scores. It will be converted to a xarray.DataArray object named “confidence”. If None (default), the scores will be set to an array of NaNs.

  • individual_names (list[str] | None) – List of unique names for the individuals in the video. If None (default), the individuals will be named “id_0”, “id_1”, etc.

  • keypoint_names (list[str] | None) – List of unique names for the keypoints in the skeleton. If None (default), the keypoints will be named “keypoint_0”, “keypoint_1”, etc.

  • frame_array (ndarray | None) – Array containing the frame numbers corresponding to the data. It must be a column vector of shape (n_frames, 1) and values must be monotonically increasing. If None (default), frame numbers are assigned as consecutive 0-based integers.

  • fps (float | None) – Frames per second of the video. Defaults to None, in which case the time coordinates will be in frame numbers.

  • source_software (str | None) – Name of the pose estimation software from which the data originate. Defaults to None.

Returns:

movement dataset containing the pose tracks, confidence scores, and associated metadata.

Return type:

Dataset

Examples

Create random position data for two individuals with three keypoints each, tracked in 2D space for 100 frames. As confidence scores are omitted, they default to NaN, and individuals/keypoints are auto-named (“id_0”, “id_1”, … and “keypoint_0”, “keypoint_1”, …). Time coordinates default to consecutive 0-based frame numbers.

>>> import numpy as np
>>> from movement.io import load_poses
>>> rng = np.random.default_rng(seed=42)
>>> ds = load_poses.from_numpy(
...     position_array=rng.random((100, 2, 3, 2)),
... )

Create a dataset with the same data as above, but name the individuals Alice and Bob, the keypoints snout, centre, and tail_base, and set all confidence scores to 1.

>>> ds = load_poses.from_numpy(
...     position_array=rng.random((100, 2, 3, 2)),
...     confidence_array=np.ones((100, 3, 2)),
...     individual_names=["Alice", "Bob"],
...     keypoint_names=["snout", "centre", "tail_base"],
... )

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_poses.from_numpy(
...     position_array=rng.random((100, 2, 3, 2)),
...     confidence_array=np.ones((100, 3, 2)),
...     individual_names=["Alice", "Bob"],
...     keypoint_names=["snout", "centre", "tail_base"],
...     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 30 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, 1202, … 1299 the corresponding time coordinates in seconds will be 40.0, 40.033…, 40.067…, … 43.3 s.

>>> ds = load_poses.from_numpy(
...     position_array=rng.random((100, 2, 3, 2)),
...     confidence_array=np.ones((100, 3, 2)),
...     individual_names=["Alice", "Bob"],
...     keypoint_names=["snout", "centre", "tail_base"],
...     frame_array=np.arange(1200, 1300).reshape(-1, 1),
...     fps=30,
... )

Examples using from_numpy#

Load and visualise FreeMoCap 3D data

Load and visualise FreeMoCap 3D data