org.kynosarges.tektosyne.geometry

Class LineD

java.lang.Object

org.kynosarges.tektosyne.geometry.LineD

public final class LineD
extends java.lang.Object

Represents a directed line segment in two-dimensional space, using Double coordinates. LineD contains two immutable PointD locations, indicating the start and end points of a directed line segment. angle() and length() are calculated on demand. Use LineI to represent lines with Integer coordinates.

Field Summary

Fields

Modifier and Type	Field and Description
static LineD	EMPTY An empty read-only LineD.
PointD	end The end point of the LineD.
PointD	start The start point of the LineD.

Constructor Summary

Constructors

Constructor and Description
LineD() Creates a LineD that starts and ends at the coordinate origin.
LineD(double startX, double startY, double endX, double endY) Creates a LineD with the specified Double coordinates.
LineD(PointD start, PointD end) Creates a LineD with the specified PointD coordinates.

Method Summary

Modifier and Type	Method and Description
double	angle() Gets the angle of the LineD, in radians.
double	distanceSquared(PointD q) Gets the squared distance between the LineD and the specified PointD coordinates.
static boolean	equals(LineD a, LineD b, double epsilon) Compares two LineD instances for equality, given the specified epsilon.
boolean	equals(java.lang.Object obj) Compares the specified Object to this LineD instance.
double	findX(double y) Finds the x-coordinate for the specified y-coordinate on the LineD or its infinite extension.
double	findY(double x) Finds the y-coordinate for the specified x-coordinate on the LineD or its infinite extension.
static LineD[]	fromDoubles(double... lines) Converts the specified Double array to a LineD array.
static LineD[]	fromIndexPoints(PointD[] points, PointI[] indices) Converts the specified arrays of PointD coordinates and zero-based indices into an array of equivalent LineD instances.
int	hashCode() Returns a hash code for the LineD.
LineIntersection	intersect(LineD line) Finds the intersection between the LineD and a specified instance, using exact coordinate comparisons.
LineIntersection	intersect(LineD line, double epsilon) Finds the intersection between the LineD and a specified instance, given the specified epsilon for coordinate comparisons.
PointD	intersect(PointD q) Finds the intersection between the LineD and the perpendicular dropped from the specified PointD coordinates.
double	inverseSlope() Gets the inverse slope of the LineD.
double	length() Gets the absolute length of the LineD.
double	lengthSquared() Gets the squared absolute length of the LineD.
LineLocation	locate(PointD q) Determines the location of the specified PointD relative to the LineD, using exact coordinate comparisons.
LineLocation	locate(PointD q, double epsilon) Determines the location of the specified PointD relative to the LineD, given the specified epsilon for coordinate comparisons.
LineLocation	locateCollinear(PointD q) Determines the location of the specified PointD relative to the LineD, assuming they are collinear and using exact coordinate comparisons.
LineLocation	locateCollinear(PointD q, double epsilon) Determines the location of the specified PointD relative to the LineD, assuming they are collinear and given the specified epsilon for coordinate comparisons.
LineD	reverse() Reverses the direction of the LineD.
LineI	round() Converts the LineD to a LineI by rounding coordinates to the nearest Integer values.
double	slope() Gets the slope of the LineD.
static double[]	toDoubles(LineD... lines) Converts the specified LineD array to a Double array.
LineI	toLineI() Converts the LineD to a LineI by truncating coordinates to the nearest Integer values.
java.lang.String	toString() Returns a String representation of the LineD.
PointD	vector() Gets the vector defined by the LineD.

Methods inherited from class java.lang.Object

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

Field Detail

start

public final PointD start

The start point of the LineD.

end

public final PointD end

The end point of the LineD.

EMPTY

public static final LineD EMPTY

An empty read-only LineD. Both start and end are set to PointD.EMPTY.

Constructor Detail

LineD

public LineD()

Creates a LineD that starts and ends at the coordinate origin. Both start and end are set to PointD.EMPTY.

LineD

public LineD(double startX,
             double startY,
             double endX,
             double endY)

Creates a LineD with the specified Double coordinates.

Parameters:

startX - the x-coordinate of the start point

startY - the y-coordinate of the start point

endX - the x-coordinate of the end point

endY - the y-coordinate of the end point

LineD

public LineD(PointD start,
             PointD end)

Creates a LineD with the specified PointD coordinates.

Parameters:

start - the start point of the LineD

end - the end point of the LineD

Throws:

java.lang.NullPointerException - if start or end is null

Method Detail

angle

public double angle()

Gets the angle of the LineD, in radians. Returns the result of Math.atan2(double, double) for the vertical and horizontal distances between end and start, within the interval [-Math.PI, +Math.PI].

angle() equals zero if the LineD extends horizontally to the right, and increases as the line turns clockwise (y-axis pointing down) or counter-clockwise (y-axis pointing up).

Returns:

the angle, in radians, of the direction on the Cartesian plane in which the LineD is pointing, or zero if length() equals zero

distanceSquared

public double distanceSquared(PointD q)

Gets the squared distance between the LineD and the specified PointD coordinates. Returns either the squared length of the perpendicular dropped from q on the LineD, or the squared distance between q and start or end if the perpendicular does not intersect the LineD.

Parameters:

q - the PointD coordinates to examine

Returns:

the squared distance between the LineD and q

Throws:

java.lang.NullPointerException - if q is null

equals

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

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

Parameters:

a - the first LineD to compare

b - the second LineD to compare

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

Returns:

true if the absolute difference between all corresponding coordinates 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

findX

public double findX(double y)

Finds the x-coordinate for the specified y-coordinate on the LineD or its infinite extension. Returns the PointD.x coordinate of start or end if y exactly equals the corresponding PointD.y coordinate, else a computed x-coordinate.

Parameters:

y - the y-coordinate to examine

Returns:

the x-coordinate for y on the LineD or its infinite extension, or Double.MAX_VALUE if the LineD is horizontal

findY

public double findY(double x)

Finds the y-coordinate for the specified x-coordinate on the LineD or its infinite extension. Returns the PointD.y coordinate of start or end if x exactly equals the corresponding PointD.x coordinate, else a computed y-coordinate.

Parameters:

x - the x-coordinate to examine

Returns:

the y-coordinate for x on the LineD or its infinite extension, or Double.MAX_VALUE if the LineD is vertical

fromDoubles

public static LineD[] fromDoubles(double... lines)

Converts the specified Double array to a LineD array. The returned array has a quarter as many elements as the specified lines and retains the same coordinate sequence.

Parameters:

lines - an array containing the coordinates start.x, start.y, end.x, end.y of LineD instances, stored in successive index positions per LineD

Returns:

the LineD array created from lines

Throws:

java.lang.IllegalArgumentException - if the length of lines is not divisible by four

java.lang.NullPointerException - if lines is null

fromIndexPoints

public static LineD[] fromIndexPoints(PointD[] points,
                                      PointI[] indices)

Converts the specified arrays of PointD coordinates and zero-based indices into an array of equivalent LineD instances.

Parameters:

points - an array of PointD coordinates representing start or end points

indices - an array of PointI pairs of zero-based indices within points

Returns:

an array of LineD instances created from the pairs of points coordinates indexed by each indices element

Throws:

java.lang.ArrayIndexOutOfBoundsException - if indices contains an index that is less than zero, or equal to or greater than the number of points elements

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

intersect

public LineIntersection intersect(LineD line)

Finds the intersection between the LineD and a specified instance, using exact coordinate comparisons. Returns the result of LineIntersection.find(org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD) for the start and end points of this instance and the specified line, in that order.

Parameters:

line - the LineD to intersect with this instance

Returns:

a LineIntersection that describes if and how this instance intersects the specified line

Throws:

java.lang.NullPointerException - if line is null

intersect

public LineIntersection intersect(LineD line,
                                  double epsilon)

Finds the intersection between the LineD and a specified instance, given the specified epsilon for coordinate comparisons. Returns the result of LineIntersection.find(org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD) for the start and end points of this instance and the specified line, in that order, and for the specified epsilon.

Parameters:

line - the LineD to intersect with this instance

epsilon - the maximum absolute difference at which coordinates and intermediate results should be considered equal. Always raised to a minium of 1e-10.

Returns:

a LineIntersection that describes if and how this instance intersects the specified line

Throws:

java.lang.NullPointerException - if line is null

intersect

public PointD intersect(PointD q)

Finds the intersection between the LineD and the perpendicular dropped from the specified PointD coordinates. Returns start if length() equals zero.

Parameters:

q - the PointD coordinates from which to drop the perpendicular

Returns:

the PointD location where the perpendicular dropped from q intersects the LineD or its infinite extension

Throws:

java.lang.NullPointerException - if q is null

inverseSlope

public double inverseSlope()

Gets the inverse slope of the LineD. Equals 1/slope(). May return a negative value, depending on angle().

Returns:

the quotient of the horizontal and vertical extensions of the LineD, or Double.MAX_VALUE if the LineD is horizontal

length

public double length()

Gets the absolute length of the LineD. Returns the square root of the sum of the squares of the horizontal and vertical extensions of the LineD.

Returns:

the non-negative absolute length of the LineD

lengthSquared

public double lengthSquared()

Gets the squared absolute length of the LineD. Returns the sum of the squares of the horizontal and vertical extensions of the LineD. Use instead of length() if you only need the squared value.

Returns:

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

locate

public LineLocation locate(PointD q)

Determines the location of the specified PointD relative to the LineD, using exact coordinate comparisons. Never returns null. The return values LineLocation.LEFT and LineLocation.RIGHT assume that y-coordinates increase upward.

locate is based on the classify algorithm by Michael J. Laszlo, Computational Geometry and Computer Graphics in C++, Prentice Hall 1996, p.76.

Parameters:

q - the PointD coordinates to examine

Returns:

a LineLocation value indicating the location of q relative to the LineD

Throws:

java.lang.NullPointerException - if q is null

locate

public LineLocation locate(PointD q,
                           double epsilon)

Determines the location of the specified PointD relative to the LineD, given the specified epsilon for coordinate comparisons. Never returns null. The return values LineLocation.LEFT and LineLocation.RIGHT assume that y-coordinates increase upward.

Parameters:

q - the PointD coordinates to examine

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

Returns:

a LineLocation value indicating the location of q relative to the LineD

Throws:

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

java.lang.NullPointerException - if q is null

locateCollinear

public LineLocation locateCollinear(PointD q)

Determines the location of the specified PointD relative to the LineD, assuming they are collinear and using exact coordinate comparisons. Returns the result of LineIntersection.locateCollinear(org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD) for the start and end points of this instance and the specified q, in that order. Never returns null, LineLocation.LEFT, or LineLocation.RIGHT due to the assumption of collinearity.

Parameters:

q - the PointD coordinates to examine

Returns:

a LineLocation value indicating the location of q relative to the LineD

Throws:

java.lang.NullPointerException - if q is null

locateCollinear

public LineLocation locateCollinear(PointD q,
                                    double epsilon)

Determines the location of the specified PointD relative to the LineD, assuming they are collinear and given the specified epsilon for coordinate comparisons. Returns the result of LineIntersection.locateCollinear(org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD, org.kynosarges.tektosyne.geometry.PointD) for the start and end points of this instance and the specified q and epsilon, in that order. Never returns null, LineLocation.LEFT, or LineLocation.RIGHT due to the assumption of collinearity.

Parameters:

q - the PointD coordinates to examine

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

Returns:

a LineLocation value indicating the location of q relative to the LineD

Throws:

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

java.lang.NullPointerException - if q is null

reverse

public LineD reverse()

Reverses the direction of the LineD.

Returns:

a LineD whose start equals the end of this instance, and vice versa

round

public LineI round()

Converts the LineD to a LineI by rounding coordinates to the nearest Integer values. Uses PointD.round() for rounding.

Returns:

a LineI whose LineI.start and LineI.end points equal the corresponding points of the LineD, with each coordinate rounded to the nearest Integer value

Throws:

java.lang.ArithmeticException - if any coordinate overflows Integer

slope

public double slope()

Gets the slope of the LineD. Equals 1/inverseSlope(). May return a negative value, depending on angle().

Returns:

the quotient of the vertical and horizontal extensions of the LineD, or Double.MAX_VALUE if the LineD is vertical

toDoubles

public static double[] toDoubles(LineD... lines)

Converts the specified LineD array to a Double array. The returned array has four times as many elements as the specified lines and retains the same coordinate sequence.

Parameters:

lines - the LineD array to convert

Returns:

an array containing the coordinates start.x, start.y, end.x, end.y for all lines, stored in successive index positions per LineD

Throws:

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

toLineI

public LineI toLineI()

Converts the LineD to a LineI by truncating coordinates to the nearest Integer values. Uses Integer casts for truncation.

Returns:

a LineI whose LineI.start and LineI.end points equal the corresponding points of the LineD, with each coordinate truncated to the nearest Integer value

Throws:

java.lang.ArithmeticException - if any coordinate overflows Integer

vector

public PointD vector()

Gets the vector defined by the LineD. Equals the end point of the LineD, assuming its start point was shifted to the coordinate origin.

Returns:

a PointD vector comprising the horizontal and vertical extensions of the LineD

equals

public boolean equals(java.lang.Object obj)

Compares the specified Object to this LineD 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 LineD instance whose start and end equal those of this instance, else false

hashCode

public int hashCode()

Returns a hash code for the LineD.

Overrides:

hashCode in class java.lang.Object

Returns:

an Integer hash code for the LineD

toString

public java.lang.String toString()

Returns a String representation of the LineD.

Overrides:

toString in class java.lang.Object

Returns:

a String containing the values of start and end