Click or drag to resize


A RouteProfile specifies the changes in height and speed along a particular segment of a route. The height, height rate, speed, linear and vertical accelerations are all defined by the profile to specify the position along the route as a function of time.

Note Note

The functionality described in this topic requires a license for the Route Design Library.

Available Profiles




Represents a constant height with respect to a given reference surface and the speed is determined by smoothly connecting the boundary conditions with the thrust acceleration or deceleration specified by the user. This is useful when modeling a constant altitude cruise for an aircraft or modeling the constant offset of a ground vehicle above a terrain surface.


Represents a profile that smoothly transitions between two boundary conditions in both height and speed. The profile geometry is defined by the initial and final height, height rate, and speed along with the user specified dynamics for the vertical rates and thrust acceleration or deceleration. This is useful when trying to transition between two boundary conditions and is used by the default connection segments to smoothly connect procedures. If the speeds change between the boundary conditions, the transition will attempt to accelerate or decelerate along a level height. If there is not enough room to change speed along a level slope, the transition will thrust along the inclined slope as it transitions between heights.


Represents a vertical profile for the route defined by the convex hull above a terrain surface such that the route lies above a minimum height above the terrain. This is useful when specifying waypoints in mountainous regions to provide an easy way to produce a valid route without having to worry about collisions with the terrain. Note: due to the nature of file-access for most terrain data, this may significantly slow down the time it takes to generate a route. The sampling size specified on the profile can be adjusted to profile courser sampling to improve performance at the cost of precision.

Using Profiles

To illustrate the behavior of the above profiles, consider the following figure:

Routing Profiles

Here, three different profiles were used to create a route. First, the profile maintains a constant height above the "EllipsoidSurfaceShape", shown in black. The usual default is to use EarthCentralBody.Shape (get / set). The next section shows the behavior of the route trying to avoid mountainous terrain, shown in green. Note how the route finds the convex hull above the terrain while connecting with the initial and final height. Lastly, the route transitions to a constant height above MeanSeaLevel (get / set), shown in red. Here is a code sample showing how to construct the different types of profiles:

EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
double speed = 30.0; // meters per second
double height = 1000.0; // meters
double maxAccelForTransition = Constants.EarthSurfaceGravity;
TerrainProvider ellipsoidSurface = new EllipsoidTerrainProvider(earth.getShape(), earth.getFixedFrame());
TerrainProvider localTerrain = myTerrainFileSource.getTerrain();
// Unless you use a CompositeTerrainProvider, positions outside of the terrain
// region will return NaN and cause errors.
CompositeTerrainProvider overallTerrainSurface = new CompositeTerrainProvider();

ConstantHeightProfile constantHeightOverShape = new ConstantHeightProfile(speed, maxAccelForTransition, maxAccelForTransition, height, ellipsoidSurface);

double minimumHeight = 100.0; // meters above terrain
double samplingDistance = 10.0; // meters along ellipsoid surface
double initialHeight = 2 * minimumHeight;
double finalHeight = 2 * minimumHeight;
double ascentSpeed = 10.0; // meters per second (constrains incline angles)
double descentSpeed = ascentSpeed; // (positive magnitude)
double thrustAcceleration = Constants.EarthSurfaceGravity;
double pitchAcceleration = Constants.EarthSurfaceGravity;
ProfileDynamics dynamics = new ProfileDynamics(ascentSpeed, pitchAcceleration, descentSpeed, pitchAcceleration, thrustAcceleration, thrustAcceleration);

TerrainAvoidanceProfile terrainAvoidance = new TerrainAvoidanceProfile(overallTerrainSurface, minimumHeight, samplingDistance, initialHeight, finalHeight, dynamics, speed);

double baseHeight = localTerrain.getHeightRelativeToShape(lon, lat);
double heightRate = 0.0;

StandardTransitionProfile noTerrainAvoidance = new StandardTransitionProfile(
        dynamics, new ProfileSpeed(speed, SpeedReference.TOTAL), 
        initialHeight + baseHeight, heightRate, 
        finalHeight + baseHeight, heightRate, 

ConstantHeightProfile constantHeightOverMSL = new ConstantHeightProfile(speed, maxAccelForTransition, maxAccelForTransition, height, earth.getMeanSeaLevel());

The values for the speed and the height specified in the profiles are represented in the "Flat Earth" (or "Flat Mars", etc.) space. Since the surface of a planet is non-Euclidean, there is a small discrepancy between a speed specified in the local "map" or "flat" space and the corresponding speed required to maintain the equivalent route in the "curved" space over the surface. Since these discrepancies are usually small (on the order of a centimeter per second for most velocities at altitudes within the troposphere), the values specified by the user in the profiles and the values reported by the various Scalar instances (see the Geometry topic) are represented in the "flat" space. The following figure illustrates the difference between the two.

Flat Earth

Note that the velocities at altitude are slightly larger in the curved space than in the flat space. This discrepancy shows up in the difference between the total velocity specified in the profile and the total FixedFrame (get / set) velocity from the Point returned from createPointFromRoute. The figure also shows the distinction between SpeedReference.SURFACE and SpeedReference.TOTAL. The green line shows the case where two reference surfaces are involved. If the green line represents the local terrain surface, a profile might specify SpeedReference.TOTAL and SpeedReference.SURFACE with zero rate of change in height with respect to the terrain. Then, when calculating the total speed with respect to the underlying surface, the non-zero height rate of the terrain is included.

Also note that the profiles each have a HeightReferenceSurface (get / set) property which defines the surface from which the height of the route is measured. Most routes will use either the EllipsoidTerrainProvider or the MeanSeaLevel (get / set) to represent zero height. It is important to note which surface each of the profiles is using. If the reference surface used by the procedures is different from that used by the connections, the system will try to reconcile the two different references ensuring that the heights and rates are continuous. However, if using different reference surfaces, it is more likely that the propagator will run into an issue and return either a configuration error or a discontinuity in the route. Here are some examples:

Different terrain for procedures vs connections

In this case, the propagator will attempt to configure the initial and final heights of the profiles such that the position of the vehicle above the underlying Ellipsoid reference surface is continuous, possibly resulting in different local heights with respect to the different surfaces. In general, this should not cause a configuration error unless one of the profiles cannot update its initial or final height, height rate, or speed.

Using discontinuous or composite terrain

In this case, the propagator will faithfully follow the terrain, including discontinuities. So, if a ground vehicle is driving along discontinuous terrain, its path will reflect the discontinuities. In general, users should never use terrain with a lot of variation as a reference surface when specifying an aircraft route (StandardTransitionProfile). However, if a craggy terrain file is specified as the reference it will create a smooth route above the "flat" zero height reference surface of the terrain, yielding a craggy route in the fixed frame of the central body. In the case of MeanSeaLevel (get / set), there may be some slight discontinuities in the height rates which show up due to bi-linear interpolation between terrain posts. (For more information, see: EarthGravityModel96MeanSeaLevel)

Using the same terrain across the route

In this case, the propagator will create a route above the given terrain. However, note that the route specified by the profiles exists in a "flat" space above the terrain, and the propagator will include the "dynamics" of the terrain when creating the trajectory in the fixed frame of the central body. This means that unless the terrain is EllipsoidTerrainProvider, the terrain may add additional effects to the height rate and/or surface speeds specified by the user in addition to those effects described above from the non-Euclidean motion over the curved surface.

Using a route beyond the valid terrain

If the specified waypoints for a route take the route outside the valid extent of the height reference, the TerrainProvider will return NaN for the height and associated gradients. This will generally cause an exception when propagating the route. So, users should take care to keep the route inside the bounds of the local terrain or use a CompositeTerrainProvider, as shown above, to specify what the height reference should be outside of the local terrain region. While the latter will provide a 'valid' route, the route will reflect the discontinuity in the terrain when the path moves from one terrain surface to another.