AirRouteOperator Class
Route planning between given waypoints for a rotary-wing aircraft, avoiding restricted airspaces and exploiting terrain for concealment.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class AirRouteOperator : OperatorRemarks
This operator can find a flight route for a rotary-wing aircraft along a given list of waypoints, avoiding restricted airspaces and exploiting terrain for concealment. The generated route will be nap-of-the-earth except when it needs to reach a high waypoint or fly over an airspace.
 |
 |
This reference documentation contains all the details, but for more accessible discussions about the design and usage of the operator, see Aircraft Routing. There is also a sample map configuration, air_route_operator.px, that is described in detail in the Aircraft Routing Tutorial. Also note that the operator has many similarities with the TerrainRouteOperator.
Introduction to the operator properties
The AircraftType property specifies how the aircraft flies, with properties that give the maximal altitude, the speeds at different climb angles, and preferred climb and descent angles. See the type AircraftType for details.
As input, the operator takes
one or more waypoint sequences represented as line features, see WaypointsInput;
terrain elevations as rasters, see ElevationInput;
optional tree heights as rasters, see TreeHeightInput;
optional airspace features, see AirspaceInput;
an optional raster defining terrain concealment for nap-of-the-earth flight, see LowFlightSafetyInput.
The airspaces can be extruded polygons, lines or points with floor and ceiling controlled via AirspaceBottomElevation and AirspaceTopElevation, or they can be volume-encoding rasters from a LineOfSightOperator or an AirspaceCoverageOperator.
Each airspace feature can be given a safety factor, see AirspaceSafety, that controls how reluctant or eager the AirRouteOperator will be to pass through the airspace. The output route feature will get attributes giving the distance and time spent inside each airspace that has a name, see AirspaceName.
The generated route can make detours through terrain areas that offer better concealment during nap-of-the-earth flight, if those areas are described by a raster from the LowFlightSafetyInput. It is also possible to adjust the general safety factor for higher flight, see HighFlightSafety.
The VerticalClearance property gives the route height above treetops for nap-of-the-earth flight.
The SearchMargin controls how far away from the waypoints the route may go.
The resolution for the calculations must be one of the available resolutions from the ElevationInput, but you can control which one is chosen via the DesiredResolution property.
Performance
The operator can be slow. The simplest way to improve performance is to use a shorter SearchMargin and a coarser DesiredResolution, although this can affect the quality of the results.
It is best to use a dynamic OrdinaryLayer.CacheMode, preferably DynamicAsync, but the ID-giving input will then be the WaypointsInput, which means that the dynamic cache will assume that all data from other inputs are static. So, special application logic is needed to handle modifications of features from other inputs, for example the AirspaceInput; see OrdinaryLayerCacheMode for details. Unfortunately, the general Carmenta Explorer application does not support this special behavior, so it is impractical to demonstrate the AirRouteOperator in Carmenta Explorer using a dynamic cache mode if there are editable airspaces. See the also Aircraft Routing Tutorial.
Basic output
The basic output is a set of subroute features with line geometries, one for each leg of the waypoints feature, and possibly some point features that can serve as warnings.
A warning point feature will be generated for each waypoint that is below treetops or higher than the maximal altitude of the aircraft. The operator will tolerate such waypoints and simply generate a route based on an adjusted waypoint position at treetop level or at the maximal altitude. The adjusted waypoint position will also be output as a point feature that either has the attribute waypointBelowTreetops = True or the attribute waypointTooHigh = True, plus copies of the attributes of the current feature from WaypointsInput. (If the TreeHeightInput is null, the treetops level will coincide with the ground.)
Three other kinds of output can be enabled via the boolean properties OutputRoutePointFeatures, OutputTravelTimeRoute and OutputSearchBounds. The rest of this section describes only the basic subroute features with line geometries.
Each such subroute feature will get copies of the attributes of the current feature from WaypointsInput, which can be useful if several waypoints features appear in the same update. Moreover, each subroute feature will get new attributes for the travel times and travel distances. Most attributes come in two versions, one with a name starting with "leg" that gives a value for the current leg, and another one with a name starting with "accumulated" that give the sum of the values for the current and all previous legs.
Name | Type | Description |
|---|---|---|
legDistance | Double | Travel distance along this leg, in meters. |
accumulatedDistance | Double | Total travel distance along this and all previous legs, in meters. |
legTimeSeconds | Double | Travel time along this leg, in seconds. |
accumulatedTimeSeconds | Double | Total travel time along this and all previous legs, in seconds. |
legTimeString | String | Travel time along this leg, formatted as hours/minutes/seconds like "7M 05S" or "2H 07M 05S", or just "?" or "!" to indicate a failed search. (If you prefer to design your own format, see the section "Formatting travel times" below.) |
accumulatedTimeString | String | Total travel time along this and previous legs, formatted as hours/minutes/seconds as above, or just "?" to indicate a failed search. |
legIndex | Int | The index of the leg, starting from 0. |
isLastLeg | Bool | True for the last leg, null otherwise. If you want to display only the accumulated values for the last leg, you can use isLastLeg in a text visualizer condition. |
routeFound | Bool | True if a route was found for this leg, otherwise False; see next section. |
constrainedBySearchMargin | Bool | True if the search process encountered the edge of the search bounds, and False otherwise. |
zMeaning | String | "Height". This distinguishes this feature from the similar one controlled by OutputTravelTimeRoute. |
If constrainedBySearchMargin is True, the route for this leg might be improved by using a larger SearchMargin.
If there are airspaces, the output route features will have some more attributes; see the section "Attributes from airspaces" below.
Placeholder output features can represent failure
If the operator fails to find a subroute for a certain leg, it will output a placeholder feature with the attribute routeFound being False and a line geometry that is just a straight segment between the two waypoints. The routeFound attribute should be used to generate a special visualization, but the condition for that visualization cannot just be not routeFound, because some output features may be points that will lack the routeFound attribute, and a null attribute value will be treated as being False if it is automatically converted to a boolean value. Two conditions that work are
routeFound = false
and
geoType = #line and not routeFound
The latter condition is used in the sample configuration air_route_operator.px:
 |
In the placeholder feature, the legTimeString attribute will be either "?" or "!"; it will be "?" if constrainedBySearchMargin is True (maybe a subroute can be found if the SearchMargin is increased), and it will be "!" otherwise (it's hopeless; an exclamation mark means not in many programming languages). The accumulatedTimeString will be "?" for the failed leg feature and all subsequent leg features. As for the numeric attributes, the ones that are leg-specific will be null for the failed leg feature, and the ones that are accumulated will be null for the failed leg feature and all subsequent leg features.
A special cause of failure is a leg that is steeper than 70°, which will generate a placeholder feature with an additional attribute legTooSteep being True. See the section Limitations in Aircraft Routing.
Attributes from airspaces
Each airspace feature can have a name; see AirspaceName. If the airspace has a positive AirspaceSafety, the generated route may pass through it, in which case the airspace will give six extra attributes to the route line features, with attribute names based on the airspace name and with values that give the travel time and distance through the airspace. For example, if the AirspaceName for an airspace evaluates to FIRE, these attributes will be:
Name | Type | Description |
|---|---|---|
legDistance_FIRE | Double | Horizontal travel distance in the FIRE airspace along this leg, in meters. |
accumulatedDistance_FIRE | Double | Total horizontal travel distance in the FIRE airspace along this and all previous legs, in meters. |
legTimeSeconds_FIRE | Double | Travel time in the FIRE airspace along this leg, in seconds. |
accumulatedTimeSeconds_FIRE | Double | Total travel time in the FIRE airspace along this and all previous legs, in seconds. |
legTimeString_FIRE | String | Travel time in the FIRE airspace along this leg, formatted as hours/minutes/seconds, for example "7M 05S" or "2H 07M 05S". (If you prefer to design your own format, see the section "Formatting travel times" below.) |
accumulatedTimeString_FIRE | String | Total travel time in the FIRE airspace along this and all previous legs, formatted as hours/minutes/seconds as above. |
The airspace names need not be unique. If there are several FIRE airspaces, the travel times and distances through them all are summed and used for the FIRE attributes.
Formatting travel times
As noted above, the operator generates the attributes legTimeString and accumulatedTimeString that are formatted as "7M 05S" or "2H 07M 05S"; this is a simplification of the ISO 8601 format for time durations. But you may prefer another format: for example, you may dislike the uppercase H, M, S symbols of ISO 8601 and prefer the lowercase h, min, s symbols recommended by the International Bureau of Weights and Measures. In that case, you can design your own format by using an Expression that manipulates the corresponding Double attribute that gives the time in seconds. First, you would need integer sub-expressions that generates the hours, minutes and seconds values, like these:
Component | Sub-expression |
|---|---|
Hours | int(legTimeSeconds) / 3600 |
Minutes | (int(legTimeSeconds) / 60) % 60 |
Seconds | int(legTimeSeconds) % 60 |
Since the numerals are integers and the int() function rounds to an integer, the division operations above will be integer division, while the percent means remainder.
The sub-expressions can be combined into a string expression like this:
$"{int(legTimeSeconds) / 3600}h {(int(legTimeSeconds) / 60) % 60}min {int(legTimeSeconds) % 60}s"
For more information about the use of curly braces in dollar-prefixed strings, see the section "Interpolated strings" in Expression Syntax.
Note: in the special case of a placeholder leg feature that represents a failed search, the legTimeSeconds will be null, so the three sub-expressions will evaluate to null, but null sub-expressions in an interpolated string are replaced by empty strings, so the result will be the string "h min s". To avoid displaying such a label, use legTimeSeconds != null as your Visualizer.Condition.
Another issue with the interpolated string is that the hours component is generated also for zero hours. To discard the hours component when it is zero, you can move the h character into an if-then-else expression inside the first curly braces:
$"{ if int(legTimeSeconds) < 3600
then null
else string(int(legTimeSeconds) / 3600) + \"h \"
}{(int(legTimeSeconds) / 60) % 60}min {int(legTimeSeconds) % 60}s"
The else-expression contains the string expression "h ", but its quotation marks must be escaped here since they occur between the quotation marks of the whole interpolated string.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
AirRouteOperator
Platforms
Windows, Linux, Android
See Also
Reference
Operators Module
AircraftType
TerrainRouteOperator
Other Resources
Aircraft Routing
Aircraft Routing Tutorial
Terrain Vehicle Analysis
AirRouteOperator Members
The AirRouteOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| AirRouteOperator | Creates a new instance of the AirRouteOperator class. |
Properties
| Name | Description |
|---|---|
| AircraftType | Gets or sets the aircraft type. |
| AirspaceBottomElevation | Gets or sets the elevation of the bottom surface of an airspace, in meters. |
| AirspaceInput | Gets or sets an operator giving airspaces that may be forbidden or have a positive safety factor. |
| AirspaceName | Gets or sets an attribute variable giving the name of each airspace. |
| AirspaceSafety | Gets or sets an attribute variable giving the safety factor of each airspace. |
| AirspaceTopElevation | Gets or sets the elevation of the top surface of an airspace, in meters. |
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DesiredResolution | Gets or sets the desired raster resolution for the computation. |
| DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
| ElevationInput | Gets or sets an operator giving a raster with terrain elevations. |
| HighFlightSafety | Gets or sets an attribute variable giving a safety factor for flight higher than nap-of-the-earth. |
| IsDisposed | Gets a value that tells whether the current AirRouteOperator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| LowFlightSafetyInput | Gets or sets an input operator that gives a raster with safety factors for nap-of-the-earth flight. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current AirRouteOperator represents. Inherited from EngineObject |
| OutputRoutePointFeatures | Gets or sets a flag that determines whether to output extra point features with useful attributes along the route. |
| OutputSearchBounds | Gets or sets a flag that determines whether to output a polygon feature representing the search bounds. |
| OutputTravelTimeRoute | Gets or sets a flag that determines whether to output an extra route feature where the z coordinates represent local travel times. |
| RoutePointFeaturesInterval | Gets or sets the time interval in seconds between extra route point features. |
| SearchMargin | Gets or sets an attribute variable giving a margin in meters around each waypoint segment, inside which all search is done. |
| TreeHeightInput | Gets or sets an input operator that provides rasters with tree heights above ground, in meters. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| VerticalClearance | Gets or sets the required vertical clearance above or below obstacles, in meters. |
| WaypointsInput | Gets or sets an operator that gives a waypoint sequence represented by a line feature. |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Operator |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Operator |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Operator |
| GetFeatures | Overloaded. Gets features from the operator chain. Inherited from Operator |
| GetLocalizedDescription | Gets a localized version of the operator description in a specific language. Inherited from Operator |
| GetLocalizedDisplayName | Gets a localized version of the operator display name in a specific language. Inherited from Operator |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Operator |
| GetRasterFeature | Overloaded. Gets raster features from the operator chain and merges them into a single raster. Inherited from Operator |
| HasLocalizedDescription | Checks if a localized version of the operator description is available in a specific language. Inherited from Operator |
| HasLocalizedDisplayName | Checks if a localized version of the operator display name is available in a specific language. Inherited from Operator |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Operator |
| SetLocalizedDescription | Sets a operator description in a specific language. Inherited from Operator |
| SetLocalizedDisplayName | Sets a operator display name in a specific language. Inherited from Operator |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the operator, for a specific language. Inherited from Operator |