geoTrajectory

Waypoint trajectory in geodetic coordinates

Since R2021a

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:

1. Create the geoTrajectory object and set its properties.

2. Call the object as if it were a function.

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

Creation

Syntax

trajectory = geoTrajectory(Waypoints,TimeOfArrival)

trajectory = geoTrajectory(Waypoints,TimeOfArrival,Name,Value)

Description

trajectory = geoTrajectory(Waypoints,TimeOfArrival) returns a geoTrajectory System object, trajectory, based on the specified geodetic waypoints, Waypoints, and the corresponding time, TimeOfArrival.

trajectory = geoTrajectory(Waypoints,TimeOfArrival,Name,Value) sets each creation argument or property 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

Syntax

[positionLLA,orientation,velocity,acceleration,angularVelocity,ecef2ref] = trajectory()

Description

[positionLLA,orientation,velocity,acceleration,angularVelocity,ecef2ref] = trajectory() outputs a frame of trajectory data based on specified creation arguments and properties, where 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²)

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

Common to All System Objects

clone	Create duplicate System object
step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object
isDone	End-of-data status

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₁-E₁-D₁ and N₂-E₂-D₂. 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₁-E₁-D₁ to B_x-B_y-B_z.

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 R2021a