VerticalClearanceOperator Class
Computes the clearance of a flight route above terrain or obstacles.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class VerticalClearanceOperator : OperatorRemarks
This operator takes a flight route from its RouteInput in the form of a line feature, where the z coordinate of each node gives the altitude above sea level. The input from RouteInput can also be a point feature, which is interpreted as an aircraft position. From its ElevationInput, the operator can take a terrain elevation raster, as well as points, lines and polygons that represent obstacles. The operator then computes the vertical clearances of the route (or aircraft) above the terrain and the obstacles, within a horizontal MaxDistance buffer zone. Some of the results are output in the form of a terrain clearance raster and newly generated terrain spot features, while other results are collected to become new attributes on obstacle features and route segments.
 |
On this page, near or nearby will stand for "closer than MaxDistance". Straight line segments of the route will be called legs.
Around a route waypoint with a course change, there are two areas that the operator regards as being near both the leg before and the leg after. One area is a circle sector outside the turn; the other is a quadrangle inside the turn:
 |
For each leg, its clearance above a nearby terrain spot or obstacle is based on the interpolated flight altitude at the point of the leg that is nearest the spot or obstacle.
You can use the output to decide whether the flight route is safe. However, the operator doesn't know about the required clearance, so you have to design the visualization to highlight computed clearances that are too low. The required clearance is usually higher for terrain than for obstacles, by a hundred meters, say, to account for buildings that are too low to be mandatory in obstacle databases.
The operator produces output of three kinds: terrain-based, obstacle-based, and route-based. You can filter away or ignore the kinds you do not need.
Terrain-based Output
 |
The terrain-based output is a raster with the same numeric format as the input elevation raster, containing the route clearance above each terrain cell near the route, and elsewhere the undefined value, which will be the largest representable number in the raster format.
Also, for each leg, one or two critical terrain spots near the leg are output as point features. "Critical" means having either the highest elevation or the lowest leg clearance, or both. The critical point features will have the same attributes as the route feature, plus the following extra attributes:
vcopTerrainElevation, the terrain elevation.
vcopTerrainClearance, the leg-cell clearance for the relevant leg.
vcopLegIndex, an integer giving the index of the relevant leg in the route, starting from 0.
vcopIsLowestTerrainClearance, will be either True or not defined.
vcopIsHighestTerrainElevation, will be either True or not defined.
When the two critical terrain spots coincide for a leg, only one critical point feature will be output for this leg, and both the Boolean attributes will be True. On the other hand, a single terrain spot can be critical for two or more legs, in which case two or more point features will be output at the same geographic position (with different vcopLegIndex attributes, and possibly with different clearance attributes).
Sometimes, the attribute vcopTerrainClearance for a spot can be higher than the corresponding cell value in the terrain clearance raster. This is because the attribute gives the terrain spot clearance for a particular nearby leg, while each raster cell gives the lowest clearance for all nearby route legs. The terrain spot may be the worst one near leg number 3, say, with a clearance of 300 m, but the same position could also have a clearance of only 200 m to leg number 7, so the raster cell would contain 200, while the worst terrain spot near leg number 7 could appear somewhere else.
Missing elevation data
Undefined cell values in the terrain elevation raster will be interpreted as if they contained the value 100 000, regardless of the concrete representation of the undefined value. This should ensure that the undefined areas appear as dangerous.
In areas where there is no terrain elevation raster at all from ElevationInput, there will be no terrain clearance raster in the output and no terrain spot features, although flying over unknown terrain is of course dangerous. So if the elevation raster does not completely cover the area near a leg, then the output leg will get an attribute for leg-terrain clearance that will be ‑100 000, and this can be used to highlight the danger, since a safe value must be positive. This leg attribute is called vcopLowestTerrainClearance; see the section Route-based Output below.
Obstacle-based Output
 |
The obstacle-based output consists of clones of the obstacle features that are near the route; obstacles farther away will not be output. The output obstacles keep their original attributes, and also get copies of the attributes of the route feature, except those that would conflict with some original attribute. The output obstacles also get the following attributes:
vcopIsObstacle, will be True.
vcopClearanceAboveObstacle, the lowest route altitude near the obstacle minus the elevation at the top of the obstacle.
vcopClearanceBelowObstacle, the elevation at the bottom of the obstacle minus the highest route altitude near the obstacle. This is useful for an airborne obstacle that you can try to fly under - this would usually be a prohibited airspace rather than a physical obstacle.
vcopObstacleClearance, the lowest vertical clearance between route and obstacle, whether above or below the obstacle.
For a point obstacle or a line obstacle, the last attribute will always be the maximum of the previous two. For a polygon obstacle, it will usually be the maximum, but it can sometimes be larger. This can occur when the polygon obstacle represents a prohibited airspace where the upper and lower vertical limits are both positive. Then, for example, the beginning of route can cross safely above the airspace, the middle of the route can be far from the airspace, and the end of the route can cross safely below the airspace. So the route and the airspace would always be separated by a positive vertical clearance wherever they are near each other, so vcopObstacleClearance would be positive. However, the vcopClearanceAboveObstacle would be negative, since the route does not go consistently above the airspace, and the vcopClearanceBelowObstacle would also be negative, since the route does not go consistently below the airspace.
Route-based Output
 |
The route-based output consists of the route legs as separate line features, with copies of the route attributes, plus some extra attributes:
vcopIsLeg, will be True.
vcopLegIndex, an integer giving the index of the leg in the route, starting from 0.
vcopLowestTerrainClearance, lowest clearance of leg above nearby terrain. If there are areas near the leg that are not covered by the elevation raster, then the value will become ‑100 000, to signal danger. See also the paragraph Missing elevation data above.
vcopLowestObstacleClearance, lowest clearance of leg above or below nearby obstacles. If there are no obstacles nearby, the operator assumes that the available obstacle databases cover the area of interest, so this attribute will become 100 000, which should be safe, and will make it easier to write a Condition for leg danger (easier than if the attribute would be absent). In the screenshot above, a TextVisualizer.condition was used to avoid displaying such a value as a label (for the northmost leg).
vcopIsClippedLeg, a Bool that tells whether the leg extended outside a clipping rectangle whose boundary goes MaxDistance beyond the View area. If so, the operator would have used a clipped copy of the leg during analysis, and the previous attributes would be the lowest clearances of the clipped leg, not necessarily of the entire leg.
About leg clipping: If the leg clipping was never done, there could be performance problems when you zoom in much, since this could cause the elevation dataset to produce higher resolutions, which could contain too much data if they had to cover the entire route, instead of just the clipping rectangle. However, the leg clipping can only affect the leg feature attributes, not other results that are visible in the view area. In the sample configuration file, vertical_clearance_operator.px, the text in each leg feature label is placed in parentheses if the leg was clipped.
Finally, as a bonus, each route waypoint is also output as a separate point feature, with copies of the route attributes, plus some extra attributes:
vcopIsWaypoint, will be True.
vcopWaypointAltitude, a copy of the z coordinate, for easier display.
vcopLegIndex, an integer that gives the index of the leg after the waypoint, starting from 0. So the first waypoint gets the index 0, and the last one gets an index for which there is no corresponding leg.
Output based on a single-point route
A special case of route-based output occurs when the RouteInput gives a point instead of a line. The point will be interpreted as an aircraft position, and clearances to terrain and obstacles will be computed within a circle with MaxDistance radius. One could say that the aircraft position is used both as a route waypoint and as a degenerate leg that is infinitely short. So the terrain-based and the obstacle-based output will be similar as for a route line. However, the route-based output will in this case just be a clone of the aircraft feature, with these extra attributes:
vcopIsWaypoint, will be True.
vcopWaypointAltitude, a copy of the z coordinate, for easier display.
vcopLegIndex, will be 0.
vcopIsLeg, will also be True.
vcopLowestTerrainClearance, defined in a analogous way to the same attribute for a leg, see above.
vcopLowestObstacleClearance, likewise analogous, see above.
Common Vertical Unit
The operator is neutral about the vertical units, since all vertical distances are compared to each other, not to any horizontal ones. So there is no way, and no need, to tell the operator about the vertical unit. The operator simply assumes that all input features have the same vertical unit, which will also be used for the output features.
To ensure that input features use a common vertical unit, you may need to preprocess them with a UnitConversionOperator, which can convert both attributes and z coordinates, but not raster cells. The input elevation raster could instead be preprocessed with a RasterConversionOperator to convert its vertical unit, but this would be less efficient. So it would be best to let your elevation raster decide the vertical unit that shall be used by the VerticalClearanceOperator, and use a UnitConversionOperator for the vector data input. If you want to, you can then postprocess the vector data output with a UnitConversionOperator, but for the raster output, it is better to adapt the RasterVisualizer to the raster vertical unit, rather than using a RasterConversionOperator to change the unit.
If different input features were to have different vertical units, the mistake would not be detected by the operator.
Horizontal Coordinates
The operator expects every elevation raster from ElevationInput to have the same Crs as the route from RouteInput, and throws an exception otherwise. The route legs will be interpreted as straight lines in this Crs. Vector data from ElevationInput (obstacles) are allowed to have a different Crs, and will then be reprojected automatically to the route/raster Crs.
If your route is expressed in a different Crs than your elevation raster, you should usually insert a ProjectOperator in the operator chain for the RouteInput, to reproject the route explicitly to the Crs of the elevation raster. Reprojecting the raster instead would be less efficient and less accurate. The reason why the VerticalClearanceOperator will not reproject the route automatically, is that the default reprojection of a line would just reproject the waypoints one by one, and this might not be accurate enough if the route legs are long. If they are long, it is important to think about whether they should be
interpreted as straight lines in their original Crs, in which case you may need a ProjectOperator.ProjectParameters with edgesToSegmentize = All,
or interpreted as great-circle arcs or as rhumb lines, in which case you may need to use a GreatCircleOperator or call the Crs.Route method before the reprojection,
or interpreted as something else...
Since the VerticalClearanceOperator cannot know which interpretation is intended, it refuses to take responsibility for the route reprojection.
As mentioned earlier, the operator will reproject obstacle features if necessary, because they are expected to be small - but if they are large airspace polygons with long straight edges, you should consider, again, whether point-by-point reprojection is accurate enough.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
VerticalClearanceOperator
Platforms
Windows, Linux, Android
VerticalClearanceOperator Members
The VerticalClearanceOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| VerticalClearanceOperator | Initializes a new instance of the VerticalClearanceOperator class. |
Properties
| Name | Description |
|---|---|
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
| ElevationInput | Gets or sets the input operator that gives a terrain elevation raster, and/or obstacles as points, lines or polygons. |
| IsDisposed | Gets a value that tells whether the current VerticalClearanceOperator 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 the maximal distance from the route, at which terrain rasters and obstacles can generate output. |
| MaxObstacleElevation | Gets or sets the elevation, above sea level, at the top of each obstacle from elevationInput. |
| MinObstacleElevation | Gets or sets the elevation, above sea level, at the bottom of each obstacle from elevationInput. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current VerticalClearanceOperator represents. Inherited from EngineObject |
| RouteInput | Gets or sets an operator that gives one or more route lines, or one or more aircraft positions. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
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 |