java.lang.Object
org.apache.commons.geometry.euclidean.threed.line.Line3D
All Implemented Interfaces:
Embedding<Vector3D,Vector1D>

public final class Line3D extends Object implements Embedding<Vector3D,Vector1D>
Class representing a line in 3D space.

Instances of this class are guaranteed to be immutable.

See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Class containing a transformed line instance along with a subspace (1D) transform.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private 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
    Constructor
    Description
    Line3D(Vector3D origin, Vector3D direction, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Simple constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    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
    eq(Line3D other, org.apache.commons.numbers.core.Precision.DoubleEquivalence ctx)
    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
    Get the intersection point of the instance and another line.
    boolean
    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.
    rayFrom(Vector3D startPoint)
    Create a new ray instance that starts at the projection of the given point and continues in the direction of the line to infinity.
    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.
    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.
    Return a new infinite line subset representing the entire line.
    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.
    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

      static final String TO_STRING_FORMAT
      Format string for creating line string representations.
      See Also:
    • origin

      private final Vector3D origin
      Line point closest to the origin.
    • direction

      private final Vector3D direction
      Line direction.
    • precision

      private final org.apache.commons.numbers.core.Precision.DoubleEquivalence precision
      Precision 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 space
      direction - the direction of the line
      precision - precision context used to compare floating point numbers
  • Method Details

    • getOrigin

      public Vector3D getOrigin()
      Get the line point closest to the origin.
      Returns:
      line point closest to the origin
    • getDirection

      public Vector3D 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

      public Line3D 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

      public Line3D transform(Transform<Vector3D> transform)
      Transform this instance.
      Parameters:
      transform - object used to transform the instance
      Returns:
      a transformed instance
    • subspaceTransform

      public Line3D.SubspaceTransform 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. 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 points a (which was transformed using the original 3D transform) and b (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

      public double abscissa(Vector3D pt)
      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 to toSubspace(Vector3D) except that this method returns a double instead of a Vector1D.
      Parameters:
      pt - point to compute the abscissa for
      Returns:
      abscissa value of the point
      See Also:
    • pointAt

      public Vector3D pointAt(double abscissa)
      Get one point from the line.
      Parameters:
      abscissa - desired abscissa for the point
      Returns:
      one point belonging to the line, at specified abscissa
    • toSubspace

      public Vector1D toSubspace(Vector3D pt)
      Transform a space point into a subspace point.
      Specified by:
      toSubspace in interface Embedding<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

      public Vector3D toSpace(Vector1D pt)
      Transform a subspace point into a space point.
      Specified by:
      toSpace in interface Embedding<Vector3D,Vector1D>
      Parameters:
      pt - lower-dimension point of the subspace
      Returns:
      n-dimension point of the space corresponding to the specified subspace point
      See Also:
    • toSpace

      public Vector3D toSpace(double abscissa)
      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

      public boolean isSimilarTo(Line3D line)
      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

      public boolean contains(Vector3D pt)
      Check if the instance contains a point.
      Parameters:
      pt - point to check
      Returns:
      true if p belongs to the line
    • distance

      public double distance(Vector3D pt)
      Compute the distance between the instance and a point.
      Parameters:
      pt - to check
      Returns:
      distance between the instance and the point
    • distance

      public double distance(Line3D line)
      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

      public Vector3D closest(Line3D line)
      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

      public Vector3D intersection(Line3D line)
      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

      public LineConvexSubset3D span()
      Return a new infinite line subset representing the entire line.
      Returns:
      a new infinite line subset representing the entire line
      See Also:
    • segment

      public Segment3D segment(double a, double b)
      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 interval
      b - 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

      public Segment3D segment(Vector3D a, Vector3D b)
      Create a new line segment from two points. The returned segment represents all points on this line between the projected locations of a and b. The points may be given in any order.
      Parameters:
      a - first point
      b - second point
      Returns:
      a new line segment on this line
      Throws:
      IllegalArgumentException - if either point contains NaN or infinite coordinate values
      See Also:
    • reverseRayTo

      public ReverseRay3D 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.
      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 in endPoint is NaN or infinite
      See Also:
    • reverseRayTo

      public ReverseRay3D reverseRayTo(double endLocation)
      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 - if endLocation is NaN or infinite
      See Also:
    • rayFrom

      public Ray3D rayFrom(Vector3D startPoint)
      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 in startPoint is NaN or infinite
      See Also:
    • rayFrom

      public Ray3D 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.
      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 - if startLocation is NaN or infinite
      See Also:
    • eq

      public boolean eq(Line3D other, org.apache.commons.numbers.core.Precision.DoubleEquivalence ctx)
      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 equivalent origins and directions.
      Parameters:
      other - the point to compare with
      ctx - 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()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object