compute_forward_vector_angle#

movement.kinematics.compute_forward_vector_angle(data, left_keypoint, right_keypoint, reference_vector=(1, 0), camera_view='top_down', in_radians=False, angle_rotates='ref to forward')[source]#

Compute the signed angle between a forward and reference vector.

Forward vector angle is the signed angle between the reference vector and the animal’s forward vector). The returned angles are in degrees, spanning the range \((-180, 180]\), unless in_radians is set to True.

Parameters:

  • data (xarray.DataArray) – The input data representing position. This must contain the two symmetrical keypoints located on the left and right sides of the body, respectively.

  • left_keypoint (str) – Name of the left keypoint, e.g., “left_ear”, used to compute the forward vector.

  • right_keypoint (str) – Name of the right keypoint, e.g., “right_ear”, used to compute the forward vector.

  • reference_vector (xr.DataArray | ArrayLike, optional) – The reference vector against which the forward_vector is compared to compute 2D heading. Must be a two-dimensional vector, in the form [x,y] - where reference_vector[0] corresponds to the x-coordinate and reference_vector[1] corresponds to the y-coordinate. If left unspecified, the vector [1, 0] is used by default.

  • camera_view (Literal["top_down", "bottom_up"], optional) – The camera viewing angle, used to determine the upwards direction of the animal. Can be either "top_down" (where the upwards direction is [0, 0, -1]), or "bottom_up" (where the upwards direction is [0, 0, 1]). If left unspecified, the camera view is assumed to be "top_down".

  • in_radians (bool, optional) – If true, the returned heading array is given in radians. If false, the array is given in degrees. False by default.

  • angle_rotates (Literal["ref to forward", "forward to ref"], optional) – Determines the sign convention for the returned signed angle. (See Notes).

Returns:

An xarray DataArray containing the computed forward vector angles, with dimensions matching the input data array, but without the keypoints and space dimensions.

Return type:

xarray.DataArray

Notes

There are different conventions for the sign of the forward vector angle. The angle_rotates argument can be used to select which behaviour the function should use.

By default, angle_rotates is set to "ref to forward", which results in the signed angle between the reference vector and the forward vector being returned. That is, the angle which the reference vector would need to be rotated by, to align with the forward vector. Setting angle_rotates to "forward to ref" reverses this convention, returning the signed angle between the forward vector and the reference vector; that is, the rotation that would need to be applied to the forward vector to return the reference vector.

See also

movement.utils.vector.compute_signed_angle_2d

The underlying function used to compute the signed angle between two 2D vectors.

movement.kinematics.compute_forward_vector

The function used to compute the forward vector.