Package com.luciad.lucy.addons.tea.loscoverage

Class TLcyLOSCoverageBackEnd

java.lang.Object

com.luciad.lucy.addons.tea.ALcyTEABackEnd

com.luciad.lucy.addons.tea.loscoverage.TLcyLOSCoverageBackEnd

public class TLcyLOSCoverageBackEnd
extends ALcyTEABackEnd

Back-end functionality for a TEA line-of-sight coverage add-on. It provides the following functionality to calculate line-of-sight coverages:

• an altitude descriptor to create a propagation function with;
• create an ILcdLOSCoverage;
• create an TLcdLOSCoverageFactory;
• create propagation functions for the coverage factory to use.

See Also:

• ALcyTEABackEnd

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ALTITUDE_KEY	The property name for a line-of-sight coverage's altitude.
static final String	ALTITUDE_MODE_KEY	The property name for a line-of-sight coverage's altitude mode.
static final String	ARC_ANGLE_KEY	The property name for a line-of-sight coverage's arc angle.
static final String	DOMAIN_OBJECT_CONTEXT_KEY	The property name for a line-of-sight coverage's associated domain object.
static final String	FIXED_HEIGHT_AMSL_KEY	Deprecated. replaced by FIXED_HEIGHT_KEY and FIXED_HEIGHT_MODE_KEY
static final String	FIXED_HEIGHT_KEY	The property name for the fixed height of a fixed height propagation function.
static final String	FIXED_HEIGHT_MODE_KEY	The property name for the fixed height model of a fixed height propagation function.
static final String	K_FACTOR_KEY	The property name for a line-of-sight coverage's radar K-factor.
static final String	LOCATION_KEY	The property name for a line-of-sight coverage's location.
static final String	LOCATION_REFERENCE_KEY	The property name for a line-of-sight coverage's model reference .
static final String	MAX_RADIUS_KEY	The property name for a line-of-sight coverage's maximum radius.
static final String	MAX_VERTICAL_ANGLE_KEY	The property name for a line-of-sight coverage's maximum vertical angle.
static final String	MIN_VERTICAL_ANGLE_KEY	The property name for a line-of-sight coverage's minimum vertical angle.
static final String	PROPAGATION_FUNCTION_KEY	The property name for a line-of-sight coverage's propagation function.
static final String	PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT	Denotes a propagation function with fixed height.
static final String	PROPAGATION_FUNCTION_VALUE_NORMAL	Denotes a normal propagation function.
static final String	PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND	Denotes a propagation function with sky in background.
static final String	START_ANGLE_KEY	The property name for a line-of-sight coverage's start angle.

Fields inherited from class com.luciad.lucy.addons.tea.ALcyTEABackEnd

ALTITUDE_PROVIDER_KEY, DISPLAY_NAME_KEY, MODEL_DISPLAY_NAME_KEY, MODEL_REFERENCE_KEY, QUALITY_KEY, SHAPE_KEY, SHAPE_REFERENCE_KEY, SOURCE_NAME_KEY, TARGET_REFERENCE_KEY, VIEW_KEY

Constructor Summary

Constructors

Constructor	Description
TLcyLOSCoverageBackEnd(ILcyLucyEnv aLucyEnv)	Default constructor for the line-of-sight coverage back-end.

Method Summary

Modifier and Type	Method	Description
ILcdLOSCoverage	createCoverage(ALcyProperties aProperties)	Creates a new line-of-sight coverage, based on the given properties.
TLcdLOSCoverageFactory	createLOSCoverageFactory(ALcyProperties aProperties)	Returns a line-of-sight coverage factory with which to compute coverages.
TLspLOSCalculator	createLspLOSCoverageCalculator()	Returns a TLspLOSCalculator used to calculate ILcdLOSCoverageMatrix instances, which make use of OpenCL functionality and are therefore faster than the default ILcdLOSCoverageMatrix calculator.
ILcdModelDescriptor	createModelDescriptor(ALcyProperties aProperties)	Returns a model descriptor suitable for the add-on's used models.
ILcdLOSPropagationFunction	createPropagationFunction(ALcyProperties aProperties)	Creates a new line-of-sight propagation function, based on the given properties.
ILcdMatrixRasterValueMapper	createPropagationMatrixRasterValueMapper(String aPropagationFunctionKey)	Returns an ILcdMatrixRasterValueMapper for the given propagation function ID.
String	retrievePropagationFunctionLabel(String aPropagationFunctionKey)	Returns a displayable label for the given propagation function ID.

Methods inherited from class com.luciad.lucy.addons.tea.ALcyTEABackEnd

createAltitudeDescriptor, createAltitudeMatrixViewFactory, createAltitudeProvider, getLucyEnv

Methods inherited from class java.lang.Object

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

Field Details

DOMAIN_OBJECT_CONTEXT_KEY

public static final String DOMAIN_OBJECT_CONTEXT_KEY

The property name for a line-of-sight coverage's associated domain object. The associated property value is of type TLcyDomainObjectContext.

See Also:

• TLcyLOSCoverageAddOn.SELECTED_COVERAGE_KEY
• Constant Field Values

LOCATION_KEY

public static final String LOCATION_KEY

The property name for a line-of-sight coverage's location. The associated property value is of type ILcdPoint.

See Also:

• Constant Field Values

LOCATION_REFERENCE_KEY

public static final String LOCATION_REFERENCE_KEY

The property name for a line-of-sight coverage's model reference . The associated property value is of type ILcdGeoReference.

See Also:

• Constant Field Values

ALTITUDE_KEY

public static final String ALTITUDE_KEY

The property name for a line-of-sight coverage's altitude. The associated property value is of type double, expressed in meters.

See Also:

• Constant Field Values

ALTITUDE_MODE_KEY

public static final String ALTITUDE_MODE_KEY

The property name for a line-of-sight coverage's altitude mode. The associated property value is of type TLcdCoverageAltitudeMode.

See Also:

• Constant Field Values

START_ANGLE_KEY

public static final String START_ANGLE_KEY

The property name for a line-of-sight coverage's start angle. The associated property value is of type double, expressed in radians.

See Also:

• Constant Field Values

ARC_ANGLE_KEY

public static final String ARC_ANGLE_KEY

The property name for a line-of-sight coverage's arc angle. The associated property value is of type double, expressed in radians.

See Also:

• Constant Field Values

MAX_RADIUS_KEY

public static final String MAX_RADIUS_KEY

The property name for a line-of-sight coverage's maximum radius. The associated property value is of type double, expressed in meters.

See Also:

• Constant Field Values

MIN_VERTICAL_ANGLE_KEY

public static final String MIN_VERTICAL_ANGLE_KEY

The property name for a line-of-sight coverage's minimum vertical angle. The associated property value is of type double, expressed in radians.

See Also:

• Constant Field Values

MAX_VERTICAL_ANGLE_KEY

public static final String MAX_VERTICAL_ANGLE_KEY

The property name for a line-of-sight coverage's maximum vertical angle. The associated property value is of type double, expressed in radians.

See Also:

• Constant Field Values

K_FACTOR_KEY

public static final String K_FACTOR_KEY

The property name for a line-of-sight coverage's radar K-factor. The associated property value is of type double, expressed without unit, default 1.0.

See Also:

• Constant Field Values

PROPAGATION_FUNCTION_KEY

public static final String PROPAGATION_FUNCTION_KEY

The property name for a line-of-sight coverage's propagation function. The associated property value is one of PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT, PROPAGATION_FUNCTION_VALUE_NORMAL and PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND.

See Also:

• Constant Field Values

FIXED_HEIGHT_AMSL_KEY

@Deprecated
public static final String FIXED_HEIGHT_AMSL_KEY

Deprecated.

replaced by FIXED_HEIGHT_KEY and FIXED_HEIGHT_MODE_KEY

The property name for the fixed height of a fixed height propagation function. The associated property value is of type double, expressed in height AMSL.

See Also:

• Constant Field Values

FIXED_HEIGHT_KEY

public static final String FIXED_HEIGHT_KEY

The property name for the fixed height of a fixed height propagation function. The associated property value is of type double, expressed in meters.

See Also:

• Constant Field Values

FIXED_HEIGHT_MODE_KEY

public static final String FIXED_HEIGHT_MODE_KEY

The property name for the fixed height model of a fixed height propagation function. The associated property value is of type TLcdCoverageAltitudeMode.

See Also:

• Constant Field Values

PROPAGATION_FUNCTION_VALUE_NORMAL

public static final String PROPAGATION_FUNCTION_VALUE_NORMAL

Denotes a normal propagation function.

See Also:

• Constant Field Values

PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND

public static final String PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND

Denotes a propagation function with sky in background.

See Also:

• Constant Field Values

PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT

public static final String PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT

Denotes a propagation function with fixed height.

See Also:

• Constant Field Values

Constructor Details

TLcyLOSCoverageBackEnd

public TLcyLOSCoverageBackEnd(ILcyLucyEnv aLucyEnv)

Default constructor for the line-of-sight coverage back-end.

Parameters:

aLucyEnv - the Lucy environment for which the back-end will be used

Method Details

createModelDescriptor

public ILcdModelDescriptor createModelDescriptor(ALcyProperties aProperties)

Returns a model descriptor suitable for the add-on's used models.

Specified by:

createModelDescriptor in class ALcyTEABackEnd

Parameters:

aProperties - a properties object with the following parameters:

• ALcyTEABackEnd.SOURCE_NAME_KEY: The source name that was used to retrieve the data from, use null to indicate that it was created from scratch.
• ALcyTEABackEnd.DISPLAY_NAME_KEY: the display name that the model descriptor should use @return a suitable model descriptor

Returns:

a line-of-sight coverage model descriptor

createPropagationFunction

public ILcdLOSPropagationFunction createPropagationFunction(ALcyProperties aProperties)

Creates a new line-of-sight propagation function, based on the given properties. This implementation supports three functions: normal, sky in background, and fixed height. The type of function returned depends on the PROPAGATION_FUNCTION_KEY property.

Note that in some situations this propagation function is by default replaced by a TLspLOSCalculator. To know the circumstances in which the TLspLOSCalculator is used, see createLspLOSCoverageCalculator().

Parameters:

aProperties - The arguments of this method. For the normal and sky in background functions, the following properties are needed:

• ALcyTEABackEnd.ALTITUDE_PROVIDER_KEY, an altitude provider of type ALcdTerrainElevationProvider
• ALTITUDE_MODE_KEY, the altitude mode
• MIN_VERTICAL_ANGLE_KEY, the minumum vertical angle
• MAX_VERTICAL_ANGLE_KEY, the maximum vertical angle

The fixed height propagation function also requires the following property:

• FIXED_HEIGHT_KEY, the fixed height
• FIXED_HEIGHT_MODE_KEY, the altitude mode

Returns:

a new line-of-sight propagation function

See Also:

• createLspLOSCoverageCalculator()

createCoverage

public ILcdLOSCoverage createCoverage(ALcyProperties aProperties)

Creates a new line-of-sight coverage, based on the given properties.

Parameters:

aProperties - The arguments of this method. The following properties are needed:

• ALcyTEABackEnd.QUALITY_KEY, the quality on which to base the coverage's sample density
• LOCATION_KEY, coverage's location
• LOCATION_REFERENCE_KEY, the geo-reference of the location
• DOMAIN_OBJECT_CONTEXT_KEY, the coverage's associated domain object. Objects implementing ILcdOriented will have their orientation added to the start angle.
• ALTITUDE_KEY, the coverage's altitude
• ALTITUDE_MODE_KEY, the coverage's altitude mode
• START_ANGLE_KEY, the coverage's start angle
• ARC_ANGLE_KEY, the coverage's arc angle
• MAX_RADIUS_KEY, the coverage's maximum radius
• ALcyTEABackEnd.TARGET_REFERENCE_KEY, the geo-reference of the target object. This property is used to compute the required step sizes.

Returns:

a new line-of-sight coverage

createLOSCoverageFactory

public TLcdLOSCoverageFactory createLOSCoverageFactory(ALcyProperties aProperties)

Returns a line-of-sight coverage factory with which to compute coverages.

Parameters:

aProperties - This implementation does not require any arguments.

Returns:

a line-of-sight coverage factory

createLspLOSCoverageCalculator

public TLspLOSCalculator createLspLOSCoverageCalculator()

Returns a TLspLOSCalculator used to calculate ILcdLOSCoverageMatrix instances, which make use of OpenCL functionality and are therefore faster than the default ILcdLOSCoverageMatrix calculator. For performance reasons, we advice to reuse the line-of-sight calculator as much as possible.

Note that this calculator will be only be used when all the following statements hold true:

• Lightspeed is available.
• The "useOpenCLSpeedup" flag, found in TLcyLOSCoverageAddOn's config file, is set to true.
• The altitude mode of the resulting ILcdLOSCoverageMatrix is 'above ground', 'above mean sea level' or 'above geoid'
• The requested line-of-sight function type is 'normal'. So it is not 'fixed height' or 'sky in background'.

Warning: this method should never be called if OpenCL is not supported by either a missing Lightspeed license option or by incompatible hardware.
Warning: when the Lightspeed line-of-sight calculator created by this method is no longer needed, it should be disposed if a dispose method is available. If such a method is available and it is not disposed of, memory leaks could occur.

Returns:

a TLspLOSCalculator used to calculate ILcdLOSCoverageMatrix instances. Can be null, in case the calculator could not be created while OpenCL is supported.

Throws:

UnsupportedOperationException - An exception is thrown when either no Lightspeed license option is available or when OpenCL is not supported.

See Also:

• createPropagationFunction(ALcyProperties)

retrievePropagationFunctionLabel

public String retrievePropagationFunctionLabel(String aPropagationFunctionKey)

Returns a displayable label for the given propagation function ID.

Parameters:

aPropagationFunctionKey - one of PROPAGATION_FUNCTION_VALUE_NORMAL, PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND, or PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT.

Returns:

a user-friendly label

createPropagationMatrixRasterValueMapper

public ILcdMatrixRasterValueMapper createPropagationMatrixRasterValueMapper(String aPropagationFunctionKey)

Returns an ILcdMatrixRasterValueMapper for the given propagation function ID.

Parameters:

aPropagationFunctionKey - one of PROPAGATION_FUNCTION_VALUE_NORMAL, PROPAGATION_FUNCTION_VALUE_SKY_BACKGROUND, or PROPAGATION_FUNCTION_VALUE_FIXED_HEIGHT.

Returns:

a value mapper for creating a LOS coverage raster