org.kynosarges.tektosyne.geometry

Class GeoUtils

java.lang.Object

org.kynosarges.tektosyne.geometry.GeoUtils

public final class GeoUtils
extends java.lang.Object

Provides standard algorithms and auxiliary methods for computational geometry. All random... methods use the standard Math.random() method for random number generation and are therefore thread-safe, though access of that method by multiple threads may lead to performance degradation.

Method Summary

Modifier and Type	Method and Description
static LineD[]	connectPoints(boolean isClosed, PointD... points) Connects the specified PointD coordinates with LineD instances.
static PointD[]	convexHull(PointD... points) Finds the convex hull for the specified PointD coordinates.
static <T> T[]	fromDoubles(java.lang.Class<T> type, double... items) Converts the specified Double array to the specified geometric objects.
static <T> T[]	fromInts(java.lang.Class<T> type, int... items) Converts the specified Integer array to the specified geometric objects.
static int	nearestPoint(java.util.List<PointD> points, PointD q) Finds the PointD nearest to the specified coordinates in the specified collection.
static PolygonLocation	pointInPolygon(PointD q, PointD[] polygon) Finds the location of the specified PointD coordinates relative to the specified arbitrary PointD polygon, using exact coordinate comparisons.
static PolygonLocation	pointInPolygon(PointD q, PointD[] polygon, double epsilon) Finds the location of the specified PointD coordinates relative to the specified arbitrary PointD polygon, given the specified epsilon for coordinate comparisons.
static double	polygonArea(PointD... polygon) Computes the area of the specified arbitrary PointD polygon.
static PointD	polygonCentroid(PointD... polygon) Computes the centroid of the specified arbitrary PointD polygon.
static LineD	randomLine(double x, double y, double width, double height) Creates a random LineD within the specified bounding area.
static PointD	randomPoint(double x, double y, double width, double height) Creates a random PointD within the specified bounding area.
static PointD[]	randomPoints(int count, RectD bounds) Creates a set of random PointD coordinates within the specified bounding area.
static PointD[]	randomPoints(int count, RectD bounds, PointDComparator comparer, double distance) Creates a set of random PointD coordinates within the specified bounding area, ensuring a specified pairwise minimum distance.
static PointD[]	randomPolygon(double x, double y, double width, double height) Creates a random simple PointD polygon within the specified bounding area.
static <T> double[]	toDoubles(java.lang.Class<T> type, T... items) Converts the specified geometric objects to a Double array.
static <T> int[]	toInts(java.lang.Class<T> type, T... items) Converts the specified geometric objects to an Integer array.

Methods inherited from class java.lang.Object

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

Method Detail

connectPoints

public static LineD[] connectPoints(boolean isClosed,
                                    PointD... points)

Connects the specified PointD coordinates with LineD instances. Returns an empty arry if points contains less than two elements. Otherwise, returns an array with the same number of elements as points if isClosed is true, else one element less.

connectPoints does not check for identical adjacent points, or for congruent LineD instances. For example, if points contains two elements and isClosed is true, the returned array will contain two LineD instances with identical coordinates but opposite directions.

Parameters:

isClosed - true to create a LineD from the last to the first points element, else false.

points - the array of PointD coordinates to connect

Returns:

an array of LineD instaces connecting all points in the given order

Throws:

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

convexHull

public static PointD[] convexHull(PointD... points)

Finds the convex hull for the specified PointD coordinates. If the specified points array contains only one or two elements, the result is a new array containing the same elements. Any points elements that are coincident or collinear with other elements are always removed from the returned array, however.

convexHull performs a Graham scan with an asymptotic runtime of O(n log n). This Java implementation was adapted from the Graham algorithm by Joseph O’Rourke, Computational Geometry in C (2nd ed.), Cambridge University Press 1998, p.72ff.

Parameters:

points - the array of PointD coordinates whose convex hull to find

Returns:

the subset of points that represents the vertices of the convex hull

Throws:

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

fromDoubles

public static <T> T[] fromDoubles(java.lang.Class<T> type,
                                  double... items)

Converts the specified Double array to the specified geometric objects. Dispatches to the fromDoubles method of LineD, PointD, RectD, or SizeD, as indicated by the generic type argument.

Type Parameters:

T - the geometric type to convert to, which must be either LineD, PointD, RectD, or SizeD

Parameters:

type - the Class object for T, required for method dispatch

items - an array containing the Double components of T instances, stored in successive index positions per instance

Returns:

the T array created from items

Throws:

java.lang.IllegalArgumentException - if T is not a valid geometric type, or if the length of items is not divisible by the number of Double components in T, or if any items are incompatible with T

java.lang.NullPointerException - if type or items is null

fromInts

public static <T> T[] fromInts(java.lang.Class<T> type,
                               int... items)

Converts the specified Integer array to the specified geometric objects. Dispatches to the fromInts method of LineI, PointI, RectI, or SizeI, as indicated by the generic type argument.

Type Parameters:

T - the geometric type to convert to, which must be either LineI, PointI, RectI, or SizeI

Parameters:

type - the Class object for T, required for method dispatch

items - an array containing the Integer components of T instances, stored in successive index positions per instance

Returns:

the T array created from items

Throws:

java.lang.IllegalArgumentException - if T is not a valid geometric type, or if the length of items is not divisible by the number of Integer components in T, or if any items are incompatible with T

java.lang.NullPointerException - if type or items is null

nearestPoint

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

Finds the PointD nearest to the specified coordinates in the specified collection. Performs a linear search through points to find the element with the smallest Euclidean distance to q. This is always an O(n) operation, where n is the total number of points, unless an exact match for q is encountered.

If the specified points are already sorted lexicographically, PointDComparator offers a much faster PointDComparator.findNearest(java.util.List<org.kynosarges.tektosyne.geometry.PointD>, org.kynosarges.tektosyne.geometry.PointD) method.

Parameters:

points - the List of PointD elements to search

q - the PointD coordinates to locate

Returns:

the zero-based index of the first occurrence of q in points, if found; else 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

pointInPolygon

public static PolygonLocation pointInPolygon(PointD q,
                                             PointD[] polygon)

Finds the location of the specified PointD coordinates relative to the specified arbitrary PointD polygon, using exact coordinate comparisons. Never returns null. The specified polygon is implicitly assumed to be closed, with an edge connecting its first and last vertex. Therefore, all vertices should be different.

pointInPolygon performs a ray crossings algorithm with an asymptotic runtime of O(n). This Java implementation was adapted from the InPoly1 algorithm by Joseph O’Rourke, Computational Geometry in C (2nd ed.), Cambridge University Press 1998, p.244.

Parameters:

q - the PointD coordinates to locate

polygon - an array of PointD coordinates defining the vertices of an arbitrary polygon

Returns:

a PolygonLocation value indicating the location of q relative to polygon

Throws:

java.lang.IllegalArgumentException - if polygon has less than three elements

java.lang.NullPointerException - if q or polygon is null, or any polygon element is null

pointInPolygon

public static PolygonLocation pointInPolygon(PointD q,
                                             PointD[] polygon,
                                             double epsilon)

Finds the location of the specified PointD coordinates relative to the specified arbitrary PointD polygon, given the specified epsilon for coordinate comparisons. Never returns null. See exact overload for details.

Parameters:

q - the PointD coordinates to locate

polygon - an array of PointD coordinates defining the vertices of an arbitrary polygon

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

Returns:

a PolygonLocation value indicating the location of q relative to polygon

Throws:

java.lang.IllegalArgumentException - if polygon has less than three elements, or epsilon is less than or equal to zero

java.lang.NullPointerException - if q or polygon is null, or any polygon element is null

polygonArea

public static double polygonArea(PointD... polygon)

Computes the area of the specified arbitrary PointD polygon. The specified polygon is implicitly assumed to be closed, with an edge connecting its first and last vertex. Therefore, all vertices should be different. Moreover, polygon must not self-intersect.

The absolute value of polygonArea(org.kynosarges.tektosyne.geometry.PointD...) equals the area of polygon, and is zero if all vertices are collinear or otherwise enclose no area. The sign of a non-zero value indicates the orientation of its vertices: negative if the vertices are specified in clockwise order, positive if they are specified in counter-clockwise order, assuming y-coordinates increase upward.

Parameters:

polygon - an array of PointD coordinates defining the vertices of an arbitrary polygon

Returns:

the area of polygon, with a sign that indicates the orientation of its vertices

Throws:

java.lang.IllegalArgumentException - if polygon has less than three elements

java.lang.NullPointerException - if polygon is null or contains any null elements

polygonCentroid

public static PointD polygonCentroid(PointD... polygon)

Computes the centroid of the specified arbitrary PointD polygon. The specified polygon is implicitly assumed to be closed, with an edge connecting its first and last vertex. Therefore, all vertices should be different. Moreover, polygon must not self-intersect and its vertices cannot be collinear, i.e. polygonArea(org.kynosarges.tektosyne.geometry.PointD...) cannot be zero.

Parameters:

polygon - an array of PointD coordinates defining the vertices of an arbitrary polygon

Returns:

the PointD coordinates of the centroid (center of gravity) of polygon

Throws:

java.lang.IllegalArgumentException - if polygon has less than three elements

java.lang.NullPointerException - if polygon is null or contains any null elements

randomLine

public static LineD randomLine(double x,
                               double y,
                               double width,
                               double height)

Creates a random LineD within the specified bounding area.

Parameters:

x - the smallest x-coordinate of the bounding area

y - the smallest y-coordinate of the bounding area

width - the horizontal extension of the bounding area

height - the vertical extension of the bounding area

Returns:

a LineD with random LineD.start and LineD.end points ranging from (x, y) to (x + width, y + height)

Throws:

java.lang.IllegalArgumentException - if width or height is equal to or less than zero

randomPoint

public static PointD randomPoint(double x,
                                 double y,
                                 double width,
                                 double height)

Creates a random PointD within the specified bounding area.

Parameters:

x - the smallest x-coordinate of the bounding area

y - the smallest y-coordinate of the bounding area

width - the horizontal extension of the bounding area

height - the vertical extension of the bounding area

Returns:

a PointD with random PointD.x and PointD.y coordinates ranging from (x, y) to (x + width, y + height)

Throws:

java.lang.IllegalArgumentException - if width or height is equal to or less than zero

randomPoints

public static PointD[] randomPoints(int count,
                                    RectD bounds)

Creates a set of random PointD coordinates within the specified bounding area. The returned array is unsorted and may contain duplicate PointD coordinates.

Parameters:

count - the number of PointD coordinates to create

bounds - a RectD defining the the bounding area

Returns:

an array of count randomly created PointD coordinates within bounds

Throws:

java.lang.IllegalArgumentException - if count is less than zero, or RectD.width() or RectD.height() of bounds is zero

java.lang.NullPointerException - if bounds is null

randomPoints

public static PointD[] randomPoints(int count,
                                    RectD bounds,
                                    PointDComparator comparer,
                                    double distance)

Creates a set of random PointD coordinates within the specified bounding area, ensuring a specified pairwise minimum distance. The returned array is sorted using the specified comparer and never contains any duplicate PointD coordinates. This method may enter an endless loop if distance is too great relative to count and bounds.

Parameters:

count - the number of PointD coordinates to create

bounds - a RectD defining the the bounding area

comparer - the PointDComparator used to sort & search the created array

distance - the smallest Euclidean distance between any two PointD instances

Returns:

an array of count randomly created PointD coordinates within bounds

Throws:

java.lang.IllegalArgumentException - if count is less than zero, or distance is equal to or less than zero, or RectD.width() or RectD.height() of bounds is zero

java.lang.NullPointerException - if bounds or comparer is null

randomPolygon

public static PointD[] randomPolygon(double x,
                                     double y,
                                     double width,
                                     double height)

Creates a random simple PointD polygon within the specified bounding area. Moves in a full circle around the center of the specified bounding area, placing vertices at random angles and radii within the area. Any two vertices are separated by a minimum angular distance of six degrees. The resulting polygon is simple, i.e. covering a single contiguous space without self-intersecting.

Parameters:

x - the smallest x-coordinate of the bounding area

y - the smallest y-coordinate of the bounding area

width - the horizontal extension of the bounding area

height - the vertical extension of the bounding area

Returns:

an array of PointD vertices with random PointD.x and PointD.y coordinates ranging from (x, y) to (x + width, y + height)

Throws:

java.lang.IllegalArgumentException - if width or height is equal to or less than zero

toDoubles

public static <T> double[] toDoubles(java.lang.Class<T> type,
                                     T... items)

Converts the specified geometric objects to a Double array. Dispatches to the toDoubles method of LineD, PointD, RectD, or SizeD, as indicated by the generic type argument.

Type Parameters:

T - the geometric type to convert from, which must be either LineD, PointD, RectD, or SizeD

Parameters:

type - the Class object for T, required for method dispatch

items - the T array to convert

Returns:

an array containing the Double components of all items, stored in successive index positions per T instance

Throws:

java.lang.IllegalArgumentException - if T is not a valid geometric type

java.lang.NullPointerException - if type or items is null, or items contains any null elements

toInts

public static <T> int[] toInts(java.lang.Class<T> type,
                               T... items)

Converts the specified geometric objects to an Integer array. Dispatches to the toInts method of LineI, PointI, RectI, or SizeI, as indicated by the generic type argument.

Type Parameters:

T - the geometric type to convert from, which must be either LineI, PointI, RectI, or SizeI

Parameters:

type - the Class object for T, required for method dispatch

items - the T array to convert

Returns:

an array containing the Integer components of all items, stored in successive index positions per T instance

Throws:

java.lang.IllegalArgumentException - if T is not a valid geometric type

java.lang.NullPointerException - if type or items is null, or items contains any null elements