Package com.luciad.tea.lightspeed.los

Class 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 Details

    • 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 Details

    • 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