TerrainRouteOperator Class
Finds a route in terrain or on roads for a given vehicle type and waypoints.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class TerrainRouteOperator : TerrainMobilityOperatorRemarks
For a general introduction to this and similar operators, see Terrain Vehicle Analysis.
For input, this operator takes road information in the form of line features from RoadInput, and three kinds of terrain information in the form of raster features from ElevationInput, GroundConditionInput and SurfaceStructureInput. An optional RestrictedAreaInput can give areas that are forbidden or just dangerous. The operator then calculates the fastest route for a specified VehicleType through a given list of waypoints from WaypointsInput. The vehicle type is normally a terrain vehicle, and the calculated route can go both off-road and on-road. There is a sample map configuration, terrain_route_operator.px, that you can try in Carmenta Explorer. Also note that the operator has many similarities with the AirRouteOperator.
Waypoints Input
The start point, goal point, and any intermediate waypoints come to the operator from the WaypointsInput in the form of a line feature, whose nodes are the waypoints that must be passed.
Road Input and Terrain Input
Roads may come as line features via RoadInput, while three kinds of terrain factors may come as raster features via ElevationInput, GroundConditionInput and SurfaceStructureInput.
Technically, the roads and the terrain rasters are not required input. If GroundConditionInput is null, the DefaultGroundCondition will be assumed, and if SurfaceStructureInput is null, the DefaultSurfaceStructure will be assumed. If ElevationInput is null, the ground is assumed to be flat.
 |
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 in that case, it is the MemoryDataSet that gives features to the WaypointsInput that will be the ID-giving MemoryDataSet, which means that the cache assumes that all data from other inputs are static. So, special application logic is needed if there are modifications of features from other inputs, for example the RestrictedAreaInput; see OrdinaryLayerCacheMode for details. Unfortunately, the general Carmenta Explorer map viewer does not support this special logic, so it is not possible to demonstrate the TerrainRouteOperator in Carmenta Explorer using both a dynamic cache mode and editable restricted areas – that is why the sample configuration does not use a dynamic cache mode.
Basic Output
The basic output is a set of subroute features, one for each leg of the waypoints feature. You can get more details by setting OutputRouteDetails = True, which will generate an additional representation of each subroute consisting of shorter parts with special attributes. You can also get the rectangular search bounds as a polygon by setting OutputSearchBounds = True. Here, we describe only the basic output.
 |
Each 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, travel distances, and ferry usage. 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 |
|---|---|---|
routeFound | Bool | True if a route was found (see next section). |
legDistance | Int | Travel distance along this leg, in meters. |
accumulatedDistance | Int | Total travel distance along this and all previous legs, in meters. |
legTimeSeconds | Int | Travel time along this leg, in seconds. |
accumulatedTimeSeconds | Int | 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. |
legNumFerryRoutes | Int | Number of ferry route features along this leg. |
accumulatedNumFerryRoutes | Int | Total number of ferry route features for this and all previous legs. |
legIndex | Int | The index of the leg, starting from 0. |
isLastLeg | Bool | True for the last leg, undefined otherwise. If you want to display only the accumulated values for the last leg, you can use isLastLeg in a text visualizer condition. |
constrainedBySearchMargin | Bool | True if the search process encountered the edge of the search rectangle, and False otherwise. |
Since the ferry schedules are not known by the operator, an application should give a clear warning about any ferry usage in a route (failure to do so can cause frustration and satire). If you want to highlight or warn about other kinds of roads, you must use OutputRouteDetails.
If constrainedBySearchMargin is True, the route for this leg might be improved by using a larger SearchMargin. In the sample configuration, terrain_route_operator.px, a dashed line style for the route indicates that the search was constrained.
If there are softly restricted areas, the route legs will have some more attributes; see the section "Softly restricted areas" below.
Placeholder output features can represent failure
The subroute features are normally lines, but if the operator fails to find a subroute for a certain leg, the operator will output a placeholder feature that is just a point halfway on the leg, where you can place a label to indicate the failure. The placeholder point feature will have the attribute routeFound = False. 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 undefined (null) for the failed leg feature, and the ones that are accumulated will be undefined for the failed leg feature and all subsequent leg features.
Restricted Areas
The optional RestrictedAreaInput can gives areas that are normally forbidden to pass through. The restricted areas can be represented by points, lines or polygons, or integer rasters where 1s are forbidden but 0s are allowed.
 |
Softly restricted areas
It is possible to have softly restricted areas. The property RestrictedAreaSafety evaluates, from the area attributes and/or the waypoints attributes, a safety between 0 and 1 that controls how reluctant the operator is to pass through the area.
So, if the safety is greater than zero, the area will not be completely forbidden. In that case, it can be useful to give each area a name, controlled via the property RestrictedAreaName. Let us say we have two softly restricted areas with the names "SNIPER" and "RADIATION". The legs of the generated routes will then have six extra attributes for each area name, giving the travel time and distance through the area; for the SNIPER area, they will be:
Name | Type | Description |
|---|---|---|
legDistance_SNIPER | Int | Travel distance in the SNIPER area along this leg, in meters. |
accumulatedDistance_SNIPER | Int | Total travel distance in the SNIPER area along this and all previous legs, in meters. |
legTimeSeconds_SNIPER | Int | Travel time in the SNIPER area along this leg, in seconds. |
accumulatedTimeSeconds_SNIPER | Int | Total travel time in the SNIPER area along this and all previous legs, in seconds. |
legTimeString_SNIPER | String | Travel time in the SNIPER area 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_SNIPER | String | Total travel time in the SNIPER area along this and all previous legs, formatted as hours/minutes/seconds as above. |
The analogous extra attributes for the RADIATION area will of course be named legDistance_RADIATION etc.
The restricted area names need not be unique. If there are several SNIPER areas, the travel times and distances through them all are summed and used for the SNIPER 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 integer 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 | legTimeSeconds / 3600 |
Minutes | (legTimeSeconds / 60) % 60 |
Seconds | legTimeSeconds % 60 |
Since the numerals and the attribute value are integers, 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:
$"{legTimeSeconds / 3600}h {(legTimeSeconds / 60) % 60}min {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 legTimeSeconds < 3600
then null
else string(legTimeSeconds / 3600) + \"h \"
}{(legTimeSeconds / 60) % 60}min {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
TerrainMobilityOperator
TerrainRouteOperator
Platforms
Windows, Linux, Android
See Also
Reference
Operators Module
AirRouteOperator
RoadDirectionality
RoadType
TerrainAccessOperator
TerrainSpeedOperator
TerrainSpeed
TerrainVehicleType
Other Resources
Terrain Vehicle Analysis
Aircraft Routing
Aircraft Routing Tutorial
TerrainRouteOperator Members
The TerrainRouteOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| TerrainRouteOperator | Initializes a new instance of the TerrainAccessOperator class. |
Properties
| Name | Description |
|---|---|
| DefaultGroundCondition | Gets or sets the default ground condition class, used when GroundConditionInput is null. Inherited from TerrainMobilityOperator |
| DefaultSurfaceStructure | Gets or sets the default surface structure class, used when SurfaceStructureInput is null. Inherited from TerrainMobilityOperator |
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DesiredResolution | Gets or sets the desired raster resolution for the computation. Inherited from TerrainMobilityOperator |
| 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. Inherited from TerrainMobilityOperator |
| ElevationUnit | Gets or sets the height unit of the raster from ElevationInput. Inherited from TerrainMobilityOperator |
| GroundConditionInput | Gets or sets an operator that gives ground condition classes (soil strength) as a raster. Inherited from TerrainMobilityOperator |
| IsDisposed | Gets a value that tells whether the current TerrainRouteOperator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| MaxWaypointSnapDistance | Gets or sets an attribute variable giving the maximal distance a waypoint is snapped to the nearest road. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current TerrainRouteOperator represents. Inherited from EngineObject |
| OutputRouteDetails | Gets or sets a boolean that says whether more detailed route features shall be output. |
| OutputSearchBounds | Gets or sets a boolean that says whether the rectangular search bounds polygon shall be output. |
| RestrictedAreaInput | Gets or sets an operator that gives restricted areas that normally cannot be passed. Inherited from TerrainMobilityOperator |
| RestrictedAreaName | Gets or sets an attribute variable giving the name of each restricted area. |
| RestrictedAreaSafety | Gets or sets an attribute variable giving the safety factor of each restricted area. |
| RoadClass | Gets or sets an attribute variable giving the quality class of a road feature. Inherited from TerrainMobilityOperator |
| RoadDirectionality | Gets or sets an attribute variable giving the directionality of a road feature. |
| RoadInput | Gets or sets an operator that gives roads as line features. Inherited from TerrainMobilityOperator |
| RoadMaxVehicleHeight | Gets or sets an attribute variable giving the maximal vehicle height for a road feature. Inherited from TerrainMobilityOperator |
| RoadMaxVehicleLength | Gets or sets an attribute variable giving the maximal vehicle length for a road feature. Inherited from TerrainMobilityOperator |
| RoadMaxVehicleWeight | Gets or sets an attribute variable giving the maximal vehicle weight for a road feature. Inherited from TerrainMobilityOperator |
| RoadMaxVehicleWidth | Gets or sets an attribute variable giving the maximal vehicle width for a road feature. Inherited from TerrainMobilityOperator |
| RoadType | Gets or sets a attribute variable giving the type of a road feature, telling how it is connected to the terrain. |
| RouteZMeaning | Gets or sets a value that specifies the meaning of z coordinates in the output route: either elevation or local travel time. |
| SearchMargin | Gets or sets an attribute variable giving a margin in meters around the waypoints feature, inside which all search is done. |
| SnowDepth | Gets or sets an attribute variable giving the assumed snow depth in meters. Inherited from TerrainMobilityOperator |
| SurfaceStructureInput | Gets or sets an operator that gives surface structure classes (roughness) as a raster. Inherited from TerrainMobilityOperator |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| VehicleType | Gets or sets an attribute variable giving the vehicle type to use in the analysis. Inherited from TerrainMobilityOperator |
| WaypointsInput | Gets or sets an operator that gives a waypoint sequence in the form of 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 |