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.
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);
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 and Description 

TLcdExtremePointFinder()
Constructs a default extreme point finder.

TLcdExtremePointFinder(ILcdReferencedMatrixView aReferencedMatrixView)
Constructs an extreme point finder for the specified matrix view.

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.

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 nonnull
matrix view.
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 nonnull
matrix view.
aReferencedMatrixView
 the matrix view to use for finding the extreme points.ClassCastException
 if the reference of the matrix view does not
implement ILcdModelReference
.public void removeStatusListener(ILcdStatusListener aStatusListener)
aStatusListener
 will no longer be notified of progress when running
an extreme point computation.addStatusListener(ILcdStatusListener)
public void addStatusListener(ILcdStatusListener aStatusListener)
aStatusListener
 will be notified of progress when running an extreme
point computation.removeStatusListener(ILcdStatusListener)
public ILcdReferencedMatrixView getReferencedMatrixView()
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 nonnull
matrix view is
set.
aReferencedMatrixView
 the new matrix view to use for finding the extreme points.ClassCastException
 if the reference of the matrix view does not
implement ILcdModelReference
.public void clearCache()
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.
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.
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
.ILcdPoint
objects.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
.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.
aValue
 The value to check.true
if the value is special, false
otherwise.