# geoTrajectory

## Description

The `geoTrajectory`

System object™ generates trajectories based on waypoints in geodetic coordinates. When you
create the System object, you can specify the time of arrival, velocity, and orientation at each
waypoint. The `geoTrajectory`

System object involves three coordinate systems. For more details, see Coordinate Frames in Geo Trajectory.

To generate an Earth-centered waypoint trajectory in geodetic coordinates:

Create the

`geoTrajectory`

object and set its properties.Call the object as if it were a function.

To learn more about how System objects work, see What Are System Objects?.

## Creation

### Syntax

### Description

returns a `trajectory`

= geoTrajectory(`Waypoints`

,`TimeOfArrival`

)`geoTrajectory`

System object, `trajectory`

,
based on the specified geodetic waypoints, `Waypoints`

, and the
corresponding time, `TimeOfArrival`

.

sets each creation argument or property `trajectory`

= geoTrajectory(`Waypoints`

,`TimeOfArrival`

,`Name,Value`

)`Name`

to the specified
`Value`

. Unspecified properties and creation arguments have default or
inferred values.

**Example: **```
trajectory =
geoTrajectory([10,10,1000;10,11,1100],[0,3600])
```

creates a geodetic waypoint
trajectory System object, `geojectory`

, that moves one degree in
longitude and 100 meters in altitude in one hour.

### Creation Arguments

Creation arguments are properties which are set during creation of the System object and cannot be modified later. If you do not explicitly set a creation argument value, the property value is inferred.

You can specify `Waypoints`

and `TimeOfArrival`

as
value-only arguments or name-value pairs.

## Properties

Unless otherwise indicated, properties are *nontunable*, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
`release`

function unlocks them.

If a property is *tunable*, you can change its value at
any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

`SampleRate`

— Sample rate of trajectory (Hz)

`1`

(default) | positive scalar

Sample rate of the trajectory in Hz, specified as a positive scalar.

**Tunable: **Yes

**Data Types: **`double`

`SamplesPerFrame`

— Number of samples per output frame

`1`

(default) | positive integer

Number of samples per output frame, specified as a positive integer.

**Tunable: **Yes

**Data Types: **`double`

`Waypoints`

— Positions in geodetic coordinates [deg deg m]

[0 0 0] (default) | *N*-by-3 matrix

Positions in geodetic coordinates, specified as an *N*-by-3 matrix.
*N* is the number of waypoints. In each row, the three elements
represent the latitude in degrees, longitude in degrees, and altitude above the WGS84
reference ellipsoid in meters of the geodetic waypoint. When *N* = 1,
the trajectory is at a stationary position.

#### Dependencies

To set this property, you must also set valid values for the
`TimeOfArrival`

property.

**Data Types: **`double`

`TimeOfArrival`

— Time at each waypoint (s)

`Inf`

(default) | *N*-element column vector of nonnegative increasing
numbers

Time at each waypoint in seconds, specified as an *N*-element
column vector. The number of samples, *N*, must be the same as the
number of samples (rows) defined by `Waypoints`

. If the trajectory is
stationary (only one waypoint specified in the `Waypoints`

property),
then the specified property value for `TimeOfArrival`

is ignored and
the default value, `Inf`

, is used.

#### Dependencies

To set this property, you must also set valid values for the
`Waypoints`

property.

**Data Types: **`double`

`Velocities`

— Velocity in local reference frame at each waypoint (m/s)

`[0 0 0]`

(default) | *N*-by-3 matrix

Velocity in the local reference frame at each waypoint in meters per second,
specified as an *N*-by-3 matrix. The number of samples,
*N*, must be the same as the number of samples (rows) defined by
`Waypoints`

.

If you do not specify the velocity, the object infers velocities from waypoints.

If you specify the velocity as a non-zero value, the object obtains the course of the trajectory accordingly.

**Data Types: **`double`

`Course`

— Angle between velocity direction and North (degree)

*N*-element vector of scalars

Angle between the velocity direction and the North direction, specified as an
*N*-element vector of scalars in degrees. The number of samples,
*N*, must be the same as the number of samples (rows) defined by
`Waypoints`

. If neither `Velocities`

nor
`Course`

is specified, course is inferred from the
waypoints.

#### Dependencies

To set this property, do not specify the `Velocities`

property
during object creation.

**Data Types: **`double`

`GroundSpeed`

— Groundspeed at each waypoint (m/s)

*N*-element real vector

Groundspeed at each waypoint, specified as an *N*-element real
vector in m/s. If you do not specify the property, it is inferred from the waypoints.
The number of samples, *N*, must be the same as the number of samples
(rows) defined by `Waypoints`

.

#### Dependencies

To set this property, do not specify the `Velocities`

property
during object creation.

**Data Types: **`double`

`Climbrate`

— Climb rate at each waypoint (m/s)

*N*-element real vector

Climb rate at each waypoint, specified as an *N*-element real
vector in degrees. The number of samples, *N*, must be the same as the
number of samples (rows) defined by `Waypoints`

. If neither
`Velocities`

nor `Course`

is specified, climb
rate is inferred from the waypoints.

#### Dependencies

To set this property, do not specify the `Velocities`

property
during object creation.

**Data Types: **`double`

`Orientation`

— Orientation at each waypoint

*N*-element quaternion column vector | 3-by-3-by-*N* array of real numbers

Orientation at each waypoint, specified as an *N*-element `quaternion`

column vector
or as a 3-by-3-by-*N* array of real numbers in which each 3-by-3 array
is a rotation matrix. The number of quaternions or rotation matrices,
*N*, must be the same as the number of samples (rows) defined by
`Waypoints`

.

Each quaternion or rotation matrix is a frame rotation from the local reference frame (NED or ENU) at the waypoint to the body frame of the platform on the trajectory.

**Data Types: **`quaternion`

| `double`

`AutoPitch`

— Align pitch angle with direction of motion

`false`

(default) | `true`

Align pitch angle with the direction of motion, specified as `true`

or `false`

. When specified as `true`

, the pitch angle
aligns with the direction of motion. If specified as `false`

, the pitch
angle is set to zero.

#### Dependencies

To set this property, the `Orientation`

property must not be
specified during object creation.

`AutoBank`

— Align roll angle to counteract centripetal force

`false`

(default) | `true`

Align the roll angle to counteract the centripetal force, specified as
`true`

or `false`

. When specified as
`true`

, the roll angle automatically counteracts the centripetal
force. If specified as `false`

, the roll angle is set to zero (flat
orientation).

#### Dependencies

To set this property, do not specify the `Orientation`

property
during object creation.

`ReferenceFrame`

— Local reference frame of trajectory

`'NED'`

(default) | `'ENU'`

Local reference frame of the trajectory, specified as `'NED'`

(North-East-Down) or `'ENU'`

(East-North-Up). The local reference frame
corresponds to the current waypoint of the trajectory. The velocity, acceleration, and
orientation of the platform are reported in the local reference frame. For more details,
see Coordinate Frames in Geo Trajectory.

## Usage

### Description

`[`

outputs a frame of trajectory data based on specified creation arguments and properties,
where `positionLLA`

,`orientation`

,`velocity`

,`acceleration`

,`angularVelocity`

,`ecef2ref`

] = trajectory()`trajectory`

is a `geoTrajectory`

object.

### Output Arguments

`positionLLA`

— Geodetic positions in latitude, longitude, and altitude (deg deg m)

*M*-by-3 matrix

Geodetic positions in latitude, longitude, and altitude, returned as an
*M*-by-3 matrix. In each row, the three elements represent the
latitude in degrees, longitude in degrees, and altitude above the WGS84 reference
ellipsoid in meters of the geodetic waypoint.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

`orientation`

— Orientation in local reference coordinate system

*M*-element quaternion column vector | 3-by-3-by-*M* real array

Orientation in the local reference coordinate system, returned as an
*M*-by-1 `quaternion`

column
vector or as a 3-by-3-by-*M* real array in which each 3-by-3 array is
a rotation matrix.

Each quaternion or rotation matrix is a frame rotation from the local reference frame (NED or ENU) to the body frame.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

`velocity`

— Velocity in local reference coordinate system (m/s)

*M*-by-3 matrix

Velocity in the local reference coordinate system in meters per second, returned
as an *M*-by-3 matrix.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

`acceleration`

— Acceleration in local reference coordinate system (m/s^{2})

*M*-by-3 matrix

Acceleration in the local reference coordinate system in meters per second
squared, returned as an *M*-by-3 matrix.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

`angularVelocity`

— Angular velocity in local reference coordinate system (rad/s)

*M*-by-3 matrix

Angular velocity in the local reference coordinate system in radians per second,
returned as an *M*-by-3 matrix.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

`ecef2ref`

— Orientation of local reference frame with respect to ECEF frame

*M*-element quaternion column vector | 3-by-3-by-*M* real array

Orientation of the local reference frame with respect to the ECEF
(Earth-Centered-Earth-Fixed) frame, returned as an *M*-by-1 `quaternion`

column
vector or as a 3-by-3-by-*M* real array in which each 3-by-3 array is
a rotation matrix.

Each quaternion or 3-by-3 rotation matrix is a frame rotation from the ECEF frame to the local reference frame (NED or ENU) corresponding to the current waypoint.

*M* is specified by the `SamplesPerFrame`

property.

**Data Types: **`double`

## Object Functions

To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named `obj`

, use
this syntax:

release(obj)

### Specific to `geoTrajectory`

`lookupPose` | Obtain pose of geodetic trajectory for a certain time |

`perturbations` | Perturbation defined on object |

`perturb` | Apply perturbations to object |

## Examples

### Create `geoTrajectory`

and Look Up Pose

Create a `geoTrajectory`

with starting LLA at [15 15 0] and ending LLA at [75 75 100]. Set the flight time to ten hours. Sample the trajectory every 1000 seconds.

```
startLLA = [15 15 0];
endLLA = [75 75 100];
timeOfTravel = [0 3600*10];
sampleRate = 0.001;
trajectory = geoTrajectory([startLLA;endLLA],timeOfTravel,'SampleRate',sampleRate);
```

Output the LLA waypoints of the trajectory.

positionsLLA = startLLA; while ~isDone(trajectory) positionsLLA = [positionsLLA;trajectory()]; end positionsLLA

`positionsLLA = `*37×3*
15.0000 15.0000 0
16.6667 16.6667 2.7778
18.3333 18.3333 5.5556
20.0000 20.0000 8.3333
21.6667 21.6667 11.1111
23.3333 23.3333 13.8889
25.0000 25.0000 16.6667
26.6667 26.6667 19.4444
28.3333 28.3333 22.2222
30.0000 30.0000 25.0000
⋮

Look up the Cartesian waypoints of the trajectory in the ECEF frame by using the `lookupPose`

function.

```
sampleTimes = 0:1000:3600*10;
n = length(sampleTimes);
positionsCart = lookupPose(trajectory,sampleTimes,'ECEF');
```

Visualize the results in the ECEF frame.

figure() km = 1000; plot3(positionsCart(1,1)/km,positionsCart(1,2)/km,positionsCart(1,3)/km, 'b*'); hold on; plot3(positionsCart(end,1)/km,positionsCart(end,2)/km,positionsCart(end,3)/km, 'bo'); plot3(positionsCart(:,1)/km,positionsCart(:,2)/km,positionsCart(:,3)/km,'b'); plot3([0 positionsCart(1,1)]/km,[0 positionsCart(1,2)]/km,[0 positionsCart(1,3)]/km,'k:'); plot3([0 positionsCart(end,1)]/km,[0 positionsCart(end,2)]/km,[0 positionsCart(end,3)]/km,'k:'); xlabel('x (km)'); ylabel('y (km)'); zlabel('z (km)'); legend('Start position','End position', 'Trajectory')

## Algorithms

### Coordinate Frames in Geo Trajectory

The `geoTrajectory`

System object involves three coordinate frames:

ECEF (Earth-Centered-Earth-Fixed) frame

Local reference frame: local NED (North-East-Down) or ENU (East-North-Up) frame

Target body frame

The figure shows an Earth-centered trajectory with two waypoints highlighted. The
figures uses the **NED** local reference frame as an example,
but you can certainly use the ENU local reference frame. In the figure,

*E*_{x},*E*_{y}, and*E*_{z}are the three axes of the ECEF frame, which is fixed on the Earth.*B*_{x},*B*_{y}, and*B*_{z }are the three axes of the target body frame, which is fixed on the target.

*N*,*E*, and*D*are the three axes of the local NED frame. The figure highlights two local NED reference frames,*N*_{1}-*E*_{1}-*D*_{1}and*N*_{2}-*E*_{2}-*D*_{2}. The origin of each local NED frame is the Earth surface point corresponding to the trajectory waypoint based on the WGS84 ellipsoid model. The horizontal plane of the local NED frame is tangent to the WGS84 ellipsoid model's surface.

*λ* and *ϕ* are the geodetic longitude and latitude,
respectively. The orientation of the target by using the NED local frame convention is
defined as the rotation from the local NED frame to the target's body frame, such as the
rotation from
*N*_{1}-*E*_{1}-*D*_{1}
to
*B*_{x}-*B*_{y}-*B*_{z}.

### Trajectory Calculation

The `geoTrajectory`

System object generates a smooth trajectory that passes
through waypoints. It begins by using an equi-rectangular projection to lay out the
*xy* path. In this projection, latitude and longitude coordinates are
directly projected onto a Cartesian *XY* grid.

Then, the `geoTrajectory`

object connects the *XY* grid
projections of the waypoints through a piecewise interpolation using clothoid curves. The
curvature of the curve between consecutive waypoints varies linearly with the curve length.
To ensure smoothness and minimize discontinuities in the curvature, the tangent direction of
the path at each waypoint is chosen, unless the course is specified explicitly via the
`Course`

property or implicitly via the `Velocities`

property. Once the path is established, the `geoTrajectory`

object uses cubic
Hermite interpolation to determine the vehicle's location along the trajectory as a function
of time and the planar distance traveled.

The normal component (*Z*-component) of the trajectory is subsequently
chosen to satisfy a shape-preserving piecewise spline (PCHIP) unless the climb rate is
specified explicitly via the `ClimbRate`

property or the third column of
the `Velocities`

property.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

The object functions, `perturbations`

and
`perturb`

, do not support code generation.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

## Version History

**Introduced in R2024a**

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)