org.kynosarges.tektosyne.geometry

Class PointD

java.lang.Object

org.kynosarges.tektosyne.geometry.PointD

public final class PointD
extends java.lang.Object

Represents a location in two-dimensional space, using Double coordinates. PointD contains two immutable non-negative Double dimensions, representing either a two-dimensional location or a two-dimensional vector. Use PointI to represent points with Integer dimensions.

Field Summary

Fields

Modifier and Type	Field and Description
static PointD	EMPTY An empty read-only PointD.
double	x The x-coordinate of the PointD.
double	y The y-coordinate of the PointD.

Constructor Summary

Constructors

Constructor and Description
PointD() Creates a PointD with the coordinate origin.
PointD(double x, double y) Creates a PointD with the specified Double coordinates.

Method Summary

Modifier and Type	Method and Description
PointD	add(PointD point) Adds the location of the specified PointD to this instance.
double	angle() Gets the polar angle of the vector represented by the PointD, in radians.
double	angleBetween(PointD vector) Computes the angle between the vector represented by the PointD and the specified vector.
double	angleBetween(PointD a, PointD b) Computes the angle between the vectors from the PointD to the specified locations.
double	crossProductLength(PointD vector) Computes the length of the cross-product of the vector represented by the PointD and the specified vector.
double	crossProductLength(PointD a, PointD b) Computes the length of the cross-product of the vectors from the PointD to the specified locations.
boolean	equals(java.lang.Object obj) Compares the specified Object to this PointD instance.
static boolean	equals(PointD a, PointD b, double epsilon) Compares two PointD instances for equality, given the specified epsilon.
static PointD[]	fromDoubles(double... points) Converts the specified Double array to a PointD array.
static PointD	fromPolar(double length, double angle) Creates a PointD from the specified polar coordinates.
int	hashCode() Returns a hash code for the PointD.
boolean	isCollinear(PointD a, PointD b) Determines if the PointD is collinear with the specified instances.
boolean	isCollinear(PointD a, PointD b, double epsilon) Determines if the PointD is collinear with the specified instances, given the specified epsilon.
double	length() Gets the absolute length of the vector represented by the PointD.
double	lengthSquared() Gets the squared absolute length of the vector represented by the PointD.
PointD	move(PointD target, double distance) Moves the PointD by the specified distance in the specified direction.
double	multiply(PointD vector) Multiplies the vectors represented by the specified PointD and this instance.
PointD	normalize() Normalizes the vector represented by the PointD.
PointD	restrict(double minX, double minY, double maxX, double maxY) Restricts the PointD to the specified location range.
PointI	round() Converts the PointD to a PointI by rounding dimensions to the nearest Integer values.
PointD	subtract(PointD point) Subtracts the location of the specified PointD from this instance.
static double[]	toDoubles(PointD... points) Converts the specified PointD array to a Double array.
PointI	toPointI() Converts the PointD to a PointI by truncating dimensions to the nearest Integer values.
java.lang.String	toString() Returns a String representation of the PointD.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

x

public final double x

The x-coordinate of the PointD.

y

public final double y

The y-coordinate of the PointD.

EMPTY

public static final PointD EMPTY

An empty read-only PointD. Both x and y are set to zero.

Constructor Detail

PointD

public PointD()

Creates a PointD with the coordinate origin. Both x and y are set to zero.

PointD

public PointD(double x,
              double y)

Creates a PointD with the specified Double coordinates.

Parameters:

x - the x-coordinate of the PointD

y - the y-coordinate of the PointD

Method Detail

add

public PointD add(PointD point)

Adds the location of the specified PointD to this instance.

Parameters:

point - the PointD whose location to add to this instance

Returns:

a PointD whose x and y equal the addition of the corresponding dimensions of the specified point to this instance

Throws:

java.lang.NullPointerException - if point is null

angle

public double angle()

Gets the polar angle of the vector represented by the PointD, in radians. Returns the result of Math.atan2(double, double) for y and x, within the interval [-Math.PI, +Math.PI].

Returns:

the polar angle, in radians, of the vector represented by the PointD, or zero if x and y both equal zero

angleBetween

public double angleBetween(PointD vector)

Computes the angle between the vector represented by the PointD and the specified vector. Returns the result of Math.atan2(double, double) for the cross-product length and the scalar dot product of the two vectors. The possible range of values is [-Math.PI, +Math.PI].

Parameters:

vector - the PointD vector to compare with this instance

Returns:

the angle, in radians, between this instance and the specified vector, in that order

Throws:

java.lang.NullPointerException - if vector is null

angleBetween

public double angleBetween(PointD a,
                           PointD b)

Computes the angle between the vectors from the PointD to the specified locations. Returns the result of Math.atan2(double, double) for the cross-product length and the scalar dot product of the two vectors. The possible range of values is [-Math.PI, +Math.PI].

Parameters:

a - the PointD location where the first vector ends

b - the PointD location where the second vector ends

Returns:

the angle, in radians, between the vectors from this instance to a and from this instance to b, in that order

Throws:

java.lang.NullPointerException - if a or b is null

crossProductLength

public double crossProductLength(PointD vector)

Computes the length of the cross-product of the vector represented by the PointD and the specified vector. The absolute value equals the area of the parallelogram spanned by the PointD and the specified vector. The sign indicates their spatial relationship, as described in crossProductLength(PointD, PointD).

Parameters:

vector - the PointD vector to multiply with this instance

Returns:

a Double value indicating the length of the cross-product of this instance and the specified vector, in that order

Throws:

java.lang.NullPointerException - if vector is null

crossProductLength

public double crossProductLength(PointD a,
                                 PointD b)

Computes the length of the cross-product of the vectors from the PointD to the specified locations. The absolute value equals the area of the parallelogram spanned by the vectors from the PointD to a and b. The sign indicates their spatial relationship of the two vectors, as follows:

• Less than zero — The sequence from this instance to a and then b constitutes a right-hand turn, assuming y-coordinates increase upward.
• Zero — This instance, a, and b are collinear.
• Greater than zero — The sequence from this instance to a and then b constitutes a left-hand turn, assuming y-coordinates increase upward.

Parameters:

a - the PointD location where the first vector ends

b - the PointD location where the second vector ends

Returns:

a Double value indicating the length of the cross-product of the vectors from this instance to a and from this instance to b, in that order

Throws:

java.lang.NullPointerException - if a or b is null

equals

public static boolean equals(PointD a,
                             PointD b,
                             double epsilon)

Compares two PointD instances for equality, given the specified epsilon.

Parameters:

a - the first PointD to compare

b - the second PointD to compare

epsilon - the maximum absolute difference where the corresponding dimensions of a and b are considered equal

Returns:

true if the absolute difference between both corresponding dimensions of a and b is no greater than epsilon, else false

Throws:

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

java.lang.NullPointerException - if a or b is null

fromDoubles

public static PointD[] fromDoubles(double... points)

Converts the specified Double array to a PointD array. The returned array has half as many elements as the specified points and retains the same coordinate sequence. Expects input suitable for the JavaFX Polygon and Polyline classes.

Parameters:

points - an array containing the x and y components of PointD instances, stored in alternating index positions

Returns:

the PointD array created from points

Throws:

java.lang.IllegalArgumentException - if points has an odd number of elements

java.lang.NullPointerException - if points is null

fromPolar

public static PointD fromPolar(double length,
                               double angle)

Creates a PointD from the specified polar coordinates. Returns EMPTY if length equals zero, and inverts the signs of x and y if length is less than zero.

Parameters:

length - the distance from the coordinate origin to the PointD

angle - the polar angle, in radians, of the PointD

Returns:

a PointD whose length() and angle() equal the specified length and angle

isCollinear

public boolean isCollinear(PointD a,
                           PointD b)

Determines if the PointD is collinear with the specified instances. Returns true exactly if crossProductLength(PointD, PointD) is zero for a and b.

Parameters:

a - the first PointD to examine

b - the second PointD to examine

Returns:

true if the PointD is collinear with a and b, else false

Throws:

java.lang.NullPointerException - if a or b is null

isCollinear

public boolean isCollinear(PointD a,
                           PointD b,
                           double epsilon)

Determines if the PointD is collinear with the specified instances, given the specified epsilon. Returns true exactly if crossProductLength(PointD, PointD) is no greater than epsilon for a and b.

Parameters:

a - the first PointD to examine

b - the second PointD to examine

epsilon - the maximum absolute value at which the result of crossProductLength(org.kynosarges.tektosyne.geometry.PointD) should be considered zero

Returns:

true if the PointD is collinear with a and b, else false

Throws:

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

java.lang.NullPointerException - if a or b is null

length

public double length()

Gets the absolute length of the vector represented by the PointD. Returns the square root of the sum of the squares of x and y.

Returns:

the non-negative absolute length of the vector represented by the PointD

lengthSquared

public double lengthSquared()

Gets the squared absolute length of the vector represented by the PointD. Returns the sum of the squares of x and y. Use instead of length() if you only need the squared value.

Returns:

a non-negative Double value that equals the square of length()

move

public PointD move(PointD target,
                   double distance)

Moves the PointD by the specified distance in the specified direction. Moves toward target if distance is positive, and away from target if distance is negative. Returns the current instance if it equals target or if distance is zero.

Parameters:

target - the PointD location that indicates the direction of the move

distance - the amount by which to move towards target

Returns:

a PointD that equals this instance, moved toward or away from target by the specified distance

Throws:

java.lang.NullPointerException - if target is null

multiply

public double multiply(PointD vector)

Multiplies the vectors represented by the specified PointD and this instance. Returns the sum of the pairwise products of both instances' x and y. That sum equals lengthSquared() if the specified vector equals this instance.

Parameters:

vector - the PointD to multiply with this instance

Returns:

a Double value that represents the scalar dot product of the specified vector and this instance

Throws:

java.lang.NullPointerException - if vector is null

normalize

public PointD normalize()

Normalizes the vector represented by the PointD.

Returns:

a PointD with the same angle() as this instance, and whose length() equals one

restrict

public PointD restrict(double minX,
                       double minY,
                       double maxX,
                       double maxY)

Restricts the PointD to the specified location range.

Parameters:

minX - the smallest permissible x

minY - the smallest permissible y

maxX - the greatest permissible x

maxY - the greatest permissible y

Returns:

a PointD whose x and y coordinates equal those of this instance, restricted to the specified location range

round

public PointI round()

Converts the PointD to a PointI by rounding dimensions to the nearest Integer values. Uses Fortran.nint(double) for rounding.

Returns:

a PointI whose PointI.x and PointI.y equal the corresponding dimensions of the PointD, rounded to the nearest Integer values

Throws:

java.lang.ArithmeticException - if any dimension overflows Integer

subtract

public PointD subtract(PointD point)

Subtracts the location of the specified PointD from this instance.

Parameters:

point - the PointD location to subtract from this instance

Returns:

a PointD whose x and y equal the subtraction of the corresponding dimensions of the specified point from this instance

Throws:

java.lang.NullPointerException - if point is null

toDoubles

public static double[] toDoubles(PointD... points)

Converts the specified PointD array to a Double array. The returned array has twice as many elements as the specified points and retains the same coordinate sequence. Produces output suitable for the JavaFX Polygon and Polyline classes.

Parameters:

points - the PointD array to convert

Returns:

an array containing the x and y components of all points, stored in alternating index positions

Throws:

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

toPointI

public PointI toPointI()

Converts the PointD to a PointI by truncating dimensions to the nearest Integer values. Uses Integer casts for truncation.

Returns:

a PointI whose PointI.x and PointI.y equal the corresponding dimensions of the PointD, truncated to the nearest Integer values

Throws:

java.lang.ArithmeticException - if any dimension overflows Integer

equals

public boolean equals(java.lang.Object obj)

Compares the specified Object to this PointD instance.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the Object to compare to this instance

Returns:

true if obj is not null and a PointD instance whose x and y equal those of this instance, else false

hashCode

public int hashCode()

Returns a hash code for the PointD.

Overrides:

hashCode in class java.lang.Object

Returns:

an Integer hash code for the PointD

toString

public java.lang.String toString()

Returns a String representation of the PointD.

Overrides:

toString in class java.lang.Object

Returns:

a String containing the values of x and y