Class Lines
java.lang.Object
org.apache.commons.geometry.euclidean.twod.Lines
Class containing factory methods for constructing
Line
and LineSubset
instances.-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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
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.
-
Constructor Details
-
Lines
private Lines()Utility class; no instantiation.
-
-
Method Details
-
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:
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:
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:
IllegalArgumentException
- Ifdirection
has zero length, as evaluated by the given precision context- See Also:
-
rayFromPoint
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:
IllegalArgumentException
- if any coordinate instartPoint
is NaN or infinite
-
rayFromLocation
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:
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:
IllegalArgumentException
- IflineDirection
has zero length, as evaluated by the given precision context- See Also:
-
reverseRayFromPoint
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:
IllegalArgumentException
- if any coordinate inendPoint
is NaN or infinite
-
reverseRayFromLocation
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:
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:
IllegalArgumentException
- If the vector betweenstartPoint
andendPoint
has zero length, as evaluated by the given precision context
-
segmentFromPoints
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:
IllegalArgumentException
- if either point contains NaN or infinite coordinate values
-
segmentFromLocations
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:
IllegalArgumentException
- if either of the locations is NaN or infinite
-
span
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
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
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:
IllegalArgumentException
- if either double value is NaN or both are infinite with the same sign (eg, both positive infinity or both negative infinity)
-
validateLinesEquivalent
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:
IllegalArgumentException
- if the actual line is not equivalent to the expected line
-