Package org.apache.commons.geometry.euclidean.twod

Class Lines

java.lang.Object

org.apache.commons.geometry.euclidean.twod.Lines

public final class Lines
extends java.lang.Object

Class containing factory methods for constructing Line and LineSubset instances.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Lines()	Utility class; no instantiation.

Method Summary

Modifier and Type	Method	Description
static Line	fromPointAndAngle(Vector2D pt, double angle, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Create a line from a point lying on the line and an angle relative to the abscissa (x) axis.
static Line	fromPointAndDirection(Vector2D pt, Vector2D dir, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Create a line from a point and direction.
static Line	fromPoints(Vector2D p1, Vector2D p2, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Create a line from two points lying on the line.
static Ray	rayFromLocation(Line line, double startLocation)	Construct a ray starting at the given 1D location on line and continuing in the direction of the line to infinity.
static Ray	rayFromPoint(Line line, Vector2D startPoint)	Construct a ray starting at the given point and continuing to infinity in the direction of line.
static Ray	rayFromPointAndDirection(Vector2D startPoint, Vector2D direction, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Construct a ray from a start point and a direction.
static ReverseRay	reverseRayFromLocation(Line line, double endLocation)	Construct a reverse ray starting at infinity and continuing in the direction of line to the given 1D end location.
static ReverseRay	reverseRayFromPoint(Line line, Vector2D endPoint)	Construct a reverse ray starting at infinity and continuing in the direction of line to the given end point.
static ReverseRay	reverseRayFromPointAndDirection(Vector2D endPoint, Vector2D lineDirection, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Construct a reverse ray from an end point and a line direction.
static Segment	segmentFromLocations(Line line, double a, double b)	Construct a new line segment from a pair of 1D locations on a line.
static Segment	segmentFromPoints(Line line, Vector2D a, Vector2D b)	Construct a new line segment from a line and a pair of points.
static Segment	segmentFromPoints(Vector2D startPoint, Vector2D endPoint, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)	Construct a new line segment from two points.
static LineConvexSubset	span(Line line)	Create a LineConvexSubset spanning the entire line.
static LineConvexSubset	subsetFromInterval(Line line, double a, double b)	Create a line subset from a line and a 1D interval on the line.
static LineConvexSubset	subsetFromInterval(Line line, Interval interval)	Create a line subset from a line and a 1D interval on the line.
(package private) static void	validateLinesEquivalent(Line expected, Line actual)	Validate that the actual line is equivalent to the expected line, throwing an exception if not.

Methods inherited from class java.lang.Object

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

Constructor Detail

Lines

private Lines()

Utility class; no instantiation.

Method Detail

fromPoints

public static Line fromPoints(Vector2D p1,
                              Vector2D p2,
                              org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Create a line from two points lying on the line. The line points in the direction from p1 to p2.

Parameters:

p1 - first point

p2 - second point

precision - precision context used to compare floating point values

Returns:

new line containing p1 and p2 and pointing in the direction from p1 to p2

Throws:

java.lang.IllegalArgumentException - If the vector between p1 and p2 has zero length, as evaluated by the given precision context

fromPointAndDirection

public static Line fromPointAndDirection(Vector2D pt,
                                         Vector2D dir,
                                         org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Create a line from a point and direction.

Parameters:

pt - point belonging to the line

dir - the direction of the line

precision - precision context used to compare floating point values

Returns:

new line containing pt and pointing in direction dir

Throws:

java.lang.IllegalArgumentException - If dir has zero length, as evaluated by the given precision context

fromPointAndAngle

public static Line fromPointAndAngle(Vector2D pt,
                                     double angle,
                                     org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Create a line from a point lying on the line and an angle relative to the abscissa (x) axis. Note that the line does not need to intersect the x-axis; the given angle is simply relative to it.

Parameters:

pt - point belonging to the line

angle - angle of the line with respect to abscissa (x) axis, in radians

precision - precision context used to compare floating point values

Returns:

new line containing pt and forming the given angle with the abscissa (x) axis.

rayFromPointAndDirection

public static Ray rayFromPointAndDirection(Vector2D startPoint,
                                           Vector2D direction,
                                           org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Construct a ray from a start point and a direction.

Parameters:

startPoint - ray start point

direction - ray direction

precision - precision context used for floating point comparisons

Returns:

a new ray instance with the given start point and direction

Throws:

java.lang.IllegalArgumentException - If direction has zero length, as evaluated by the given precision context

See Also:

fromPointAndDirection(Vector2D, Vector2D, Precision.DoubleEquivalence)

rayFromPoint

public static Ray rayFromPoint(Line line,
                               Vector2D startPoint)

Construct a ray starting at the given point and continuing to infinity in the direction of line. The given point is projected onto the line.

Parameters:

line - line for the ray

startPoint - start point for the ray

Returns:

a new ray instance starting at the given point and continuing in the direction of line

Throws:

java.lang.IllegalArgumentException - if any coordinate in startPoint is NaN or infinite

rayFromLocation

public static Ray rayFromLocation(Line line,
                                  double startLocation)

Construct a ray starting at the given 1D location on line and continuing in the direction of the line to infinity.

Parameters:

line - line for the ray

startLocation - 1D location of the ray start point

Returns:

a new ray instance starting at the given 1D location and continuing to infinity along line

Throws:

java.lang.IllegalArgumentException - if startLocation is NaN or infinite

reverseRayFromPointAndDirection

public static ReverseRay reverseRayFromPointAndDirection(Vector2D endPoint,
                                                         Vector2D lineDirection,
                                                         org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Construct a reverse ray from an end point and a line direction.

Parameters:

endPoint - instance end point

lineDirection - line direction

precision - precision context used for floating point comparisons

Returns:

a new instance with the given end point and line direction

Throws:

java.lang.IllegalArgumentException - If lineDirection has zero length, as evaluated by the given precision context

See Also:

fromPointAndDirection(Vector2D, Vector2D, Precision.DoubleEquivalence)

reverseRayFromPoint

public static ReverseRay reverseRayFromPoint(Line line,
                                             Vector2D endPoint)

Construct a reverse ray starting at infinity and continuing in the direction of line to the given end point. The point is projected onto the line.

Parameters:

line - line for the instance

endPoint - end point for the instance

Returns:

a new instance starting at infinity and continuing along the line to endPoint

Throws:

java.lang.IllegalArgumentException - if any coordinate in endPoint is NaN or infinite

reverseRayFromLocation

public static ReverseRay reverseRayFromLocation(Line line,
                                                double endLocation)

Construct a reverse ray starting at infinity and continuing in the direction of line to the given 1D end location.

Parameters:

line - line for the instance

endLocation - 1D location of the instance end point

Returns:

a new instance starting infinity and continuing in the direction of line to the given 1D end location

Throws:

java.lang.IllegalArgumentException - if endLocation is NaN or infinite

segmentFromPoints

public static Segment segmentFromPoints(Vector2D startPoint,
                                        Vector2D endPoint,
                                        org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)

Construct a new line segment from two points. A new line is created for the segment and points in the direction from startPoint to endPoint.

Parameters:

startPoint - segment start point

endPoint - segment end point

precision - precision context to use for floating point comparisons

Returns:

a new line segment instance with the given start and end points

Throws:

java.lang.IllegalArgumentException - If the vector between startPoint and endPoint has zero length, as evaluated by the given precision context

segmentFromPoints

public static Segment segmentFromPoints(Line line,
                                        Vector2D a,
                                        Vector2D b)

Construct a new line segment from a line and a pair of points. The returned segment represents all points on the line between the projected locations of a and b. The points may be given in any order.

Parameters:

line - line forming the base of the segment

a - first point

b - second point

Returns:

a new line segment representing the points between the projected locations of a and b on the given line

Throws:

java.lang.IllegalArgumentException - if either point contains NaN or infinite coordinate values

segmentFromLocations

public static Segment segmentFromLocations(Line line,
                                           double a,
                                           double b)

Construct a new line segment from a pair of 1D locations on a line. The returned line segment consists of all points between the two locations, regardless of the order the arguments are given.

Parameters:

line - line forming the base of the segment

a - first 1D location on the line

b - second 1D location on the line

Returns:

a new line segment representing the points between a and b on the given line

Throws:

java.lang.IllegalArgumentException - if either of the locations is NaN or infinite

span

public static LineConvexSubset span(Line line)

Create a LineConvexSubset spanning the entire line. In other words, the returned subset is infinite and contains all points on the given line.

Parameters:

line - the line to span

Returns:

a convex subset spanning the entire line

subsetFromInterval

public static LineConvexSubset subsetFromInterval(Line line,
                                                  Interval interval)

Create a line subset from a line and a 1D interval on the line. The returned subset uses the precision context from the line and not any precision contexts referenced by the interval.

Parameters:

line - the line containing the subset

interval - 1D interval on the line

Returns:

a convex subset defined by the given line and interval

subsetFromInterval

public static LineConvexSubset subsetFromInterval(Line line,
                                                  double a,
                                                  double b)

Create a line subset from a line and a 1D interval on the line. The double values may be given in any order and support the use of infinite values. For example, the call Lines.subsetFromInterval(line, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY) will return an instance representing the full span of the line.

Parameters:

line - the line containing the subset

a - first 1D location on the line

b - second 1D location on the line

Returns:

a line subset defined by the given line and interval

Throws:

java.lang.IllegalArgumentException - if either double value is NaN or both are infinite with the same sign (eg, both positive infinity or both negative infinity)

validateLinesEquivalent

static void validateLinesEquivalent(Line expected,
                                    Line actual)

Validate that the actual line is equivalent to the expected line, throwing an exception if not.

Parameters:

expected - the expected line

actual - the actual line

Throws:

java.lang.IllegalArgumentException - if the actual line is not equivalent to the expected line