Main Content

gravitydir

Gravity direction vector for given orientation

Since R2023b

collapse all in page

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.

example

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

Examples

collapse all

Open Live Script

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)

Figure contains an axes object. The axes object is empty.

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

collapse all

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.

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

collapse all

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

collapse all

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 gx, gy, and gz and returns these components.

Gravity direction vector decomposition

Extended Capabilities

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

Version History

Introduced in R2023b

See Also

| |