org.kynosarges.tektosyne.geometry

Class PointDComparator

java.lang.Object

org.kynosarges.tektosyne.geometry.PointDComparator

All Implemented Interfaces:

java.util.Comparator<PointD>

Direct Known Subclasses:

PointDComparatorX, PointDComparatorY

public abstract class PointDComparator
extends java.lang.Object
implements java.util.Comparator<PointD>

Provides methods that compare two PointD instances, given a specified epsilon for lexicographic coordinate comparisons. Defines a Comparator that lexicographically compares PointD instances with a given epsilon, applied to each dimension. PointDComparatorX and PointDComparatorY provide implementations whose lexicographic ordering prefers x- and y-coordinates, respectively.

Field Summary

Fields

Modifier and Type	Field and Description
double	epsilon The epsilon used for coordinate comparisons.

Constructor Summary

Constructors

Constructor and Description
PointDComparator(double epsilon) Creates a PointDComparator with the specified epsilon.

Method Summary

Modifier and Type	Method and Description
int	findNearest(java.util.List<PointD> points, PointD q) Searches a sorted PointD list for the element nearest to the specified location, given the current epsilon for coordinate comparisons.
PointD	findNearest(java.util.NavigableSet<PointD> points, PointD q) Searches a NavigableSet for the PointD element nearest to the specified location, given the current epsilon for coordinate comparisons.
<V> java.util.NavigableMap<PointD,V>	findRange(java.util.NavigableMap<PointD,V> map, RectD range) Finds all entries in the specified NavigableMap whose PointD keys are within the specified RectD, given the current epsilon for coordinate comparisons.
java.util.NavigableSet<PointD>	findRange(java.util.NavigableSet<PointD> points, RectD range) Finds all PointD elements in the specified NavigableSet that are within the specified RectD, given the current epsilon for coordinate comparisons.
protected abstract double	getPrimary(PointD point) Gets the primary dimension of the specified PointD.
protected abstract double	getSecondary(PointD point) Gets the secondary dimension of the specified PointD.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

compare, comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Field Detail

epsilon

public final double epsilon

The epsilon used for coordinate comparisons. Defines the maximum absolute difference at which coordinates should be considered equal. Zero indicates that exact coordinate comparisons should be used.

Note: List.sort(java.util.Comparator<? super E>) throws IllegalArgumentException when supplied a PointDComparator whose epsilon overlaps the coordinates of distinct PointD instances in both dimensions, resulting in the classification of PointD instances as equal when their PointD.equals(org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, double) and PointD.hashCode() results signal inequality. ("Comparison method violates its general contract.")

Constructor Detail

PointDComparator

public PointDComparator(double epsilon)

Creates a PointDComparator with the specified epsilon.

Parameters:

epsilon - the maximum absolute difference at which coordinates should be considered equal

Throws:

java.lang.IllegalArgumentException - if epsilon is less than zero

Method Detail

findNearest

public int findNearest(java.util.List<PointD> points,
                       PointD q)

Searches a sorted PointD list for the element nearest to the specified location, given the current epsilon for coordinate comparisons. First approximates the index position of q within points by a lexicographic binary search, using PointDComparator methods with the current epsilon. The search is then expanded to both increasing and decreasing index positions, using the Euclidean distance of the first approximation, or of any subsequently found nearer element, as the maximum search radius.

Once the vertical (PointDComparatorY) or horizontal (PointDComparatorX) distances of the tested points elements in both directions exceed the search radius, findNearest returns the zero-based index of the element with the smallest Euclidean distance to q.

The worst-case runtime is O(ld n + n), where n is the total number of points. However, the runtime for an evenly distributed point set is close to O(ld n) since comparisons can be limited to a relatively narrow vertical or horizontal distance around the initial approximation.

Parameters:

points - a List containing the PointD locations to search, sorted lexicographically using the current PointDComparator

q - the PointD location to find in points

Returns:

the zero-based index of any occurrence of q in points, if found; otherwise, the zero-based index of the points element with the smallest Euclidean distance to q

Throws:

java.lang.NullPointerException - if points or q is null, or points is empty or contains any null elements

findNearest

public PointD findNearest(java.util.NavigableSet<PointD> points,
                          PointD q)

Searches a NavigableSet for the PointD element nearest to the specified location, given the current epsilon for coordinate comparisons. First approximates the vicinity of q within points using NavigableSet.headSet(E, boolean) and NavigableSet.tailSet(E, boolean). The search is then expanded by both ascending and descending iteration, using the Euclidean distance of the first approximation, or of any subsequently found nearer element, as the maximum search radius.

Once the vertical (PointDComparatorY) or horizontal (PointDComparatorX) distances of the tested points elements in both directions exceed the search radius, findNearest returns the element with the smallest Euclidean distance to q.

The actual runtime depends on the supplied implementation of NavigableSet. For the algorithm to work, points must use the PointDComparator itself as its SortedSet.comparator(). This condition is accordingly checked.

Parameters:

points - a NavigableSet containing the PointD locations to search, sorted lexicographically using the current PointDComparator

q - the PointD location to find in points

Returns:

the specified q if found in points; otherwise, the points element with the smallest Euclidean distance to q

Throws:

java.lang.IllegalArgumentException - if the SortedSet.comparator() of points differs from the current PointDComparator instance

java.lang.NullPointerException - if points or q is null, or points is empty or contains any null elements

findRange

public <V> java.util.NavigableMap<PointD,V> findRange(java.util.NavigableMap<PointD,V> map,
                                                      RectD range)

Finds all entries in the specified NavigableMap whose PointD keys are within the specified RectD, given the current epsilon for coordinate comparisons. Always returns a new NavigableMap with the current PointDComparator.

Type Parameters:

V - the type of all values in the NavigableMap

Parameters:

map - the NavigableMap whose PointD keys to search

range - a RectD indicating the coordinate range to find

Returns:

a NavigableMap containing all map entries whose PointD keys are within range

Throws:

java.lang.IllegalArgumentException - if the SortedSet.comparator() of map differs from the current PointDComparator instance

java.lang.NullPointerException - if map or range is null

findRange

public java.util.NavigableSet<PointD> findRange(java.util.NavigableSet<PointD> points,
                                                RectD range)

Finds all PointD elements in the specified NavigableSet that are within the specified RectD, given the current epsilon for coordinate comparisons. Always returns a new NavigableSet with the current PointDComparator.

Parameters:

points - the NavigableSet whose PointD elements to search

range - a RectD indicating the coordinate range to find

Returns:

a NavigableSet containing all points within range

Throws:

java.lang.IllegalArgumentException - if the SortedSet.comparator() of points differs from the current PointDComparator instance

java.lang.NullPointerException - if points or range is null

getPrimary

protected abstract double getPrimary(PointD point)

Gets the primary dimension of the specified PointD.

Parameters:

point - the PointD whose primary dimension to return

Returns:

the PointD.x or PointD.y component of point

Throws:

java.lang.NullPointerException - if point is null

getSecondary

protected abstract double getSecondary(PointD point)

Gets the secondary dimension of the specified PointD.

Parameters:

point - the PointD whose secondary dimension to return

Returns:

the PointD.x or PointD.y component of point

Throws:

java.lang.NullPointerException - if point is null