Class Lines


  • public final class Lines
    extends java.lang.Object
    Class containing factory methods for constructing Line and LineSubset instances.
    • Constructor Detail

      • Lines

        private Lines()
        Utility class; no instantiation.
    • 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 from p1 to p2.
        Parameters:
        p1 - first point
        p2 - second point
        precision - precision context used to compare floating point values
        Returns:
        new line containing p1 and p2 and pointing in the direction from p1 to p2
        Throws:
        java.lang.IllegalArgumentException - If the vector between p1 and p2 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 line
        dir - the direction of the line
        precision - precision context used to compare floating point values
        Returns:
        new line containing pt and pointing in direction dir
        Throws:
        java.lang.IllegalArgumentException - If dir 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 line
        angle - angle of the line with respect to abscissa (x) axis, in radians
        precision - 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 point
        direction - ray direction
        precision - precision context used for floating point comparisons
        Returns:
        a new ray instance with the given start point and direction
        Throws:
        java.lang.IllegalArgumentException - If direction 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 of line. The given point is projected onto the line.
        Parameters:
        line - line for the ray
        startPoint - 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 in startPoint is NaN or infinite
      • rayFromLocation

        public static Ray rayFromLocation​(Line line,
                                          double startLocation)
        Construct a ray starting at the given 1D location on line and continuing in the direction of the line to infinity.
        Parameters:
        line - line for the ray
        startLocation - 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 - if startLocation 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 point
        lineDirection - line direction
        precision - precision context used for floating point comparisons
        Returns:
        a new instance with the given end point and line direction
        Throws:
        java.lang.IllegalArgumentException - If lineDirection 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 of line to the given end point. The point is projected onto the line.
        Parameters:
        line - line for the instance
        endPoint - 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 in endPoint 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 of line to the given 1D end location.
        Parameters:
        line - line for the instance
        endLocation - 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 - if endLocation 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 from startPoint to endPoint.
        Parameters:
        startPoint - segment start point
        endPoint - segment end point
        precision - 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 between startPoint and endPoint 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 of a and b. The points may be given in any order.
        Parameters:
        line - line forming the base of the segment
        a - first point
        b - second point
        Returns:
        a new line segment representing the points between the projected locations of a and b 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 segment
        a - first 1D location on the line
        b - second 1D location on the line
        Returns:
        a new line segment representing the points between a and b 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 a LineConvexSubset 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 subset
        interval - 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 call Lines.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 subset
        a - first 1D location on the line
        b - 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 line
        actual - the actual line
        Throws:
        java.lang.IllegalArgumentException - if the actual line is not equivalent to the expected line