ICustomPropagation.Propagate Method
Given a ray from the current observer, characterized by a relative bearing and a terrain profile, returns the propagated values at requested indices.
Propagate(System.Double relativeBearing, PropagationProfilePointCollection profile, IntCollection requestedIndices)
Given a ray from the current observer, characterized by a relative bearing and a terrain profile, returns the propagated values at requested indices.Syntax
public DoubleCollection Propagate (
System.Double relativeBearing,
PropagationProfilePointCollection profile,
IntCollection requestedIndices
)Parameters
The relative bearing of the current ray, in degrees clockwise from the main bearing given by VisibilityOperator.PictureDirection. Will be in the range from −180° to +180°.
A terrain profile along the current ray that, for a set of distances from the observer, gives the corresponding ground elevations and optionally tree heights and auxiliary values.
A list giving the indices of the terrain profile that need a propagated value.
Return Value
The propagated values at the requested indices.
Remarks
Let us look at an example:
 |
In this example, the relative bearing for a ray is 45° clockwise from the pictureDirection. This parameter lets you model an observer whose sensitivity varies with direction, but it can be ignored if the observer has constant sensitivity in all directions. And if an observer has constant sensitivity within a certain sector and no sensitivity elsewhere, it is easier to control the sector via the VisibilityOperator.PictureDirection and VisibilityOperator.PictureWidth; see also VisibilityOperator.DistanceVariation.
The example also shows a profile that is a collection of seven propagation profile points, indexed from 0 to 6. They describe a vertical terrain profile along the ray, where each horizontal distance from the observer is associated with a ground elevation above sea level originating in the VisibilityOperator.ElevationInput, a tree height above ground originating in the optional VisibilityOperator.TreeHeightInput, and an auxiliary value originating in the optional LineOfSightOperator.AuxiliaryRasterInput. The profile points are not equidistant in this example: see NeedsEquidistantProfilePoints.
The third parameter is the collection of requested indices, which can improve performance since the calling operator will usually not need propagated values for each entry of the profile. A TargetLineOfSightOperator will only request the propagated value for the last entry of the profile. And a LineOfSightOperator will only request propagated values for a subset of the profile entries, because near the observer several rays may pass through the same output raster cell, and only the ray that passes closest to the cell center will fill the cell. To be clear, the Propagate method will normally use all the given profile entries to generate its results, but results are needed only for the distances corresponding to the requested indices. In this example, propagated values are requested for the indices 3, 5 and 6, so the output is expected to be a collection of three values.
The calling operator will throw an exception if the output has more values than requested, but fewer values are allowed. See the section "Missing output values" further down.
Undefined input values
The input profile to Propagate may contain values that at least originally were undefined: the ground elevations, tree heights and auxiliary values come from raster input to the calling operator, and the rasters may not cover the whole requested area, or they may contain some cells with their own Undefined value, or some rasters may not even be requested at all, since both VisibilityOperator.TreeHeightInput and LineOfSightOperator.AuxiliaryRasterInput are optional. For raster values that were originally undefined, their representation in the input profile will depend on their kind and on LineOfSightOperator.UndefinedElevationInterpretation:
undefinedElevationInterpretation | Ground elevation | Tree height | Auxiliary value |
|---|---|---|---|
NegativeElevation | −500 | 0 | −DBL_MAX |
ZeroElevation | 0 | 0 | −DBL_MAX |
UnknownElevation | −DBL_MAX | −DBL_MAX | −DBL_MAX |
Note that a TargetLineOfSightOperator supports only ZeroElevation.
Note also that the UnknownElevation will not automatically make custom-propagated values beyond an undefined elevation or tree height be the special value −32 768 that can represent uncertainty, as with standard line-of-sight propagation. It is possible to get that effect, but the custom propagation code must explicitly fill the rest of its output with −32 768 until it has as many entries as the requested indices. See also the LineOfSightOperator.UndefinedElevationInterpretation.
The idea behind the setting ZeroElevation is that it can be convenient if the custom code developer can forget about undefined elevations and tree heights and just have them served as zero values. The idea behind NegativeElevation is similar, but assumes that the unrealistic elevation of −500 m, when taken at face value, will produce reasonable visualizations that usually will indicate that something is amiss. But this convenience is not available for auxiliary values: in general, they can be of any dimension and unit, so we cannot be confident that a zero value would have a neutral effect. Finally, the idea behind UnknownElevation is of course that "Absence of Evidence does not mean Evidence of Absence": in other words, since missing data can be dangerous, there should be a way for the calling operator to tell the Propagate method about them.
The custom code should be careful with profile entries containing the lowest finite Double, since the literal value is on the edge of the finite numbers and can cause surprising results if used in ordinary calculations.
And there is one situation where the calling operator will internally assume that undefined tree heights are zero, even if they have been represented as the lowest finite Double in the profile. This situation occurs when the custom propagation says that its OutputType represents heights above treetops, and the calling operator needs to convert them to heights above sea level. Such a conversion from heights above treetops will always be necessary for a TargetLineOfSightOperator and an AirspaceCoverageOperator, and also for a LineOfSightOperator if it has been configured to produce volumetric viewsheds. The calling operator has no better options in this situation, but its behavior is still questionable, since the operator cannot tell whether the custom code has treated the undefined tree heights in some unusual way (for example, it could have treated them as 100 meters for good measure). So, if the custom code treats undefined tree heights as a non-zero value, it should not use heights above treetops as its OutputType.
Missing output values
As mentioned above, the output collection may have fewer entries than requested. The calling operator will handle such a situation in slightly different ways, depending on its type.
Since a TargetLineOfSightOperator will request a value only for the last profile index, it can get fewer results than requested only if it gets an empty collection. In that case the operator will ignore it, so no attributes will be added to the output target feature, and no line feature will be generated from the observer to the target – just as if the target had been farther than VisibilityOperator.MaxDistance from the observer.
A LineOfSightOperator will usually request several values, and if it gets a collection with fewer entries, it will assume that it is the final entries that are missing. Since the corresponding raster cells must be filled with something, they will be filled with the special value that the output raster will contain beyond the VisibilityOperator.MaxDistance, which happens to be 15 000 000.0 (see next section). In other words, by producing fewer output values than requested, the Propagate method can indicate that the sensor range along some profile is shorter than the MaxDistance. On the other hand, the method has no way of indicating that the the range is longer than the MaxDistance, since the distance covered by the input profile is limited by the MaxDistance, and producing too many output values will throw an exception anyway.
Special raster values and visualization
When a LineOfSightOperator uses a custom propagation, its output rasters will use the Float format and can contain two special values:
The value 16 000 000.0 is the official Undefined value of the rasters, and it will appear when multiple pyramidal resolutions are used (see VisibilityOperator.FirstResolutionChange), but only in the big central hole of a large coarse raster that will be covered by a smaller finer raster.
The value 15 000 000.0 will appear beyond the VisibilityOperator.MaxDistance, or more generally outside the annulus sector defined by VisibilityOperator.MaxDistance, LineOfSightOperator.MinDistance, VisibilityOperator.PictureDirection, VisibilityOperator.PictureWidth, and VisibilityOperator.DistanceVariation.
The basic documentation of these values appears under LineOfSightOperator.OutputMinVisibilityHeights.
Since the value 16 000 000.0 has an official status of being Undefined, it will not be colored even if you use a color table that assigns a color to it: the undefined status will override the color table in such a case. But the other special value, 15 000 000.0, has no such protection, so your color table should be designed to give it a fully transparent color (since it usually makes no sense to color areas beyond the MaxDistance).
In many cases, it is natural to give a fully transparent color to any LOS raster values that are large. For example, when the LOS raster values represent minimal visibility height above ground, and you want to display just the ground that can be seen, you would use a color table where 0.0 gets a color and larger values get a fully transparent color, for example:
 |
Since there is a threshold, 0.1 meters in this example, above which all values appear as fully transparent, the special value 15 000 000.0 becomes fully transparent with no extra trouble (provided the threshold is less than 15 million).
When custom propagation is used, the LOS raster values do not necessarily represent heights, but it can still be natural to display all values above some threshold as fully transparent, for example if the values indicate path loss in decibel. But there are counterexamples: the custom propagation sample calculates vision probability in percent from 0 to 100, so within the MaxDistance it is natural to display zero values as fully transparent, while the raster values beyond the MaxDistance will still be 15 000 000.0, and to make them fully transparent, too, your color table must be designed accordingly; for example:
 |
Of course, in this situation it would have been nicer if one could have specified that all raster values beyond the MaxDistance shall become zero, but the API does not allow that. When necessary, one can instead use a RasterReclassificationOperator to reclassify 15 000 000.0 to some other value; indeed, this is done in the configuration file for the custom propagation sample in order to generate an isoline boundary for the custom viewshed.
Finally, the Propagate method should avoid producing the special values 15 million and 16 million as regular values by coincidence, but that will seldom be a problem in practice.
When the output values represent heights in meters, the special values should be higher than any realistic output values.
When the output values represent something else (probability, path loss, signal strength, etc.), it is wise to choose a unit that makes all realistic values less than the special values.
If you want to be extra careful, your custom code can check if a calculated value happens to be within 0.5 from a special value and in that case nudge it down to 14 999 999.0 or 15 999 999.0 (the tolerance of 0.5 would be needed since the Double results will be rounded to Float when stored in the LOS raster, and the Float resolution is 1.0 near the special values).
Platforms
Windows, Linux, Android