Class Line3D

    • Nested Class Summary

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

      Fields 
      Modifier and Type Field Description
      private Vector3D direction
      Line direction.
      private Vector3D origin
      Line point closest to the origin.
      private org.apache.commons.numbers.core.Precision.DoubleEquivalence precision
      Precision context used to compare floating point numbers.
      (package private) static java.lang.String TO_STRING_FORMAT
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      double abscissa​(Vector3D pt)
      Get the abscissa of the given point on the line.
      Vector3D closest​(Line3D line)
      Compute the point of the instance closest to another line.
      boolean contains​(Vector3D pt)
      Check if the instance contains a point.
      double distance​(Line3D line)
      Compute the shortest distance between the instance and another line.
      double distance​(Vector3D pt)
      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 equals​(java.lang.Object obj)
      Vector3D getDirection()
      Get the normalized direction vector.
      Vector3D getOrigin()
      Get the line point closest to the origin.
      org.apache.commons.numbers.core.Precision.DoubleEquivalence getPrecision()
      Get the object used to determine floating point equality for this instance.
      int hashCode()
      Vector3D 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.
      Vector3D pointAt​(double abscissa)
      Get one point from the line.
      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.
      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.
      Line3D reverse()
      Return a line containing the same points as this instance but pointing in the opposite direction.
      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.
      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.
      Segment3D segment​(double a, double b)
      Create a new line segment from the given 1D interval.
      Segment3D segment​(Vector3D a, Vector3D b)
      Create a new line segment from two points.
      LineConvexSubset3D span()
      Return a new infinite line subset representing the entire line.
      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.
      Vector3D toSpace​(double abscissa)
      Get the 3 dimensional point at the given abscissa position on the line.
      Vector3D toSpace​(Vector1D pt)
      Transform a subspace point into a space point.
      java.lang.String toString()
      Vector1D toSubspace​(Vector3D pt)
      Transform a space point into a subspace point.
      Line3D transform​(Transform<Vector3D> transform)
      Transform this instance.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • TO_STRING_FORMAT

        static final java.lang.String TO_STRING_FORMAT
        Format string for creating line string representations.
        See Also:
        Constant Field Values
      • 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 Detail

      • 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 Detail

      • 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:
        transform(Transform)
      • 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:
        toSubspace(Vector3D)
      • 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
      • 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:
        Lines3D.span(Line3D)
      • 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:
        java.lang.IllegalArgumentException - if either of the locations is NaN or infinite
        See Also:
        Lines3D.segmentFromLocations(Line3D, double, double)
      • 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:
        java.lang.IllegalArgumentException - if either point contains NaN or infinite coordinate values
        See Also:
        Lines3D.segmentFromPoints(Line3D, Vector3D, Vector3D)
      • 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:
        java.lang.IllegalArgumentException - if any coordinate in endPoint is NaN or infinite
        See Also:
        Lines3D.reverseRayFromPoint(Line3D, Vector3D)
      • 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:
        java.lang.IllegalArgumentException - if endLocation is NaN or infinite
        See Also:
        Lines3D.reverseRayFromLocation(Line3D, double)
      • 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:
        java.lang.IllegalArgumentException - if any coordinate in startPoint is NaN or infinite
        See Also:
        Lines3D.rayFromPoint(Line3D, Vector3D)
      • 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:
        java.lang.IllegalArgumentException - if startLocation is NaN or infinite
        See Also:
        Lines3D.rayFromLocation(Line3D, double)
      • 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:
        Vector3D.eq(Vector3D, Precision.DoubleEquivalence)
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object