TerrainAccessOperator Class
Gives travel times (isochrones) for a terrain vehicle to all nearby points (on-road and off-road) from a start position.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class TerrainAccessOperator : 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 to pass through. The operator then uses a specified VehicleType to calculate the accessibility, or travel time, to each nearby point from a starting position. There is a sample map configuration, terrain_access_operator.px, that you can try in Carmenta Explorer.
The starting position is usually a single point feature, but it can also be single line feature, or the entire road network. The kind of starting position is controlled via the PositionInput.
If the terrain access operator has a PositionInput, this input operator should give a starting point or a starting line. There will be raster output giving the travel times to nearby off-road points, as well as line output giving the travel times to nearby on-road points. There will also be a rectangular output polygon that covers the area that has been analyzed. For more details about the output features, see the section "Accessibility from a starting point", below.
Or if the PositionInput is null, the entire road network from RoadInput will be used as a set of starting lines. There will only be raster output for travel times to off-road points, since the travel time to any on-road point would be zero by definition.
Performance
The operator can be slow. The simplest way to improve performance is to use lower values for MaxTravelTime and MaxDistance and a coarser DesiredResolution, although this can affect the quality of the results.
Some kind of layer caching should be used: a dynamic OrdinaryLayer.CacheMode (preferably DynamicAsync) when the PositionInput operator exists, and a TileLayer otherwise, possibly with a larger value of TileLayer.TileSize.
If the ordinary layer uses a dynamic cache mode, it is the MemoryDataSet that gives features to the PositionInput 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 to handle 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 TerrainAccessOperator in Carmenta Explorer using both a dynamic cache mode and editable restricted areas – that is why the sample configuration does not use layer caching.
Usage
Before we look at screenshots from the operator, we present a background map:
 |
The background shows two alternative starting features that could come from PositionInput: an off-road point feature (triangle), as well as a line feature (purple line) that is a feasible vehicle route.
Accessibility from a starting point
Using only the point feature above as the start position, and an amphibious vehicle type, we can get output that can be visualized like this (the blue shorelines of the background map have been rendered last):
 |
Output for terrain accessibility
For accessibility in terrain, we get an accessibility raster that contains travel times in seconds. The defined values in the raster will go from zero up to just a little bit more than the MaxTravelTime, which was 1800 seconds in the screenshot. A raster value that is Undefined could mean either that the point is completely inaccessible, or just that more travel time is needed.
A plain RasterVisualizer would just give colors, but to make the screenshot, we also used an IsolineOperator so that a TextVisualizer could create the smaller italic labels along the isolines (isochrones). The level distance of the isoline operator was 300 seconds, and to get a label expressed in minutes, the value attribute of each isoline had to be divided by 60 in a text expression in the text visualizer.
The accessibility raster will usually contain signed 16-bit integers, with the highest possible value, 32 767, representing Undefined. In the unlikely case that the MaxTravelTime is greater than 30 000 seconds (8 hours 20 minutes), the raster will instead contain signed 32-bit integers, again with the highest possible value, 2 147 483 647, representing Undefined.
Output for road accessibility
For accessibility on roads, we get short road pieces that have a travel time attribute
taopTimeSeconds
giving the travel time in seconds to the most accessible end of the road piece. In the screenshot above, we have displayed the raster and the road pieces using the same color scheme, using the taopTimeSeconds attribute to control the LineVisualizer.color. The line widths for the colored roads are designed to be the same as for the white roads of the background map, and the wider black background lines (visible as black road edges) are redrawn by the accessibility layer using the same black line visualizer as the background map. (To see the details, open terrain_access_operator.px in Carmenta Studio.)
The output road pieces are shorter than the input roads, since the input roads are chopped into pieces at each interior point whose accessibility is a multiple of the road time resolution, by default 60 seconds. They are also chopped at each interior point where the accessibility reaches a local maximum or minimum along the road. (The road time resolution can be controlled by letting the application set a starting feature attribute named roadTimeResolution, which should be a value in seconds that is a divisor of 60.)
The screenshot complements the road colors with big labels that show road accessibility in whole minutes. To display such labels, one could have used the taopTimeSeconds attribute again, by formatting it as minutes via a text expression, but for convenience there is another road piece attribute that can be used directly: the attribute
taopTimeWholeMinutes
gives the travel time in minutes to a road piece, provided the time can be expressed as whole minutes – otherwise the attribute will be absent. The node order of each road piece will be reversed, if necessary, to make the most accessible node come first; therefore, the TextVisualizer must have at = 0 and repeat = Node, which will place the label at the node with index 0.
There will also be other attributes on the output road pieces. Each will get the attributes of its original road feature, as well as the attributes of the starting feature, and new attributes created by the operator, namely
Attribute name | Type | Description |
|---|---|---|
taopTimeSeconds | Double | See above. |
taopTimeWholeMinutes | Integer | See above. |
taopRoadClass | Integer | See RoadClass. |
taopRoadDirectionality | One of the atoms twoWay, oneWay and oneWayReversed, analogous to the possible enumeration values for RoadDirectionality. For a one-way road, this attribute value is based on the line direction of the output road piece, which may differ from the line direction of the original road feature. Note that if these atom constants are used in an Expression, they should be prefixed by a hash character, for example taopRoadDirectionality != #twoWay. | |
taopRoadSpeed | Double | The assumed vehicle speed on this road in km/h, based on the VehicleType and on the RoadClass and SnowDepth for the road. |
taopRoadSnowDepth | Double | The assumed snow depth in meters on this road, see SnowDepth. |
taopRoadType | One of the atoms roadWithTerrainAccess, roadWithoutTerrainAccess, bridge, tunnel and ferryRoute, analogous to the possible enumeration values for RoadType. Note that if these atom constants are used in an Expression, they should be prefixed by a hash character, for example taopRoadType != #ferryRoute. |
Output giving the search area
Finally, the operator will create a special output feature (not used in the screenshot): a rectangular polygon that covers the area that has been analyzed. The size of this area can be controlled in two ways, by the properties MaxTravelTime: the maximal interesting travel time from the start, and MaxDistance: the max interesting straight distance from the start. The polygon will have copies of the attributes of the feature from PositionInput, and also two special attributes:
Attribute name | Type | Description |
|---|---|---|
taopConstrainedByMaxTravelTime | Bool | If true, the analysis stopped searching beyond a point with the maximal travel time (at least once). |
taopConstrainedByMaxDistance | Bool | If true, the analysis reached the edge of the coverage polygon (at least once). |
If both attributes are false, the results cannot be improved by a longer MaxTravelTime or MaxDistance. The reason must be physical obstacles – the start position must be in or surrounded by no-go terrain and/or restricted areas.
If the analysis was constrained by the max travel time but not by the max distance, then a longer MaxTravelTime will not decrease the calculated travel times that are well-defined, but it could turn some Undefined travel times into well-defined ones. (In the screenshot above, this would happen in the northeast corner, where the vehicle can just continue northward.)
If the analysis was constrained by the max distance, then a longer MaxDistance may decrease also some well-defined travel times, since they may benefit from a detour on a fast road that goes partially outside the original analysis area.
Accessibility from a starting line
If we use a starting line instead of a point, the output will be similar, but the travel time to each surrounding point is calculated from the most suitable node of the starting line. The result is analogous to using some node of the line as a single starting point, while regarding the line as a superhighway giving infinite travel speed. Here is a screenshot using the purple starting line in our original background map:
 |
This purple line is a vehicle route that was calculated by TerrainRouteOperator. In the screenshot above, one can see that some parts of the route are inflexible in that the vehicle cannot deviate from a road, whereas the last third of the route is very flexible since it goes through easy terrain.
For the accessibility labels on roads, we used a text visualizer similar to the one in the previous example. However, here we added the visualizer condition
taopTimeWholeMinutes > 0
Without this condition, we would get a lot of zero labels where the route line follows a road, which would be too cluttered.
In general, intermediate points on the starting line edges between the explicit nodes are not used as starting points for the accessibility calculation, but one could densify the line feature; see RoadType for a tip on how to densify lines. On the other hand, when the starting line is a route from TerrainRouteOperator, its node density should usually be good enough already.
Accessibility from the road network
When the PositionInput is null, the entire road network from RoadInput will be used as a set of starting lines. The output feature will be a raster with the terrain accessibility from the roads, but there will be no output road pieces and no coverage polygon.
 |
Note that if a large area is analyzed in this mode, the relative values of accessibilities for places far apart can differ from an intuitive notion of accessibility. This is because all roads have equal status as starting lines, even if they are on an isolated island that is reachable only by ferry.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
TerrainMobilityOperator
TerrainAccessOperator
Platforms
Windows, Linux, Android
See Also
Reference
Operators Module
RoadDirectionality
RoadType
TerrainSpeedOperator
TerrainRouteOperator
TerrainSpeed
TerrainVehicleType
Terrain Vehicle Analysis
TerrainAccessOperator Members
The TerrainAccessOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| TerrainAccessOperator | 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 TerrainAccessOperator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| MaxDistance | Gets or sets an attribute variable giving the longest interesting distance from a starting feature, in meters. |
| MaxTravelTime | Gets or sets an attribute variable giving the longest interesting travel time from a starting feature, in seconds. |
| 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 TerrainAccessOperator represents. Inherited from EngineObject |
| PositionInput | Gets or sets an operator that gives a start position as a point or line feature. |
| RestrictedAreaInput | Gets or sets an operator that gives restricted areas that normally cannot be passed. Inherited from TerrainMobilityOperator |
| 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. |
| 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 |
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 |