Class LinePath

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  LinePath.Builder
      Class used to build line paths.
      private static class  LinePath.SimplifiedLinePath
      Internal class returned when a line path is simplified to remove unnecessary line subset divisions.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.List<LineConvexSubset> elements
      The line convex subsets comprising the path.
      private static LinePath EMPTY
      Line path instance containing no elements.
    • Constructor Summary

      Constructors 
      Constructor Description
      LinePath​(java.util.List<LineConvexSubset> elements)
      Simple constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.stream.Stream<LineConvexSubset> boundaryStream()
      Return a stream containing the boundaries for this instance.
      static LinePath.Builder builder​(org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return a LinePath.Builder instance configured with the given precision context.
      static LinePath empty()
      Return a path containing no elements.
      static LinePath from​(java.util.Collection<? extends LineConvexSubset> subsets)
      Build a new path from the given line subsets.
      static LinePath from​(LineConvexSubset... subsets)
      Build a new path from the given line subsets.
      static LinePath fromVertexLoop​(java.util.Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices.
      static LinePath fromVertices​(java.util.Collection<Vector2D> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices.
      static LinePath fromVertices​(java.util.Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Build a new path from the given vertices.
      java.util.List<LineConvexSubset> getElements()
      Get the sequence of line subsets comprising the path.
      LineConvexSubset getEnd()
      Get the line subset at the end of the path or null if the path is empty.
      private Vector2D getEndVertex()
      Get the end vertex for the path or null if the path is empty or has an infinite end line subset.
      double getSize()
      Get the size of the instance.
      LineConvexSubset getStart()
      Get the line subset at the start of the path or null if the path is empty.
      private Vector2D getStartVertex()
      Get the start vertex for the path or null if the path is empty or has an infinite start line subset.
      java.util.List<Vector2D> getVertexSequence()
      Get the sequence of vertices defined by the path.
      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.
      boolean isEmpty()
      Return true if the path does not contain any elements.
      boolean isFinite()
      Return true if the path has a finite size.
      boolean isInfinite()
      Return true if the path has an element with infinite size.
      LinePath reverse()
      Return a new instance with all line subset directions, and their order, reversed.
      LinePath simplify()
      Simplify this path, if possible, by combining adjacent elements that lie on the same line (as determined by Line.equals(Object)).
      java.lang.String toString()
      Return a string representation of the path.
      LinePath transform​(Transform<Vector2D> transform)
      Transform this instance with the argument, returning the result in a new instance.
      • Methods inherited from class java.lang.Object

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

      • EMPTY

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

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

      • LinePath

        LinePath​(java.util.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 Detail

      • getElements

        public java.util.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()
      • 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:
        getStart()
      • getVertexSequence

        public java.util.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 java.lang.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 java.lang.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:
        java.lang.IllegalStateException - if the line subsets do not form a connected path
      • from

        public static LinePath from​(java.util.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:
        java.lang.IllegalStateException - if the subsets do not form a connected path
      • fromVertexLoop

        public static LinePath fromVertexLoop​(java.util.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:
        java.lang.IllegalStateException - if vertices contains only a single unique vertex
        See Also:
        fromVertices(Collection, boolean, Precision.DoubleEquivalence)
      • fromVertices

        public static LinePath fromVertices​(java.util.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:
        java.lang.IllegalStateException - if vertices contains only a single unique vertex
        See Also:
        fromVertices(Collection, boolean, Precision.DoubleEquivalence)
      • fromVertices

        public static LinePath fromVertices​(java.util.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:
        java.lang.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