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 constructingLine
andLineSubset
instances.
-
-
Constructor Summary
Constructors Modifier Constructor Description private
Lines()
Utility class; no instantiation.
-
Method Summary
All Methods Static Methods Concrete Methods 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 online
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 ofline
.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 ofline
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 ofline
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 aLineConvexSubset
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.
-
-
-
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 fromp1
top2
.- Parameters:
p1
- first pointp2
- second pointprecision
- precision context used to compare floating point values- Returns:
- new line containing
p1
andp2
and pointing in the direction fromp1
top2
- Throws:
java.lang.IllegalArgumentException
- If the vector betweenp1
andp2
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 linedir
- the direction of the lineprecision
- precision context used to compare floating point values- Returns:
- new line containing
pt
and pointing in directiondir
- Throws:
java.lang.IllegalArgumentException
- Ifdir
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 lineangle
- angle of the line with respect to abscissa (x) axis, in radiansprecision
- 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 pointdirection
- ray directionprecision
- precision context used for floating point comparisons- Returns:
- a new ray instance with the given start point and direction
- Throws:
java.lang.IllegalArgumentException
- Ifdirection
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 ofline
. The given point is projected onto the line.- Parameters:
line
- line for the raystartPoint
- 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 instartPoint
is NaN or infinite
-
rayFromLocation
public static Ray rayFromLocation(Line line, double startLocation)
Construct a ray starting at the given 1D location online
and continuing in the direction of the line to infinity.- Parameters:
line
- line for the raystartLocation
- 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
- ifstartLocation
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 pointlineDirection
- line directionprecision
- precision context used for floating point comparisons- Returns:
- a new instance with the given end point and line direction
- Throws:
java.lang.IllegalArgumentException
- IflineDirection
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 ofline
to the given end point. The point is projected onto the line.- Parameters:
line
- line for the instanceendPoint
- 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 inendPoint
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 ofline
to the given 1D end location.- Parameters:
line
- line for the instanceendLocation
- 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
- ifendLocation
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 fromstartPoint
toendPoint
.- Parameters:
startPoint
- segment start pointendPoint
- segment end pointprecision
- 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 betweenstartPoint
andendPoint
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 ofa
andb
. The points may be given in any order.- Parameters:
line
- line forming the base of the segmenta
- first pointb
- second point- Returns:
- a new line segment representing the points between the projected locations of
a
andb
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 segmenta
- first 1D location on the lineb
- second 1D location on the line- Returns:
- a new line segment representing the points between
a
andb
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 aLineConvexSubset
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 subsetinterval
- 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 callLines.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 subseta
- first 1D location on the lineb
- 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 lineactual
- the actual line- Throws:
java.lang.IllegalArgumentException
- if the actual line is not equivalent to the expected line
-
-