Class Lines

java.lang.Object
org.apache.commons.geometry.euclidean.twod.Lines
public final class Lines extends Object
Class containing factory methods for constructing Line and LineSubset instances.

  • 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 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:
      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:
      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:
      IllegalArgumentException - If direction has zero length, as evaluated by the given precision context
      See Also:

    • 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:
      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:
      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:
      IllegalArgumentException - If lineDirection has zero length, as evaluated by the given precision context
      See Also:

    • 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:
      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:
      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:
      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:
      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:
      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:
      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:
      IllegalArgumentException - if the actual line is not equivalent to the expected line