com.luciad.tea

Terrain Analysis EngineClass TLcdLOSCoverageFactory

java.lang.Object

com.luciad.tea.TLcdLOSCoverageFactory

public class TLcdLOSCoverageFactory
extends Object

Computes line-of-sight between a point and its surroundings and converts the results to either a raster or a set of polygon contours.

A TLcdLOSCoverageFactory is a factory which creates ILcdLOSCoverageMatrix objects representing the result of a line-of-sight computation around a point. These computations are based on propagation functions describing the visibility along an azimuth. The resulting matrices can then be converted into a raster or a list of polygons.

For example, to create a line-of-sight raster:

1. Choose or create a propagation function (ILcdLOSPropagationFunction) describing how the detection wave propagates (visual, radar).
2. Create a circular area to compute the line-of-sight for. An ILcdLOSCoverage describes both the outline of the area and the sampling inside the area.
3. Call createLOSCoverageMatrix to compute the line-of-sight according to the propagation function on the covered area. The result is returned as an ILcdLOSCoverageMatrix in the specified reference.
4. Convert the matrix into a raster, using createLOSCoverageRaster. This raster can be used to display the result of the line-of-sight computations in a view using a ILcdRasterPainter.

Constructor Summary

Constructors

Constructor and Description
TLcdLOSCoverageFactory() Defines a line-of-sight coverage factory.

Method Summary

Modifier and Type	Method and Description
void	addStatusListener(ILcdStatusListener aStatusListener) Starts notifying a listener with the progress of line-of-sight computations and result conversions.
ILcdValuedPolygon[]	createLOSCoverageContours(ILcdLOSCoverageMatrix aLOSCoverageMatrix, ILcdGeoReference aTargetReference, double[] aContourLevels) Deprecated. Use createLOSCoverageContours(ILcdLOSCoverageMatrix, com.luciad.reference.ILcdGeoReference, com.luciad.contour.TLcdComplexPolygonContourFinder.IntervalMode, double[], double[]) instead. This method relies on deprecated contour finding algorithms. The output of the new contour finding algorithms are much more practical to work with as they define complex polygons within an interval range, instead of simple polygons that represent contour edges. This method has been kept for compatibility reasons with LuciadMap
ILcdBounded[]	createLOSCoverageContours(ILcdLOSCoverageMatrix aLOSCoverageMatrix, ILcdGeoReference aTargetReference, TLcdComplexPolygonContourFinder.IntervalMode aIntervalMode, double[] aContourIntervalLevels, double[] aContourSpecialValues) Generates complex polygon contours from the given ILcdLOSCoverageMatrix using the target reference and the contour levels.
ILcdLOSCoverageMatrix	createLOSCoverageMatrix(ILcdLOSPropagationFunction aLOSPropagationFunction, ILcdLOSCoverage aLOSCoverage, ILcdGeoReference aTargetReference) Creates a ILcdLOSCoverageMatrix representing the result of line-of-sight computations on the given area aLOSCoverage using the propagation function aLOSPropagationFunction.
ILcdRaster	createLOSCoverageRaster(ILcdLOSCoverageMatrix aLOSCoverageMatrix, ILcdMatrixRasterValueMapper aMatrixRasterValueMapper, ILcdGeoReference aTargetReference, double aTargetPixelDensity, TLcdCoverageFillMode aFillMode) Creates an ILcdRaster from the ILcdLOSCoverageMatrix using the given target reference, pixel density and fill mode.
void	removeStatusListener(ILcdStatusListener aStatusListener) Terminates notifying a listener of the progress of line-of-sight computations and result conversions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TLcdLOSCoverageFactory

public TLcdLOSCoverageFactory()

Defines a line-of-sight coverage factory.

Method Detail

removeStatusListener

public void removeStatusListener(ILcdStatusListener aStatusListener)

Terminates notifying a listener of the progress of line-of-sight computations and result conversions.

Parameters:

aStatusListener - will no longer be notified of progress when running a line-of-sight computation or when converting a coverage matrix to either a raster or a set of polygon contours.

See Also:

addStatusListener(ILcdStatusListener)

addStatusListener

public void addStatusListener(ILcdStatusListener aStatusListener)

Starts notifying a listener with the progress of line-of-sight computations and result conversions.

Parameters:

aStatusListener - will be notified of progress when running a line-of-sight computation and when converting a coverage matrix to either a raster or a set of polygon contours.

See Also:

removeStatusListener(ILcdStatusListener)

createLOSCoverageMatrix

public ILcdLOSCoverageMatrix createLOSCoverageMatrix(ILcdLOSPropagationFunction aLOSPropagationFunction,
                                                     ILcdLOSCoverage aLOSCoverage,
                                                     ILcdGeoReference aTargetReference)

Creates a ILcdLOSCoverageMatrix representing the result of line-of-sight computations on the given area aLOSCoverage using the propagation function aLOSPropagationFunction.

The target reference aTargetReference defines the reference in which the coverage matrix will be defined. Currently, only geodetic target references are supported.

The coverage matrix contains coordinates that should be interpreted in the target reference. The points in the matrix cover the area of the line-of-sight coverage passed with intermediate steps as in the line-of-sight coverage.

Note that, when the current thread is interrupted, null is returned.

Parameters:

aLOSPropagationFunction - The propagation function to use for the computation.

aLOSCoverage - The covered area and the intermediate step sizes.

aTargetReference - The reference in which the result will be defined.

Returns:

a ILcdLOSCoverageMatrix representing the result of line-of-sight computations on the given area using the given propagation function.

Throws:

NullPointerException - when a null argument is found or when the propagation function was not set.

IllegalArgumentException - if the propagation function does not accept the parameter aLOSCoverage or when the target reference is not a geodetic reference.

createLOSCoverageRaster

public ILcdRaster createLOSCoverageRaster(ILcdLOSCoverageMatrix aLOSCoverageMatrix,
                                          ILcdMatrixRasterValueMapper aMatrixRasterValueMapper,
                                          ILcdGeoReference aTargetReference,
                                          double aTargetPixelDensity,
                                          TLcdCoverageFillMode aFillMode)

Creates an ILcdRaster from the ILcdLOSCoverageMatrix using the given target reference, pixel density and fill mode. The aTargetReference defines the reference in which the raster will be defined. Using the pixel density and the fill mode, the given line-of-sight coverage matrix is re-sampled into a rectangular coverage.

The target pixel density is the pixel density of the resulting raster. This is the average number of pixels in an area of 1 by 1 in model coordinates. Higher densities will lead to more detailed coverages of the area. Note that the result is bound by the density of the samples taken of the underlying terrain data (which depends on the radial and angular step sizes used in the line-of-sight coverage to create the coverage matrix). The size occupied in memory by the coverage will increase linearly with this density.

The fill mode aFillMode indicates how the raster should be filled. Possible choices are:

• maximum: the pixel value corresponds to the maximum value found in line-of-sight coverage matrix for that pixel.
• minimum: the pixel value corresponds to the minimum value found in line-of-sight coverage matrix for that pixel.
• nearest neighbor: the pixel value corresponds to the value computed nearest to the bottom left of the pixel location. This mode will ensure that the raster contains no holes.

The fill mode is combined with the given ILcdMatrixRasterValueMapper to map the matrix entry values onto raster pixel values. There are two possibilities. The first maps a matrix value to a raster value. This forward mapping is used with the minimum and the maximum fill mode. The method ILcdMatrixRasterValueMapper.mapMatrixValue will be used to retrieve the raster value. The second maps a raster pixel to a number of matrix entries and combines the corresponding matrix values to a raster value, ensuring that all raster pixels are filled with a value. This backwards mapping is used with the nearest neighbor fill mode. The interface method ILcdMatrixRasterValueMapper.combineMatrixValues is used with only one matrix value which corresponds to the matrix value of the point nearest to the raster pixel and only one weight value, which is 1.

Note that, when the current thread is interrupted, null is returned.

Parameters:

aLOSCoverageMatrix - The matrix to convert.

aMatrixRasterValueMapper - Mapper to map matrix values on raster values.

aTargetReference - The target reference in which the result will be defined.

aTargetPixelDensity - The pixel density of the resulting raster.

aFillMode - The fill mode indicating how the raster should be filled.

Returns:

a raster representation of the given coverage matrix.

Throws:

NullPointerException - when one of the arguments (aLOSCoverageMatrix, aMatrixRasterValueMapper, aTargetReference or aFillMode) is null.

IllegalArgumentException - when aTargetReference is a geocentric reference.

createLOSCoverageContours

public ILcdValuedPolygon[] createLOSCoverageContours(ILcdLOSCoverageMatrix aLOSCoverageMatrix,
                                                     ILcdGeoReference aTargetReference,
                                                     double[] aContourLevels)

Deprecated. Use createLOSCoverageContours(ILcdLOSCoverageMatrix, com.luciad.reference.ILcdGeoReference, com.luciad.contour.TLcdComplexPolygonContourFinder.IntervalMode, double[], double[]) instead. This method relies on deprecated contour finding algorithms. The output of the new contour finding algorithms are much more practical to work with as they define complex polygons within an interval range, instead of simple polygons that represent contour edges. This method has been kept for compatibility reasons with LuciadMap

Generates contour lines from the given ILcdLOSCoverageMatrix using the target reference and the contour levels. The contours are returned as a set of ILcdValuedPolygon objects. The target reference defines the reference in which the polygons will be defined.

The contour levels define the different heights on which the contours will be calculated. They should be ordered from low to high.

The edge of a polygon indicates a contour line of equal height. The orientation of the returned polygons should be interpreted as follows:

• CLOCKWISE: The area on just on the exterior of the polygon has a higher value than the interior.
• COUNTER-CLOCKWISE: The area just on the exterior of the polygon has a lower value than the interior.

Note that this orientation only says something about the immediate area surrounding the contour line, and not the entire area enclosed by the contour. For instance, it is possible to have a counter-clockwise oriented contour that contains other contours in its interior with lower values than itself.

Note that, when the current thread is interrupted, null is returned.

Parameters:

aLOSCoverageMatrix - The matrix to convert.

aTargetReference - The target reference in which the polygons are defined.

aContourLevels - The different levels to compute the contours on.

Returns:

a contour representation of the given coverage matrix.

Throws:

NullPointerException - when a null argument is found.

createLOSCoverageContours

public ILcdBounded[] createLOSCoverageContours(ILcdLOSCoverageMatrix aLOSCoverageMatrix,
                                               ILcdGeoReference aTargetReference,
                                               TLcdComplexPolygonContourFinder.IntervalMode aIntervalMode,
                                               double[] aContourIntervalLevels,
                                               double[] aContourSpecialValues)

Generates complex polygon contours from the given ILcdLOSCoverageMatrix using the target reference and the contour levels. The contours are returned as a set of TLcdIntervalContour and TLcdValuedContour objects, which are stored in an array of ILcdBounded, and which have a ILcdComplexPolygon as base shape. TLcdIntervalContour are used when the complex polygon defines an area between an interval of two values, that is when two numerical parameters are needed to describe the area, TLcdValuedContour are used when the complex polygon defines a special value area or when the interval mode is LOWER or HIGHER, that is, when one numerical parameter is needed. The target reference defines the reference in which the shapes will be defined.

The interval levels define the different heights on which the contours will be calculated. They should be ordered from low to high. The special values define the values which are not heights around which specific contours should be created.

Note that, when the current thread is interrupted, null is returned.

Parameters:

aLOSCoverageMatrix - The matrix to convert.

aTargetReference - The target reference in which the polygons are defined.

aIntervalMode - The interval mode to use by the contour finder. When INTERVAL is given, the contours for all levels will be disjoint, "donut-shaped" complex polygons. When LOWER or HIGHER is given, the complex polygons will overlap but may have less edges. When LOWER is used, the complex polygons need to be drawn in inverse order of return.

aContourIntervalLevels - Contour values for intervals

aContourSpecialValues - Contour values for special values

Returns:

a contour representation of the given coverage matrix.

Throws:

NullPointerException - when a null argument is found.

IllegalArgumentException - when a height level or special value is invalid.