features

keypoint_distances(trajectory, *, trajectory_other=None, keypoints_1, keypoints_2, element_wise=False, flat=False)

Calculate euclidean distances between keypoints.

Parameters:

• trajectory (Trajectory) – The trajectory to calculate the distances for.

• trajectory_other (Trajectory | None, default: None) – The other trajectory to calculate the distances with, if None, falls back to trajectory.

• keypoints_1 (Iterable[int]) – The keypoint indices to use (of the first trajectory).

• keypoints_2 (Iterable[int]) – The keypoint indices to use as target (of the second trajectory).

• element_wise (bool, default: False) – Whether to calculate the distances element-wise.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

Returns:

The euclidean distances between the keypoints.

keypoints(collection, *, keypoints, flat=False, suffixes=('x', 'y'))

2D coordinates of trajectory keypoints.

Parameters:

• collection (InstanceCollection) – The instance collection (e.g., a trajectory) to retrieve the keypoints from.

• keypoints (Iterable[int]) – The indices of keypoints to retrieve.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

• suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The 2D coordinates of the keypoints.

Note

This is currently only extracting the x and y coordinates of the keypoints.

position(collection, *, suffixes=('x', 'y'))

Calculates the position of each instance in the collection as the mean of all keypoints.

Parameters:

• collection (InstanceCollection) – The instance collection (e.g., a trajectory).

• suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The 2D position of each instance in the collection.

posture_alignment(trajectory, *, trajectory_other=None, keypoint_pairs_1, keypoint_pairs_2, element_wise=False, flat=False)

Calculate alignment of posture vectors, ranging between 0 (anti-parallel), 0.5 (orthogonal) and 1 (parallel).

Parameters:

• trajectory (Trajectory) – The trajectory to calculate the alignment for.

• trajectory_other (Trajectory | None, default: None) – The other trajectory to calculate the alignment with, if None, falls back to trajectory.

• keypoint_pairs_1 (Iterable[tuple[int, int]]) – The keypoint pairs to use for the first angle ray (of the first trajectory).

• keypoint_pairs_2 (Iterable[tuple[int, int]]) – The keypoint pairs to use for the second angle ray (of the second trajectory).

• element_wise (bool, default: False) – Whether to calculate the alignment element-wise.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

Returns:

The alignment of the posture vectors.

posture_angles(trajectory, *, trajectory_other=None, keypoint_pairs_1, keypoint_pairs_2, element_wise=False, flat=False)

Calculate signed angles in radians between posture vectors.

Parameters:

• trajectory (Trajectory) – The trajectory to calculate the angles for.

• trajectory_other (Trajectory | None, default: None) – The other trajectory to calculate the angles with, if None, falls back to trajectory.

• keypoint_pairs_1 (Iterable[tuple[int, int]]) – The keypoint pairs to use for the first angle ray (of the first trajectory).

• keypoint_pairs_2 (Iterable[tuple[int, int]]) – The keypoint pairs to use for the second angle ray (of the second trajectory).

• element_wise (bool, default: False) – Whether to calculate the angles element-wise.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

Returns:

The signed angles in radians between the posture vectors.

posture_segments(trajectory, *, keypoint_pairs, flat=False, suffixes=('x1', 'y1', 'x2', 'y2'))

Retrieves 2D line segments between trajectory keypoints.

Parameters:

• trajectory (InstanceCollection) – The trajectory or instance collection.

• keypoint_pairs (Iterable[tuple[int, int]]) – The pairs of keypoint indices to use for the segments.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

• suffixes (tuple[str, ...], default: ('x1', 'y1', 'x2', 'y2')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The 2D line segments between trajectory keypoints.

posture_vectors(trajectory, *, keypoint_pairs, as_unit_vectors=False, flat=False, suffixes=('x', 'y'))

2D vectors between trajectory keypoints.

Alternatively, return vectors as unit vectors with as_unit_vectors=True.

Parameters:

• trajectory (InstanceCollection) – The trajectory or instance collection.

• keypoint_pairs (Iterable[tuple[int, int]]) – The pairs of keypoint indices to use for the segments.

• as_unit_vectors (bool, default: False) – Whether to return unit vectors instead of regular vectors.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

• suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The 2D vectors between the keypoints.

target_angles(trajectory, *, trajectory_other=None, keypoint_pairs_1, keypoints_2, element_wise=False, flat=False)

Calculate signed angles in radians between posture vectors and target vectors.

The two legs of the angles are - the orientation vectors of the posture segments - the vectors pointing from posture segment (keypoint_pairs_1) end keypoints to the target keypoints (keypoints_2)

Parameters:

• trajectory (Trajectory) – The trajectory to compute target vectors for.

• trajectory_other (Trajectory | None, default: None) – The other trajectory for the target keypoints, if None, falls back to trajectory.

• keypoint_pairs_1 (Iterable[tuple[int, int]]) – The keypoint segment indices to use (of the first trajectory).

• keypoints_2 (Iterable[int]) – The keypoint indices to use as target (of the second trajectory).

• element_wise (bool, default: False) – Whether to calculate the distances element-wise.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

Return type:

ndarray

target_vectors(trajectory, *, trajectory_other=None, keypoints_1, keypoints_2, element_wise=False, flat=False, suffixes=('x', 'y'))

Retrieve vectors pointing from one set of keypoints to another.

Parameters:

• trajectory (Trajectory) – The trajectory to get target vectors from.

• trajectory_other (Trajectory | None, default: None) – The other trajectory for the target vectors, if None, falls back to trajectory.

• keypoints_1 (Iterable[int]) – The keypoint indices to use (of the first trajectory).

• keypoints_2 (Iterable[int]) – The keypoint indices to use as target (of the second trajectory).

• element_wise (bool, default: False) – Whether to calculate the distances element-wise.

• flat (bool, default: False) – Whether to flatten the output along all but the first dimension.

• suffixes (tuple[str, ...], default: ('x', 'y')) – The suffixes to use for the output when decorated with as_dataframe().

Return type:

ndarray

Returns:

The target vectors.