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/s2)
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,
Ex, Ey, and Ez are the three axes of the ECEF frame, which is fixed on the Earth.
Bx, By, and Bz 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, N1-E1-D1 and N2-E2-D2. 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 N1-E1-D1 to Bx-By-Bz.
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)