Class Line3D
java.lang.Object
org.apache.commons.geometry.euclidean.threed.line.Line3D
Class representing a line in 3D space.
Instances of this class are guaranteed to be immutable.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Class containing a transformed line instance along with a subspace (1D) transform. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Vector3D
Line direction.private final Vector3D
Line point closest to the origin.private final org.apache.commons.numbers.core.Precision.DoubleEquivalence
Precision context used to compare floating point numbers.(package private) static final String
Format string for creating line string representations. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptiondouble
Get the abscissa of the given point on the line.Compute the point of the instance closest to another line.boolean
Check if the instance contains a point.double
Compute the shortest distance between the instance and another line.double
Compute the distance between the instance and a point.boolean
Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison.boolean
Get the normalized direction vector.Get the line point closest to the origin.org.apache.commons.numbers.core.Precision.DoubleEquivalence
Get the object used to determine floating point equality for this instance.int
hashCode()
intersection
(Line3D line) Get the intersection point of the instance and another line.boolean
isSimilarTo
(Line3D line) Check if the instance is similar to another line.pointAt
(double abscissa) Get one point from the line.rayFrom
(double startLocation) Create a new ray instance that starts at the given 1D location and continues in the direction of the line to infinity.Create a new ray instance that starts at the projection of the given point and continues in the direction of the line to infinity.reverse()
Return a line containing the same points as this instance but pointing in the opposite direction.reverseRayTo
(double endLocation) Create a new line convex subset that starts at infinity and continues along the line up to the given 1D location.reverseRayTo
(Vector3D endPoint) Create a new line convex subset that starts at infinity and continues along the line up to the projection of the given end point.segment
(double a, double b) Create a new line segment from the given 1D interval.Create a new line segment from two points.span()
Return a new infinite line subset representing the entire line.subspaceTransform
(Transform<Vector3D> transform) Get an object containing the current line transformed by the argument along with a 1D transform that can be applied to subspace points.toSpace
(double abscissa) Get the 3 dimensional point at the given abscissa position on the line.Transform a subspace point into a space point.toString()
toSubspace
(Vector3D pt) Transform a space point into a subspace point.Transform this instance.Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.commons.geometry.core.Embedding
toSpace, toSubspace
-
Field Details
-
TO_STRING_FORMAT
Format string for creating line string representations.- See Also:
-
origin
Line point closest to the origin. -
direction
Line direction. -
precision
private final org.apache.commons.numbers.core.Precision.DoubleEquivalence precisionPrecision context used to compare floating point numbers.
-
-
Constructor Details
-
Line3D
Line3D(Vector3D origin, Vector3D direction, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Simple constructor.- Parameters:
origin
- the origin of the line, meaning the point on the line closest to the origin of the 3D spacedirection
- the direction of the lineprecision
- precision context used to compare floating point numbers
-
-
Method Details
-
getOrigin
Get the line point closest to the origin.- Returns:
- line point closest to the origin
-
getDirection
Get the normalized direction vector.- Returns:
- normalized direction vector
-
getPrecision
public org.apache.commons.numbers.core.Precision.DoubleEquivalence getPrecision()Get the object used to determine floating point equality for this instance.- Returns:
- the floating point precision context for the instance
-
reverse
Return a line containing the same points as this instance but pointing in the opposite direction.- Returns:
- an instance containing the same points but pointing in the opposite direction
-
transform
Transform this instance.- Parameters:
transform
- object used to transform the instance- Returns:
- a transformed instance
-
subspaceTransform
Get an object containing the current line transformed by the argument along with a 1D transform that can be applied to subspace points. The subspace transform transforms subspace points such that their 3D location in the transformed line is the same as their 3D location in the original line after the 3D transform is applied. For example, consider the code below:SubspaceTransform st = line.subspaceTransform(transform); Vector1D subPt = Vector1D.of(1); Vector3D a = transform.apply(line.toSpace(subPt)); // transform in 3D space Vector3D b = st.getLine().toSpace(st.getTransform().apply(subPt)); // transform in 1D space
At the end of execution, the pointsa
(which was transformed using the original 3D transform) andb
(which was transformed in 1D using the subspace transform) are equivalent.- Parameters:
transform
- the transform to apply to this instance- Returns:
- an object containing the transformed line along with a transform that can be applied to subspace points
- See Also:
-
abscissa
Get the abscissa of the given point on the line. The abscissa represents the distance the projection of the point on the line is from the line's origin point (the point on the line closest to the origin of the 2D space). Abscissa values increase in the direction of the line. This method is exactly equivalent totoSubspace(Vector3D)
except that this method returns a double instead of aVector1D
.- Parameters:
pt
- point to compute the abscissa for- Returns:
- abscissa value of the point
- See Also:
-
pointAt
Get one point from the line.- Parameters:
abscissa
- desired abscissa for the point- Returns:
- one point belonging to the line, at specified abscissa
-
toSubspace
Transform a space point into a subspace point.- Specified by:
toSubspace
in interfaceEmbedding<Vector3D,
Vector1D> - Parameters:
pt
- n-dimension point of the space- Returns:
- lower-dimension point of the subspace corresponding to the specified space point
- See Also:
-
toSpace
Transform a subspace point into a space point. -
toSpace
Get the 3 dimensional point at the given abscissa position on the line.- Parameters:
abscissa
- location on the line- Returns:
- the 3 dimensional point at the given abscissa position on the line
-
isSimilarTo
Check if the instance is similar to another line.Lines are considered similar if they contain the same points. This does not mean they are equal since they can have opposite directions.
- Parameters:
line
- line to which instance should be compared- Returns:
- true if the lines are similar
-
contains
Check if the instance contains a point.- Parameters:
pt
- point to check- Returns:
- true if p belongs to the line
-
distance
Compute the distance between the instance and a point.- Parameters:
pt
- to check- Returns:
- distance between the instance and the point
-
distance
Compute the shortest distance between the instance and another line.- Parameters:
line
- line to check against the instance- Returns:
- shortest distance between the instance and the line
-
closest
Compute the point of the instance closest to another line.- Parameters:
line
- line to check against the instance- Returns:
- point of the instance closest to another line
-
intersection
Get the intersection point of the instance and another line.- Parameters:
line
- other line- Returns:
- intersection point of the instance and the other line or null if there are no intersection points
-
span
Return a new infinite line subset representing the entire line.- Returns:
- a new infinite line subset representing the entire line
- See Also:
-
segment
Create a new line segment from the given 1D interval. The returned line segment consists of all points between the two locations, regardless of the order the arguments are given.- Parameters:
a
- first 1D location for the intervalb
- second 1D location for the interval- Returns:
- a new line segment on this line
- Throws:
IllegalArgumentException
- if either of the locations is NaN or infinite- See Also:
-
segment
Create a new line segment from two points. The returned segment represents all points on this line between the projected locations ofa
andb
. The points may be given in any order.- Parameters:
a
- first pointb
- second point- Returns:
- a new line segment on this line
- Throws:
IllegalArgumentException
- if either point contains NaN or infinite coordinate values- See Also:
-
reverseRayTo
Create a new line convex subset that starts at infinity and continues along the line up to the projection of the given end point.- Parameters:
endPoint
- point defining the end point of the line subset; the end point is equal to the projection of this point onto the line- Returns:
- a new, half-open line subset that ends at the given point
- Throws:
IllegalArgumentException
- if any coordinate inendPoint
is NaN or infinite- See Also:
-
reverseRayTo
Create a new line convex subset that starts at infinity and continues along the line up to the given 1D location.- Parameters:
endLocation
- the 1D location of the end of the half-line- Returns:
- a new, half-open line subset that ends at the given 1D location
- Throws:
IllegalArgumentException
- ifendLocation
is NaN or infinite- See Also:
-
rayFrom
Create a new ray instance that starts at the projection of the given point and continues in the direction of the line to infinity.- Parameters:
startPoint
- point defining the start point of the ray; the start point is equal to the projection of this point onto the line- Returns:
- a ray starting at the projected point and extending along this line to infinity
- Throws:
IllegalArgumentException
- if any coordinate instartPoint
is NaN or infinite- See Also:
-
rayFrom
Create a new ray instance that starts at the given 1D location and continues in the direction of the line to infinity.- Parameters:
startLocation
- 1D location defining the start point of the ray- Returns:
- a ray starting at the given 1D location and extending along this line to infinity
- Throws:
IllegalArgumentException
- ifstartLocation
is NaN or infinite- See Also:
-
eq
Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison. Instances are considered equivalent if they have equivalentorigin
s anddirection
s.- Parameters:
other
- the point to compare withctx
- precision context to use for the comparison- Returns:
- true if this instance should be considered equivalent to the argument
- See Also:
-
hashCode
public int hashCode() -
equals
-
toString
-