TargetLineOfSightOperator Class
Computes whether there are free lines of sight between observers and targets.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class TargetLineOfSightOperator : LineOfSightOperatorRemarks
There is an introductory Visibility Guide, which you should read in parallel with this reference manual.
As input, the TargetLineOfSightOperator takes a set of point observers from ObserverInput, a set of point targets from TargetInput, 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.
The operator can work in two modes: binary or continuous.
In the binary mode, the operator calculates whether or not there is a free line-of-sight between each pair of observer and target. This mode is active if the standard line-of-sight propagation model is used, or if the operator uses a CustomPropagation model whose output type is a kind of height.
In the continuous mode, the operator calculates a real number – a propagation value – between each pair of observer and target. This mode is active if the operator uses a CustomPropagation model whose output type is Other.
Binary mode
The output is the stream of targets with new attributes, telling which observers can see it. Optionally, the operator can generate a line feature for each free line of sight from an observer to a target, or a line feature for each interrupted line of sight from an observer to the first obstructing terrain; see OutputSightLines.
If the operator uses a CustomPropagation model whose output type is a kind of height, then the height values are interpreted as defining the bottom surface of the viewshed volume, while the top surface is generated by the standard propagation model, so the operator can figure out whether or not a target is inside the viewshed in the usual way. However, interrupted lines of sight are not supported by a CustomPropagation.
 |
Each output target gets several new attributes. As an example, let us say that two observers come from ObserverInput, one with an attribute Name: "Argus", the other with an attribute Name: "Monitor". We let the ObserverName property be an IndirectAttributeVariable<System.String> that just looks up the Name attribute. Then, each target can get the following new attributes:
Attribute | Type | Meaning |
|---|---|---|
seeingObservers | string | The names of all observers that can see the target, separated by the Separator, for example, "Argus;Monitor". |
visibleBy | integer | The total number of observers that can see the target. |
visibleByArgus | integer | The number of observers named "Argus" that can see the target (but only if non-zero). |
visibleByMonitor | integer | The number of observers named "Monitor" that can see the target (but only if non-zero). |
The first two attributes (seeingObservers and visibleBy) will always be added to the target, even if they become the empty string or zero. (If a target already has an attribute called seeingObservers or visibleBy when it comes to a TargetLineOfSightOperator, then the operator will ignore and overwrite the previous value.) Each of the other attributes (visibleByArgus, visibleByMonitor, etc.) is added only if it is non-zero.
To learn which observers can see a given target, it is easiest to let the application parse the value of seeingObservers.
To learn which targets a given observer can see, it may be best to let the application create a condition like visibleByArgus > 0 and use it in a special SymbolVisualizer for targets, or use it in an FilterOperator.
The ground elevation outside available data is assumed to be zero. If the input elevation raster contains cells with the Raster.UndefinedValue, the elevations in these cells are also assumed to be zero. However, a special case occurs when an observer is outside the available elevation data: then it will not affect the output. Therefore, we recommend using a global low-resolution elevation dataset, like GMTED2010, to complement any high-resolution elevation dataset with limited extent; see Multiple Resolution.
Continuous mode
If a CustomPropagation model is used whose output type is not a kind of height but Other, for example representing path loss in decibel, then the operator cannot use the propagation values to divide the targets into seen and unseen. The only thing it can do is to pass the propagation values to the output.
The most useful kind of output feature will be straight lines between each pair of observer and target for which the propagation value is not the "no signal" value. Such lines are generated if OutputSightLines = Line and will have attributes containing the observer name, the target name and the propagation value; see SightLine for details. In the continuous mode, the only supported values of OutputSightLines are Line and None.
Another kind of output feature will be copies of the target features with extra attributes. If there is a single observer named "Argus", say, that gets a well-defined propagation value to some target, then the output target feature will get an attribute named propagationFromArgus with the value. (The prefix propagationFrom cannot be modified.) However, if there are several observers named "Argus", then all their propagation values to the same target will be summed and stored in the propagationFromArgus attribute for the target. The drawback is that summation of propagation values may not make much sense, so this output mechanism is mainly useful if you can use application logic to keep all observer names unique.
In addition, the output target feature will get the attribute seeingObservers with a similar meaning as in the binary mode. But in the continuous mode, the word "seeing" does not imply a free line of sight, only that the custom propagation value was well-defined rather than the "no signal" value.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
VisibilityOperator
LineOfSightOperator
TargetLineOfSightOperator
Platforms
Windows, Linux, Android
TargetLineOfSightOperator Members
The TargetLineOfSightOperator type has the following members.
Constructors
| Name | Description |
|---|---|
| TargetLineOfSightOperator | Initializes a new instance of the TargetLineOfSightOperator class. |
Properties
| Name | Description |
|---|---|
| AuxiliaryRasterInput | Gets or sets an input operator that provides additional raster data for CustomPropagation. Inherited from LineOfSightOperator |
| CarrierType | Gets or sets an enumeration value, telling if the observer is ground-based or airborne. Inherited from LineOfSightOperator |
| CustomPropagation | Gets or sets a custom propagation proxy object that refers to custom-written code for propagation. Inherited from LineOfSightOperator |
| 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. Inherited from LineOfSightOperator |
| IsDisposed | Gets a value that tells whether the current TargetLineOfSightOperator 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). Inherited from LineOfSightOperator |
| MaxUpDistance | Gets or sets the maximal straight-up range of the observer. Inherited from LineOfSightOperator |
| MinDistance | Gets or sets the minimal range of the observer. Inherited from LineOfSightOperator |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current TargetLineOfSightOperator 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. Inherited from LineOfSightOperator |
| ObserverName | Gets or sets an attribute variable that extracts the name of each observer. |
| OutputSightLines | Gets or sets a value, telling whether free and/or interrupted lines of sight shall be generated. |
| 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 |
| 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 |
| Separator | Gets or sets the separator between observer names in the value of the seeingObservers attribute, see TargetLineOfSightOperator. |
| TargetAttribute | Gets or sets the prefix used for the names of the new target attributes. |
| TargetInput | Gets or sets the input operator that gives point features representing targets. |
| TargetName | Gets or sets an attribute variable that extracts the name of each target. |
| 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. Inherited from LineOfSightOperator |
| 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 |
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 |