compute_forward_vector#

movement.kinematics.compute_forward_vector(data, left_keypoint, right_keypoint, camera_view='top_down')[source]#

Compute a 2D forward vector given two left-right symmetric keypoints.

The forward vector is computed as a vector perpendicular to the line connecting two symmetrical keypoints on either side of the body (i.e., symmetrical relative to the mid-sagittal plane), and pointing forwards (in the rostral direction). A top-down or bottom-up view of the animal is assumed (see Notes).

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”

  • right_keypoint (str) – Name of the right keypoint, e.g., “right_ear”

  • 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".

Returns:

An xarray DataArray representing the forward vector, with dimensions matching the input data array, but without the keypoints dimension.

Return type:

xarray.DataArray

Notes

To determine the forward direction of the animal, we need to specify (1) the right-to-left direction of the animal and (2) its upward direction. We determine the right-to-left direction via the input left and right keypoints. The upwards direction, in turn, can be determined by passing the camera_view argument with either "top_down" or "bottom_up". If the camera view is specified as being "top_down", or if no additional information is provided, we assume that the upwards direction matches that of the vector [0, 0, -1]. If the camera view is "bottom_up", the upwards direction is assumed to be given by [0, 0, 1]. For both cases, we assume that position values are expressed in the image coordinate system (where the positive X-axis is oriented to the right, the positive Y-axis faces downwards, and positive Z-axis faces away from the person viewing the screen).

If one of the required pieces of information is missing for a frame (e.g., the left keypoint is not visible), then the computed head direction vector is set to NaN.