compute_forward_vector_angle#

movement.kinematics.compute_forward_vector_angle(data, left_keypoint, right_keypoint, reference_vector=(1, 0), camera_view='top_down', in_degrees=False)[source]#

Compute the signed angle between a reference and a forward vector.

Forward vector angle is the signed angle between the reference vector and the animal’s forward vector. The returned angles are in radians, spanning the range \((-\pi, \pi]\), unless in_degrees 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 (Hashable) – Name of the left keypoint, e.g., “left_ear”, used to compute the forward vector.

  • right_keypoint (Hashable) – 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_degrees (bool) – If True, the returned heading array is given in degrees. Otherwise, the array is given in radians. Default False.

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

See also

movement.utils.vector.compute_signed_angle_2d

The underlying function used to compute the signed angle between two 2D vectors. See this function for a definition of the signed angle between two vectors.

movement.kinematics.compute_forward_vector

The function used to compute the forward vector.