com.luciad.tea

Terrain Analysis EngineClass TLcdExtremePointFinder

java.lang.Object

com.luciad.tea.TLcdExtremePointFinder

public class TLcdExtremePointFinder
extends Object

Finds the extreme (highest or lowest) points from a matrix view. This class considers an extreme point to be a point that has a higher (lower) or equal value than its surrounding points.

The definition of a peak is defined as a point that has a higher (lower) or equal value than its surrounding points and for which one of the following statements count.

• The value difference on all paths between two peaks shall be at least the specified value difference (value separation).
  
  


• The distance between two peaks shall be at least the specified minimum distance (distance separation).
  
  

Note that special values are not taken into account while looking for extreme points. The method isSpecialValue(double) is called to determine which values are ignored.

For performance reasons, the referenced matrix view, for which the extreme points need to be located, should be set to the class instead of passed as a parameter in the method findExtremePoints. This allows reuse of previous results when one of the other parameters is changed. Note that this caching mechanism makes the class inherently not thread safe.

When the values of the referenced matrix view are updated after the matrix view was set to this instance, the caching mechanism can result in invalid results. The caching should be reset via the method clearCache().

The following code shows how the class should be used. The variable peaks will contain, at most, requestedPointCount points that are the highest extreme points from the given referencedMatrixView.

 TLcdExtremePointFinder finder = new TLcdExtremePointFinder();
 finder.setReferencedMatrixView(referencedMatrixView);

 List peaks = finder.findExtremePoints(TLcdExtremePointFinder.Type.HIGHEST_POINTS, requestedPointCount, separationHeight, separationDistance);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TLcdExtremePointFinder.Type Defines an enumeration that indicates the type of extreme points that should be computed.

Constructor Summary

Constructors

Constructor and Description
TLcdExtremePointFinder() Constructs a default extreme point finder.
TLcdExtremePointFinder(ILcdReferencedMatrixView aReferencedMatrixView) Constructs an extreme point finder for the specified matrix view.

Method Summary

Modifier and Type	Method and Description
void	addStatusListener(ILcdStatusListener aStatusListener) Starts notifying a listener about the progress of the extreme point computation.
void	clearCache() Invalidates the cache of this instance.
List	findExtremePoints(TLcdExtremePointFinder.Type aExtremePointMode, int aRequestedPointCount, double aMinValueSeparation, double aMinDistanceSeparation) Retrieves an ordered collection of ILcdPoint objects.
ILcdReferencedMatrixView	getReferencedMatrixView() Returns the matrix view used for finding the extreme points.
protected boolean	isSpecialValue(double aValue) Determines whether the specified altitude value is special or not.
void	removeStatusListener(ILcdStatusListener aStatusListener) Terminates notifying a listener of the progress of the extreme point computation.
void	setReferencedMatrixView(ILcdReferencedMatrixView aReferencedMatrixView) Sets a new matrix view for finding the extreme points.

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcdExtremePointFinder

public TLcdExtremePointFinder()

Constructs a default extreme point finder.

Note that this constructor leaves this instance in an invalid state as it sets the matrix view to null. To validate the instance, a call to the method setReferencedMatrixView is required with a non-null matrix view.

TLcdExtremePointFinder

public TLcdExtremePointFinder(ILcdReferencedMatrixView aReferencedMatrixView)

Constructs an extreme point finder for the specified matrix view.

A clone of the model point, compatible with this reference, is used to create an extreme point. This model point is retrieved using ILcdModelReference.makeModelPoint(). The matrix view reference should therefore implement ILcdModelReference, if not an ClassCastException will be thrown.

Note that this constructor leaves this instance in an invalid state if the matrix view is set to null. To validate the instance, a call to the method setReferencedMatrixView is required with a non-null matrix view.

Parameters:

aReferencedMatrixView - the matrix view to use for finding the extreme points.

Throws:

ClassCastException - if the reference of the matrix view does not implement ILcdModelReference.

Method Detail

removeStatusListener

public void removeStatusListener(ILcdStatusListener aStatusListener)

Terminates notifying a listener of the progress of the extreme point computation.

Parameters:

aStatusListener - will no longer be notified of progress when running an extreme point computation.

See Also:

addStatusListener(ILcdStatusListener)

addStatusListener

public void addStatusListener(ILcdStatusListener aStatusListener)

Starts notifying a listener about the progress of the extreme point computation.

Parameters:

aStatusListener - will be notified of progress when running an extreme point computation.

See Also:

removeStatusListener(ILcdStatusListener)

getReferencedMatrixView

public ILcdReferencedMatrixView getReferencedMatrixView()

Returns the matrix view used for finding the extreme points.

Returns:

the matrix view used for finding the extreme points.

setReferencedMatrixView

public void setReferencedMatrixView(ILcdReferencedMatrixView aReferencedMatrixView)

Sets a new matrix view for finding the extreme points. The reference of this matrix view defines the reference in which the created extreme points are defined.

A clone of the model point, compatible with this reference, is used to create an extreme point. This model point is retrieved using ILcdModelReference.makeModelPoint(). The matrix view reference should therefore implement ILcdModelReference, if not an ClassCastException will be thrown.

For performance reasons, this referenced matrix view should be set to the class instead of passed as a parameter in the method findExtremePoints. This allows reuse of previous results when one of the other parameters is changed. Note that this caching mechanism makes the class inherently not thread safe.

When the values of the referenced matrix view are updated after the matrix view was set to this instance, the caching mechanism can result in invalid results. The caching should be reset via the method clearCache().

Note that, if the matrix view is set to null, this instance is left in an invalid state. The finder remains unusable until a non-null matrix view is set.

Parameters:

aReferencedMatrixView - the new matrix view to use for finding the extreme points.

Throws:

ClassCastException - if the reference of the matrix view does not implement ILcdModelReference.

clearCache

public void clearCache()

Invalidates the cache of this instance. This method needs to be called when the values of the matrix view are updated after the matrix view was set to this instance.

findExtremePoints

public List findExtremePoints(TLcdExtremePointFinder.Type aExtremePointMode,
                              int aRequestedPointCount,
                              double aMinValueSeparation,
                              double aMinDistanceSeparation)

Retrieves an ordered collection of ILcdPoint objects. The points represent the coordinates of the extreme peaks found in the referenced matrix view set on this instance. Each point object is a clone of the model point retrieved from the matrix view reference. The collection is ordered with the highest (lowest) extreme point first depending on the specified extreme point mode.

The definition of a peak is defined as a point that has a higher (lower) or equal value than its surrounding points and for which one of the following statements count.

• All paths between two peaks shall exceed the specified value difference (value separation)
• The distance between two peaks shall be at least the specified minimum distance (distance separation)

Both separation parameters should be positive or Double.POSITIVE_INFINITY. If a parameter does not lie inside this interval, an IllegalArgumentException will be thrown.

When the number of extreme points requested by the user has been reached, or when no other extreme points can be found, the locations of the extreme points are returned in a list of ILcdPoint objects.

Note that, when the current thread is interrupted, the method will return the intermediate result containing the extreme points that were already found.

Parameters:

aExtremePointMode - The mode indicating which extreme points should be computed.

aRequestedPointCount - The maximum number of extreme points that should be retrieved. Note that the actual number of returned points may be smaller than the requested number if there are not enough peaks.

aMinValueSeparation - The relative value difference which indicates how "distinct" the peaks should be from one another. Must be positive or Double.POSITIVE_INFINITY.

aMinDistanceSeparation - The minimum distance between two peaks defined in meters. This indicates how "far" the peaks should be from one another. With this value a circle is defined around the peak in which no other peak can be found. Must be positive or Double.POSITIVE_INFINITY.

Returns:

an ordered collection of ILcdPoint objects.

Throws:

IllegalArgumentException - if a separation parameter is not strict positive or Double.POSITIVE_INFINITY.

IllegalStateException - if no matrix view was set to this instance.

NullPointerException - if the specified extreme point mode is null.

isSpecialValue

protected boolean isSpecialValue(double aValue)

Determines whether the specified altitude value is special or not. A value is special if it is a Not-a-Number value (Double.NaN) or if it lies in the reserved special value interval [ Integer.MIN_VALUE + 1, Integer.MIN_VALUE + 100 ].

This method is called to determine the matrix values to ignore while looking for extreme points. Override this method when, for example, the matrix contains special values that are defined outside the above interval.

Parameters:

aValue - The value to check.

Returns:

true if the value is special, false otherwise.