Class TLcdExtremePointFinder
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
Modifier and TypeClassDescriptionstatic final class
Defines an enumeration that indicates the type of extreme points that should be computed. 
Constructor Summary
ConstructorDescriptionConstructs a default extreme point finder.TLcdExtremePointFinder
(ILcdReferencedMatrixView aReferencedMatrixView) Constructs an extreme point finder for the specified matrix view. 
Method Summary
Modifier and TypeMethodDescriptionvoid
addStatusListener
(ILcdStatusListener aStatusListener) Starts notifying a listener about the progress of the extreme point computation.void
Invalidates the cache of this instance.findExtremePoints
(TLcdExtremePointFinder.Type aExtremePointMode, int aRequestedPointCount, double aMinValueSeparation, double aMinDistanceSeparation) Retrieves an ordered collection ofILcdPoint
objects.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.

Constructor Details

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 methodsetReferencedMatrixView
is required with a nonnull
matrix view. 
TLcdExtremePointFinder
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 implementILcdModelReference
, if not anClassCastException
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 methodsetReferencedMatrixView
is required with a nonnull
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 implementILcdModelReference
.


Method Details

removeStatusListener
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
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:

getReferencedMatrixView
Returns the matrix view used for finding the extreme points. Returns:
 the matrix view used for finding the extreme points.

setReferencedMatrixView
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 implementILcdModelReference
, if not anClassCastException
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 nonnull
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 implementILcdModelReference
.

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, anIllegalArgumentException
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 orDouble.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 orDouble.POSITIVE_INFINITY
. Returns:
 an ordered collection of
ILcdPoint
objects.  Throws:
IllegalArgumentException
 if a separation parameter is not strict positive orDouble.POSITIVE_INFINITY
.IllegalStateException
 if no matrix view was set to this instance.NullPointerException
 if the specified extreme point mode isnull
.

isSpecialValue
protected boolean isSpecialValue(double aValue) Determines whether the specified altitude value is special or not. A value is special if it is a NotaNumber 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.
