java.lang.Object
org.apache.commons.geometry.euclidean.twod.path.LinePath
All Implemented Interfaces:
BoundarySource<LineConvexSubset>, Sized, BoundarySource2D, Linecastable2D
Direct Known Subclasses:
LinePath.SimplifiedLinePath

public class LinePath extends Object implements BoundarySource2D, Sized
Class representing a connected path of line convex subsets. The elements in the path are connected end to end, with the end vertex of the previous element equivalent to the start vertex of the next element. Elements are not required to be finite. However, since path elements are connected, only the first element and/or last element may be infinite.

Instances of this class are guaranteed to be immutable.

  • Field Details

    • EMPTY

      private static final LinePath EMPTY
      Line path instance containing no elements.
    • elements

      private final List<LineConvexSubset> elements
      The line convex subsets comprising the path.
  • Constructor Details

    • LinePath

      LinePath(List<LineConvexSubset> elements)
      Simple constructor. Callers are responsible for ensuring that the given list of line subsets defines a valid path. No validation is performed.
      Parameters:
      elements - elements defining the path.
  • Method Details

    • boundaryStream

      public Stream<LineConvexSubset> boundaryStream()
      Return a stream containing the boundaries for this instance.
      Specified by:
      boundaryStream in interface BoundarySource<LineConvexSubset>
      Returns:
      a stream containing the boundaries for this instance
    • getElements

      public List<LineConvexSubset> getElements()
      Get the sequence of line subsets comprising the path.
      Returns:
      the sequence of line subsets comprising the path
    • getStart

      public LineConvexSubset getStart()
      Get the line subset at the start of the path or null if the path is empty. If the path consists of a single line subset, then the returned instance with be the same as that returned by getEnd().
      Returns:
      the line subset at the start of the path or null if the path is empty
      See Also:
    • getEnd

      public LineConvexSubset getEnd()
      Get the line subset at the end of the path or null if the path is empty. If the path consists of a single line subset, then the returned instance with be the same as that returned by getStart().
      Returns:
      the line subset at the end of the path or null if the path is empty
      See Also:
    • getVertexSequence

      public List<Vector2D> getVertexSequence()
      Get the sequence of vertices defined by the path. Vertices appear in the list as many times as they are visited in the path. For example, the vertex sequence for a closed path contains the start point at the beginning of the list as well as the end.
      Returns:
      the sequence of vertices defined by the path
    • isInfinite

      public boolean isInfinite()
      Return true if the path has an element with infinite size.
      Specified by:
      isInfinite in interface Sized
      Returns:
      true if the path is infinite
    • isFinite

      public boolean isFinite()
      Return true if the path has a finite size. This will be true if there are no elements in the path or if all elements have a finite length.
      Specified by:
      isFinite in interface Sized
      Returns:
      true if the path is finite
    • getSize

      public double getSize()
      Get the size of the instance.

      The size of the path is defined as the sum of the sizes (lengths) of all path elements.

      Specified by:
      getSize in interface Sized
      Returns:
      the size of the instance
    • isEmpty

      public boolean isEmpty()
      Return true if the path does not contain any elements.
      Returns:
      true if the path does not contain any elements
    • isClosed

      public boolean isClosed()
      Return true if the path is closed, meaning that the end point for the last element is equivalent to the start point of the first.
      Returns:
      true if the end point for the last element is equivalent to the start point for the first
    • transform

      public LinePath transform(Transform<Vector2D> transform)
      Transform this instance with the argument, returning the result in a new instance.
      Parameters:
      transform - the transform to apply
      Returns:
      a new instance, transformed by the argument
    • reverse

      public LinePath reverse()
      Return a new instance with all line subset directions, and their order, reversed. The last line subset in this instance will be the first in the returned instance.
      Returns:
      a new instance with the path reversed
    • simplify

      public LinePath simplify()
      Simplify this path, if possible, by combining adjacent elements that lie on the same line (as determined by Line.equals(Object)).
      Returns:
      a simplified instance
    • toString

      public String toString()
      Return a string representation of the path.

      In order to keep the string representation short but useful, the exact format of the return value depends on the properties of the path. See below for examples.

      • Empty path
        • LinePath[empty= true]
      • Single element
        • LinePath[single= Segment[startPoint= (0.0, 0.0), endPoint= (1.0, 0.0)]]
      • Path with infinite start element
        • LinePath[startDirection= (1.0, 0.0), vertices= [(1.0, 0.0), (1.0, 1.0)]]
      • Path with infinite end element
        • LinePath[vertices= [(0.0, 1.0), (0.0, 0.0)], endDirection= (1.0, 0.0)]
      • Path with infinite start and end elements
        • LinePath[startDirection= (0.0, 1.0), vertices= [(0.0, 0.0)], endDirection= (1.0, 0.0)]
      • Path with no infinite elements
        • LinePath[vertices= [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0)]]
      Overrides:
      toString in class Object
    • getStartVertex

      private Vector2D getStartVertex()
      Get the start vertex for the path or null if the path is empty or has an infinite start line subset.
      Returns:
      the start vertex for the path or null if the path does not start with a vertex
    • getEndVertex

      private Vector2D getEndVertex()
      Get the end vertex for the path or null if the path is empty or has an infinite end line subset.
      Returns:
      the end vertex for the path or null if the path does not end with a vertex
    • from

      public static LinePath from(LineConvexSubset... subsets)
      Build a new path from the given line subsets.
      Parameters:
      subsets - the line subsets to comprise the path
      Returns:
      new path containing the given line subsets in order
      Throws:
      IllegalStateException - if the line subsets do not form a connected path
    • from

      public static LinePath from(Collection<? extends LineConvexSubset> subsets)
      Build a new path from the given line subsets.
      Parameters:
      subsets - the line subsets to comprise the path
      Returns:
      new path containing the given line subsets in order
      Throws:
      IllegalStateException - if the subsets do not form a connected path
    • fromVertexLoop

      public static LinePath fromVertexLoop(Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices. A line segment is created from the last vertex to the first one, if the two vertices are not already considered equal using the given precision context. This method is equivalent to calling fromVertices(vertices, true, precision)
      Parameters:
      vertices - the vertices to construct the closed path from
      precision - precision context used to construct the line segment instances for the path
      Returns:
      new closed path constructed from the given vertices
      Throws:
      IllegalStateException - if vertices contains only a single unique vertex
      See Also:
    • fromVertices

      public static LinePath fromVertices(Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices. No additional segment is added from the last vertex to the first. This method is equivalent to calling fromVertices(vertices, false, precision).
      Parameters:
      vertices - the vertices to construct the path from
      precision - precision context used to construct the line segment instances for the path
      Returns:
      new path constructed from the given vertices
      Throws:
      IllegalStateException - if vertices contains only a single unique vertex
      See Also:
    • fromVertices

      public static LinePath fromVertices(Collection<Vector2D> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices.
      Parameters:
      vertices - the vertices to construct the path from
      close - if true, a line segment is created from the last vertex given to the first one, if the two vertices are not already considered equal using the given precision context.
      precision - precision context used to construct the line segment instances for the path
      Returns:
      new path constructed from the given vertices
      Throws:
      IllegalStateException - if vertices contains only a single unique vertex
    • empty

      public static LinePath empty()
      Return a path containing no elements.
      Returns:
      a path containing no elements
    • builder

      public static LinePath.Builder builder(org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return a LinePath.Builder instance configured with the given precision context. The precision context is used when building line segments from vertices and may be omitted if raw vertices are not used.
      Parameters:
      precision - precision context to use when building line segments from raw vertices; may be null if raw vertices are not used.
      Returns:
      a new LinePath.Builder instance