LineOfSightOperator Class
Computes the viewshed (visible region) from one or more observers.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class LineOfSightOperator : VisibilityOperator
Remarks
There is an introductory Visibility Guide, which you should read in parallel with this reference manual, and also a Line of Sight Configuration Tutorial.
This operator is used to display what an observer can see: the viewshed of the observer.
Sometimes, you want to know what the observer can see of the ground: that is a viewshed surface (often called a 2D viewshed).
And sometimes, you want to know what the observer can see of the air: that is a viewshed volume (often called a 3D viewshed).
The operator can be used to generate and display both kinds of viewshed.
As input, the LineOfSightOperator takes a set of observers from ObserverInput, a numeric raster with ground elevations above sea level from ElevationInput, and optionally another numeric raster with treetop heights above ground from TreeHeightInput. If a CustomPropagation is used, the operator can also take a numeric raster from AuxiliaryRasterInput.
For each observer, the operator returns one or more features, depending on enabled output types. The default output type is minimum visibility height rasters, see OutputMinVisibilityHeights, which are normally used to display the viewshed surfaces, although some variations are possible. The other output types represent the viewshed volumes in two different ways:
using OutputVolumeMesh, we get mesh features suitable for 3D display with a GlobeView;
using OutputVolumeEncodingRaster, we get a special raster-based volume representation that can be sent to a VerticalProfileOperator or an IsolineOperator.
Each output feature will have the same attributes with the same values (except the geoType attribute), as the corresponding observer (point or line) from ObserverInput. There may also be some additional attributes added by the operator, documented under the various output types.
Observers are points or lines
A LineOfSightOperator can accept both points and lines from its ObserverInput. If it gets a line, it means that the observer is moving from the first to the second point of the line (other points ignored), and the output cells will contain the minimal height where an aircraft is visible from somewhere on the route. Remember that the PictureDirection is measured clockwise from north for a point observer, but clockwise from the course direction for a line observer. The operator silently ignores any line that has fewer than two points, or whose first and second points have equal x and y values.
Merging overlapping viewsheds
If many observers have viewsheds that overlap each other, it can be messy to display them all individually. The most versatile way to merge overlapping viewsheds is to use an AirspaceCoverageOperator instead, but see also Overlapping Viewsheds.
Observers outside elevation data
If an observer is outside the extent of the available elevation rasters, a LineOfSightOperator usually gives no result. But sometimes, the elevation rasters will be extended with a default cell value, so that the LineOfSightOperator gives a result (which cannot be trusted). This happens when
the values of MaxDistance and FirstResolutionChange cause the LineOfSightOperator to use just one resolution for elevation rasters,
and the elevation request, which covers the bounding rectangle of the circle determined by MaxDistance, overlaps the elevation rasters,
and the elevation rasters lack an specified undefined value.
So, if these conditions are satisfied, the MaxDistance can affect whether an observer outside the elevation rasters gives any result. Since this behavior can be confusing, it is best to use a global low-resolution elevation dataset, like GMTED2010, to complement any high-resolution elevation dataset with limited extent; see Multiple Resolution.
This operator uses the global cache to store its calculated output features, so it can often reuse a cached result feature instead of recomputing it. If possible, you should also let the viewshed layer use a dynamic OrdinaryLayer.CacheMode; it is normally possible but not if the layer uses a RasterMergeOperator to merge the default output (see Overlapping Viewsheds).
Example
// Create a simple LineOfSightOperator for a ground based radar system
public static LineOfSightOperator CreateSimpleLineOfSightOperator(
Operator elevationInput, Point sensorPositionWgs84LatLong)
{
// Create a new LineOfSightOperator
LineOfSightOperator newLineOfSightOperator = new LineOfSightOperator();
// Set the elevation input in the new LineOfSightOperator
newLineOfSightOperator.ElevationInput = elevationInput;
// Create a new MemoryDataSet for the observer feature
MemoryDataSet observerDataSet = new MemoryDataSet(Crs.Wgs84LongLat);
// Add the MemoryDataSet as ObserverInput to the new LineOfSightOperator
newLineOfSightOperator.ObserverInput = new ReadOperator(observerDataSet);
// Create a new point Feature at the given position
Feature observerFeature = new Feature(
new PointGeometry(sensorPositionWgs84LatLong), Crs.Wgs84LongLat);
// Add the observer feature to the MemoryDataSet
observerDataSet.Insert(observerFeature);
// Set the MaxDistance to 20km
newLineOfSightOperator.MaxDistance = 20000.0;
// Set the ObserverHeight to 50m
newLineOfSightOperator.SensorHeight = 50.0;
// Return the created LineOfSightOperator
return newLineOfSightOperator;
}
// Create a LineOfSightOperator looking forward and backward for a Airborne
// at the given position
public static LineOfSightOperator CreateAirborneLineOfSightOperator(
Operator elevationInput, Point sensorPositionWgs84LatLong)
{
// Create a new LineOfSightOperator
LineOfSightOperator newLineOfSightOperator = new LineOfSightOperator();
// Set the elevation input in the new LineOfSightOperator
newLineOfSightOperator.ElevationInput = elevationInput;
// Create a new MemoryDataSet for the observer feature
MemoryDataSet observerDataSet = new MemoryDataSet(Crs.Wgs84LongLat);
// Add the MemoryDataSet as ObserverInput to the new LineOfSightOperator
newLineOfSightOperator.ObserverInput = new ReadOperator(observerDataSet);
// Create a new point Feature at the given position
Feature observerFeature = new Feature(
new PointGeometry(sensorPositionWgs84LatLong), Crs.Wgs84LongLat);
// Add the observer feature to the MemoryDataSet
observerDataSet.Insert(observerFeature);
// Set the CarrierType to airborne
newLineOfSightOperator.CarrierType = CarrierType.Airborne;
// Set the DistanceVariation to PhasedArray
newLineOfSightOperator.DistanceVariation = DistanceVariation.PhasedArray;
// Set the MaxDistanceType to ThreeDimensional
newLineOfSightOperator.MaxDistanceType = DistanceType.ThreeDimensional;
// Set the PictureWidth to 120 degrees
newLineOfSightOperator.PictureWidth = 120.0;
// Set the PictureHeight to 40 degrees
newLineOfSightOperator.PictureHeight = 40.0;
// Set the PictureElevation to -45 degrees. This will define the pitch of the observer
newLineOfSightOperator.PictureElevation = -45.0;
// Set the PictureDirection to 90 degrees.
newLineOfSightOperator.PictureDirection = 90.0;
// Set SecondPictureBackwards to true. The observer looks also backwards
newLineOfSightOperator.SecondPictureBackwards = true;
// Set the ObserverHightType to AboveGround
newLineOfSightOperator.ObserverHeightType = HeightType.AboveGround;
// Set the MinVisibilityHeightType to AboveGround
newLineOfSightOperator.MinVisibilityHeightType = HeightType.AboveGround;
// Set the MaxDistance to 20km
newLineOfSightOperator.MaxDistance = 20000.0;
// Set the VerticalRotationAxis to false,
// then the globe axis is tilted so that the ray through the center of the
// sensor lobe goes through the globe equator, and the globe axis is in the
// same vertical plane as that ray.
newLineOfSightOperator.VerticalRotationAxis = false;
// Return the created LineOfSightOperator
return newLineOfSightOperator;
}
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
VisibilityOperator
LineOfSightOperator
AirspaceCoverageOperator
TargetLineOfSightOperator
Platforms
Windows, Linux, Android
LineOfSightOperator Members
The LineOfSightOperator type has the following members.
Constructors
Name | Description |
---|---|
LineOfSightOperator | Initializes a new instance of the LineOfSightOperator class. |
Properties
Name | Description |
---|---|
AuxiliaryRasterInput | Gets or sets an input operator that provides additional raster data for CustomPropagation. |
CarrierType | Gets or sets an enumeration value, telling if the observer is ground-based or airborne. |
CustomPropagation | Gets or sets a custom propagation proxy object that refers to custom-written code for propagation. |
Description | Gets or sets a short description of the operator. Inherited from Operator |
DesiredInputResolution | Gets or sets the desired resolution for the calculation nearest the observers, in meters. Inherited from VisibilityOperator |
DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
DistanceVariation | Gets or sets a value that tells how the range of the observer varies with the direction (Constant or PhasedArray). Inherited from VisibilityOperator |
ElevationInput | Gets or sets the operator that provides elevation data. Inherited from VisibilityOperator |
EnableEvents | Gets or sets a flag that determines whether the operator shall fire events for a progress bar. Inherited from VisibilityOperator |
FirstResolutionChange | Gets or sets a value, telling how far away from the observer that the highest resolution should be used. Inherited from VisibilityOperator |
InterpolatedCells | Gets or sets a value, telling how far away from the observer elevations should be interpolated. |
IsDisposed | Gets a value that tells whether the current LineOfSightOperator 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 range of the observer, in meters. Inherited from VisibilityOperator |
MaxDistanceType | Gets or sets the type of maximal distance (horizontal or three-dimensional). |
MaxUpDistance | Gets or sets the maximal straight-up range of the observer. |
MinDistance | Gets or sets the minimal range of the observer. |
MinVisibilityHeightType | Gets or sets the type of visibility heights in the output (above sea-level, ground or treetops). |
Name | Gets or sets the name of the operator. Inherited from Operator |
NativeHandle | Gets the native Carmenta Engine kernel object the current LineOfSightOperator represents. Inherited from EngineObject |
ObserverHeightType | Gets or sets the type of height used for an observer (above sea-level, ground or treetops). Inherited from VisibilityOperator |
ObserverInput | Gets or sets the input operator that gives features that represent observers. |
OutputMinVisibilityHeights | Gets or sets whether the operator shall output rasters containing in each cell the minimum height that is visible to the observer. |
OutputVolumeEncodingRaster | Gets or sets whether the operator should output volume-encoding rasters. |
OutputVolumeMesh | Gets or sets whether the operator should output mesh features that represent volumes. |
PictureDirection | Gets or sets the main direction of observation. Inherited from VisibilityOperator |
PictureElevation | Gets or sets the elevation angle of the observer. Inherited from VisibilityOperator |
PictureHeight | Gets or sets the height of the picture that the observer sees. Inherited from VisibilityOperator |
PictureWidth | Gets or sets the width of the picture that the observer sees. Inherited from VisibilityOperator |
Refraction | Gets or sets a value that models the effects of refraction in the atmosphere. Inherited from VisibilityOperator |
SampleInterval | Gets or sets the distance between sample points, when the observer feature is a line. |
SecondPictureBackwards | Gets or sets a flag, telling if the observer looks in two opposite directions at once. Inherited from VisibilityOperator |
SensorHeight | Gets or sets the sensor height. Inherited from VisibilityOperator |
TreeHeightInput | Gets or sets an input operator that provides tree heights above ground. Inherited from VisibilityOperator |
UndefinedElevationInterpretation | Gets or sets the interpretation of the undefined elevation. |
IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
VerticalRotationAxis | Gets or sets a flag that determines the exact shape of the rectangular cross-section of the lobe. Use True for a radar system with a vertical rotation axis; use False for a camera with fixed orientation. Inherited from VisibilityOperator |
VerticalUnit | Gets or sets the unit for elevations and vertical distances except maxUpDistance. Inherited from VisibilityOperator |
VolumeOutputResolutionFactor | Gets or sets a factor controlling the resolution of volume output (mesh or volume-encoding raster). |
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 |