com.luciad.tea.lightspeed.los

Terrain Analysis EngineClass TLspLOSCalculator

java.lang.Object

com.luciad.tea.lightspeed.los.TLspLOSCalculator

All Implemented Interfaces:

ILcdDisposable, AutoCloseable

public class TLspLOSCalculator
extends Object
implements ILcdDisposable

A calculator for LOS coverage matrices (ILcdLOSCoverageMatrix)

The propagation function used by this calculator will calculate the height needed (in the given target reference) for a point to be visible. These resulting elevations will be expressed in the given target reference, and the set altitude mode method. If a value could not be determined, because there was no elevation information, the value in the resulting coverage matrix will be LOS_UKNOWN_VALUE

As an example: Let's say the matrix returned by this calculator is set to ABOVE_ELLIPSOID (see setCoverageAltitudeMode. Also, let's assume that lon-lat coordinate (15.0, 22.0) is found to be 50 metres in the resulting LOS coverage matrix. This implies that any point higher than 50 metres (above ellipsoid) is visible for that specific point. All points lower than 50 metres, at lon-lat coordinate (15.0, 22.0), will not be visible.

This calculator samples radially outward from the center point (as defined in the supplied properties). The terrain is sampled for each azimuth from the start angle to the arc of the angle, with an interval defined by the angle step of the given LOS properties. A sample is taken for each distance step size that is within the given radius of the properties. These values need to be chosen carefully with respect to the quality of the terrain. Decreasing the step sizes and angle sizes will increase the amount of sample points taken, but also reduce performance.

Note: This class requires a working OpenCL device capable of OpenCL 1.0 or higher. If no OpenCL capable device is found at construction of this class, a runtime exception will be thrown. For double precision calculations, the cl_khr_fp64 extension is required. If this extension is not available, this Line-Of-Sight calculator will fall back to computations with floating point precision, which can cause decreased output accuracy, especially over large distances. If the cl_khr_fp64 extension is not supported, the LOS calculator will log a warning in the console.

For performance reasons it is better to use a single instance of this calculator in your application. This class will build some openCL kernels, which can produce some overhead at construction and destruction.

This calculator implements the ILcdDisposable interface. It is important to call the dispose method when you are no longer using an instance of this class, to avoid native memory problems. Note that calling dispose will make the results produced by this class invalid.

When performing LOS calculations on a dedicated thread, it is possible to cancel the calculations using thread interruption. In this scenario, the LOS coverage matrix will not be written to. It is up to the application to ensure that it does not try to access the output of an interrupted calculation, as doing so will result in the ILcdLOSCoverageMatrix throwing an IllegalStateException.

Since:

2012.0

Constructor Summary

Constructors

Constructor and Description
TLspLOSCalculator() Creates a new TLspLOSCalculator instance.

Method Summary

Modifier and Type	Method and Description
ILcdLOSCoverageMatrix	calculateLOS(TLspLOSProperties aProperties, ILcdAltitudeProvider aAltitudeProvider, ILcdGeoReference aTargetReference) Performs Line-Of-Sight calculations based on the given properties.
void	dispose() Disposes of this object and allows it to release any system resources that it is holding.
void	disposeLOSCalculation(ILcdLOSCoverageMatrix aLOSCoverageMatrix) Method that allows the LOS calculator to clean up any references the LOS coverage matrix.
TLcdCoverageAltitudeMode	getCoverageAltitudeMode() Returns the altitude mode in which this LOS calculator's results are defined.
void	setCoverageAltitudeMode(TLcdCoverageAltitudeMode aAltitudeMode) Sets the altitude mode in which the results of this LOS calculator will be defined.
void	updateLOSCalculationSFCT(TLspLOSProperties aProperties, ILcdAltitudeProvider aAltitudeProvider, ILcdGeoReference aTargetReference, ILcdLOSCoverageMatrix aLOSCoverageMatrixSFCT) A side-effect method that updates the given LOS coverage matrix with the new properties given.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.util.ILcdDisposable

close

Constructor Detail

TLspLOSCalculator

public TLspLOSCalculator()

Creates a new TLspLOSCalculator instance. The object is initialized with default values. Calls to calculateLOS will generate valid ILcdLOSCoverageMatrix instances.

Throws:

RuntimeException - exception is thrown if no OpenCL capable device was found that supports at least OpenCL 1.0.

Method Detail

getCoverageAltitudeMode

public TLcdCoverageAltitudeMode getCoverageAltitudeMode()

Returns the altitude mode in which this LOS calculator's results are defined.

Returns:

the altitude mode that defines the results of this LOS calculator

setCoverageAltitudeMode

public void setCoverageAltitudeMode(TLcdCoverageAltitudeMode aAltitudeMode)

Sets the altitude mode in which the results of this LOS calculator will be defined. It may be one of the following values:

• TLcdCoverageAltitudeMode.ABOVE_ELLIPSOID
• TLcdCoverageAltitudeMode.ABOVE_GROUND_LEVEL
• TLcdCoverageAltitudeMode.ABOVE_GEOID

The default value of the coverage altitude mode is ABOVE_ELLIPSOID.

Note that the ABOVE_GEOID value assumes that geoid information is readily available in the target reference during calculation. If this is not the case, then the geoid will be set to 0 height above ellipsoid of the target reference, for the entire coverage.

Parameters:

aAltitudeMode - the altitude mode in which the results of this LOS calculator will be defined

calculateLOS

public ILcdLOSCoverageMatrix calculateLOS(TLspLOSProperties aProperties,
                                          ILcdAltitudeProvider aAltitudeProvider,
                                          ILcdGeoReference aTargetReference)

Performs Line-Of-Sight calculations based on the given properties.

Before performing the calculations, this method will first sample the terrain (using aAltitudeProvider) to retrieve the actual altitude values at the sample locations. Note that the sample locations are calculated based on the values in aProperties. When the sampling is done, the calculator will start computing the LOS values at the sample locations.

Note that LOS values refer to the minimum altitude something should have at a certain point in order to be visible from the center point of the LOS calculation area. How this altitude is interpreted (above ellipsoid, above geoid, etc.) depends on the altitude mode of the center point, which is defined by TLspLOSProperties.getCenterPointAltitudeMode() ()}.

Parameters:

aProperties - the properties that specify the LOS calculations

aAltitudeProvider - the altitude provider that is used for sampling the terrain

aTargetReference - the target reference in which the LOS values will be computed

Returns:

an ILcdLOSCoverageMatrix that contains the LOS values that are associated with the sampled terrain values

updateLOSCalculationSFCT

public void updateLOSCalculationSFCT(TLspLOSProperties aProperties,
                                     ILcdAltitudeProvider aAltitudeProvider,
                                     ILcdGeoReference aTargetReference,
                                     ILcdLOSCoverageMatrix aLOSCoverageMatrixSFCT)

A side-effect method that updates the given LOS coverage matrix with the new properties given. The given LOS coverage matrix must be created with this LOS calculator in order for this method to work correctly.

This method is useful for updating an existent coverage matrix in a performance friendly manner. It is preferred to creating and deleting new LOS coverages.

Parameters:

aProperties - a new properties for aLOSCoverageMatrixSFCT

aAltitudeProvider - the altitude provider that is used for sampling the terrain

aTargetReference - the target reference in which the LOS values will be computed

aLOSCoverageMatrixSFCT - the LOS coverage matrix to be updated

disposeLOSCalculation

public void disposeLOSCalculation(ILcdLOSCoverageMatrix aLOSCoverageMatrix)

Method that allows the LOS calculator to clean up any references the LOS coverage matrix.

Note that calling this method makes the ILcdLOSCoverageMatrix invalid, and no further methods should be called on this object.

Parameters:

aLOSCoverageMatrix - A LOS coverage matrix created by this LOS calculator that should be disposed of

dispose

public void dispose()

Disposes of this object and allows it to release any system resources that it is holding.

Important note that calling this method will make all produced ILcdLOSCoverageMatrix instances invalid. Dispose this object with caution.

Specified by:

dispose in interface ILcdDisposable