public final class GeoUtils
extends java.lang.Object
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.Modifier and Type | Method and Description |
---|---|
static LineD[] |
connectPoints(boolean isClosed,
PointD... points)
|
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)
|
static PolygonLocation |
pointInPolygon(PointD q,
PointD[] polygon,
double epsilon)
|
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. |
public static LineD[] connectPoints(boolean isClosed, PointD... points)
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.
isClosed
- true
to create a LineD
from the last to the first
points
element, else false
.points
- the array of PointD
coordinates to connectLineD
instaces connecting all points
in the given orderjava.lang.NullPointerException
- if points
is null
or contains any null
elementspublic static PointD[] convexHull(PointD... points)
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.
points
- the array of PointD
coordinates whose convex hull to findpoints
that represents the vertices of the convex hulljava.lang.NullPointerException
- if points
is null
or empty
or contains any null
elementspublic static <T> T[] fromDoubles(java.lang.Class<T> type, double... items)
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.T
- the geometric type to convert to, which must be either
LineD
, PointD
, RectD
, or SizeD
type
- the Class
object for T, required for method dispatchitems
- an array containing the Double
components of T
instances, stored in successive index positions per instanceitems
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 Tjava.lang.NullPointerException
- if type
or items
is null
public static <T> T[] fromInts(java.lang.Class<T> type, int... items)
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.T
- the geometric type to convert to, which must be either
LineI
, PointI
, RectI
, or SizeI
type
- the Class
object for T, required for method dispatchitems
- an array containing the Integer
components of T
instances, stored in successive index positions per instanceitems
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 Tjava.lang.NullPointerException
- if type
or items
is null
public static int nearestPoint(java.util.List<PointD> points, PointD q)
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.
points
- the List
of PointD
elements to searchq
- the PointD
coordinates to locateq
in points
,
if found; else the zero-based index of the points
element with the
smallest Euclidean distance to q
java.lang.NullPointerException
- if points
or q
is null
,
or points
is empty or contains any null
elementspublic static PolygonLocation pointInPolygon(PointD q, PointD[] polygon)
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.
q
- the PointD
coordinates to locatepolygon
- an array of PointD
coordinates defining the vertices of an arbitrary polygonPolygonLocation
value indicating the location of q
relative to polygon
java.lang.IllegalArgumentException
- if polygon
has less than three elementsjava.lang.NullPointerException
- if q
or polygon
is null
,
or any polygon
element is null
public static PolygonLocation pointInPolygon(PointD q, PointD[] polygon, double epsilon)
PointD
coordinates relative to the specified
arbitrary PointD
polygon, given the specified epsilon for coordinate comparisons.
Never returns null
. See exact overload for details.q
- the PointD
coordinates to locatepolygon
- an array of PointD
coordinates defining the vertices of an arbitrary polygonepsilon
- the maximum absolute difference at which two coordinates should be considered equalPolygonLocation
value indicating the location of q
relative to polygon
java.lang.IllegalArgumentException
- if polygon
has less than three elements,
or epsilon
is less than or equal to zerojava.lang.NullPointerException
- if q
or polygon
is null
,
or any polygon
element is null
public static double polygonArea(PointD... polygon)
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.
polygon
- an array of PointD
coordinates defining the vertices of an arbitrary polygonpolygon
, with a sign that indicates the orientation of its verticesjava.lang.IllegalArgumentException
- if polygon
has less than three elementsjava.lang.NullPointerException
- if polygon
is null
or contains any null
elementspublic static PointD polygonCentroid(PointD... polygon)
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.polygon
- an array of PointD
coordinates defining the vertices of an arbitrary polygonPointD
coordinates of the centroid (center of gravity) of polygon
java.lang.IllegalArgumentException
- if polygon
has less than three elementsjava.lang.NullPointerException
- if polygon
is null
or contains any null
elementspublic static LineD randomLine(double x, double y, double width, double height)
LineD
within the specified bounding area.x
- the smallest x-coordinate of the bounding areay
- the smallest y-coordinate of the bounding areawidth
- the horizontal extension of the bounding areaheight
- the vertical extension of the bounding areaLineD
with random LineD.start
and LineD.end
points
ranging from (x
, y
) to (x + width
, y + height
)java.lang.IllegalArgumentException
- if width
or height
is equal to or less than zeropublic static PointD randomPoint(double x, double y, double width, double height)
PointD
within the specified bounding area.x
- the smallest x-coordinate of the bounding areay
- the smallest y-coordinate of the bounding areawidth
- the horizontal extension of the bounding areaheight
- the vertical extension of the bounding areaPointD
with random PointD.x
and PointD.y
coordinates
ranging from (x
, y
) to (x + width
, y + height
)java.lang.IllegalArgumentException
- if width
or height
is equal to or less than zeropublic static PointD[] randomPoints(int count, RectD bounds)
PointD
coordinates within the specified bounding area.
The returned array is unsorted and may contain duplicate PointD
coordinates.count
- the number of PointD
coordinates to createbounds
- a RectD
defining the the bounding areacount
randomly created PointD
coordinates within bounds
java.lang.IllegalArgumentException
- if count
is less than zero, or RectD.width()
or RectD.height()
of bounds
is zerojava.lang.NullPointerException
- if bounds
is null
public static PointD[] randomPoints(int count, RectD bounds, PointDComparator comparer, double distance)
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
.count
- the number of PointD
coordinates to createbounds
- a RectD
defining the the bounding areacomparer
- the PointDComparator
used to sort & search the created arraydistance
- the smallest Euclidean distance between any two PointD
instancescount
randomly created PointD
coordinates within bounds
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 zerojava.lang.NullPointerException
- if bounds
or comparer
is null
public static PointD[] randomPolygon(double x, double y, double width, double height)
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.x
- the smallest x-coordinate of the bounding areay
- the smallest y-coordinate of the bounding areawidth
- the horizontal extension of the bounding areaheight
- the vertical extension of the bounding areaPointD
vertices with random PointD.x
and PointD.y
coordinates ranging from (x
, y
) to (x + width
, y + height
)java.lang.IllegalArgumentException
- if width
or height
is equal to or less than zeropublic static <T> double[] toDoubles(java.lang.Class<T> type, T... items)
Double
array.
Dispatches to the toDoubles
method of LineD
, PointD
,
RectD
, or SizeD
, as indicated by the generic type argument.T
- the geometric type to convert from, which must be either
LineD
, PointD
, RectD
, or SizeD
type
- the Class
object for T, required for method dispatchitems
- the T array to convertDouble
components of all items
,
stored in successive index positions per T instancejava.lang.IllegalArgumentException
- if T is not a valid geometric typejava.lang.NullPointerException
- if type
or items
is null
,
or items
contains any null
elementspublic static <T> int[] toInts(java.lang.Class<T> type, T... items)
Integer
array.
Dispatches to the toInts
method of LineI
, PointI
,
RectI
, or SizeI
, as indicated by the generic type argument.T
- the geometric type to convert from, which must be either
LineI
, PointI
, RectI
, or SizeI
type
- the Class
object for T, required for method dispatchitems
- the T array to convertInteger
components of all items
,
stored in successive index positions per T instancejava.lang.IllegalArgumentException
- if T is not a valid geometric typejava.lang.NullPointerException
- if type
or items
is null
,
or items
contains any null
elements