# 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.```

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

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

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.

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.

## Version History

Introduced in R2023b