gravitydir

Gravity direction vector for given orientation

Since R2023b

Syntax

D = gravitydir(orientations)

D = gravitydir(orientations,RF)

Description

D = gravitydir(orientations) returns the normalized gravity direction vector expressed in frames defined by orientations. By default, the reference frame of these orientations is the north-east-down (NED) reference frame. See Gravity Direction for more details.

D = gravitydir(orientations,RF) specifies the reference frame as the "NED" (north-east-down) frame or the "ENU" (east-north-up) frame.

Examples

Get Gravity Direction Vectors from Orientations

Create an identity quaternion and get the corresponding gravity direction vector. Verify that the gravity direction vector is [0 0 1] as expected.

quat0 = ones(1,"quaternion");
dir1 = gravitydir(quat0)

dir1 = 1×3

     0     0     1

Next, create a quaternion that corresponds to an x-rotation of 90 degrees. Obtain the gravity direction vector.

angles = [0 0 90];
quat1 = quaternion(angles,"eulerd","ZYX","frame");
dir2 = gravitydir(quat1)

dir2 = 1×3

         0    1.0000    0.0000

You can visually verify this result by using the poseplot function. From the figure, you can see that the gravitational acceleration is along the y-axis.

poseplot(quat1)

Change the reference frame to the east-north-up (ENU) frame and get the gravity direction vector.

dir3 = gravitydir(quat1,"ENU")

dir3 = 1×3

         0   -1.0000   -0.0000

Finally, create a vector of random quaternions and obtain the corresponding gravity direction vectors.

rng(2023) % For repeatable results
quats = randrot(10,1);
D = gravitydir(quats)

D = 10×3

   -0.2859   -0.8615   -0.4197
   -0.7971   -0.3204    0.5119
    0.3598    0.7139   -0.6007
    0.3622    0.6720    0.6460
    0.1749    0.4020    0.8988
    0.4627    0.3655   -0.8077
    0.3134    0.8613    0.4000
    0.8776    0.4267   -0.2185
   -0.9924   -0.1226    0.0137
    0.4086   -0.4099    0.8155

Input Arguments

orientations — Orientations

N-by-1 vector of quaternion objects | 3-by-3-by-N array of rotation matrices

Orientations, specified as an N-by-1 vector of quaternion objects or as a 3-by-3-by-N array of rotation matrices. N is the total number of orientations.

RF — Reference frame

"NED" | "ENU"

Reference frame, specified as "NED" for the north-east-down frame or "ENU" for the east-north-up frame.

Data Types: string | char

Output Arguments

D — Gravity direction vectors

N-by-3 real-valued matrix

Gravity direction vectors, returned as an N-by-3 real-valued matrix. N is the total number of orientations. Each row of the matrix is a gravity direction vector.

More About

Gravity Direction

The gravitydir function returns the gravity direction vector expressed in the body frame whose orientation is given by the orientations input argument. For example, in the NED reference frame, the orientation defines the rotational coordinate transformation from the NED frame (X-Y-Z) to the body frame (x-y-z). The gravitydir function resolves the gravity direction vector g into three components g_x, g_y, and g_z and returns these components.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023b