Class LinePath.Builder

  • Enclosing class:
    LinePath

    public static final class LinePath.Builder
    extends java.lang.Object
    Class used to build line paths.
    • Field Detail

      • appended

        private java.util.List<LineConvexSubset> appended
        Line subsets appended to the path.
      • prepended

        private java.util.List<LineConvexSubset> prepended
        Line subsets prepended to the path.
      • precision

        private org.apache.commons.numbers.core.Precision.DoubleEquivalence precision
        Precision context used when creating line segments directly from vertices.
      • startVertex

        private Vector2D startVertex
        The current vertex at the start of the path.
      • endVertex

        private Vector2D endVertex
        The current vertex at the end of the path.
      • endVertexPrecision

        private org.apache.commons.numbers.core.Precision.DoubleEquivalence endVertexPrecision
        The precision context used when performing comparisons involving the current end vertex.
    • Constructor Detail

      • Builder

        private Builder​(org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a new 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 creating line segments from vertices
    • Method Detail

      • setPrecision

        public LinePath.Builder setPrecision​(org.apache.commons.numbers.core.Precision.DoubleEquivalence builderPrecision)
        Set the precision context. This context is used only when creating line segments from appended or prepended vertices. It is not used when adding existing LineConvexSubset instances since those contain their own precision contexts.
        Parameters:
        builderPrecision - precision context to use when creating line segments from vertices
        Returns:
        this instance
      • getStart

        public LineConvexSubset getStart()
        Get the line subset at the start of the path or null if it does not exist.
        Returns:
        the line subset at the start of the path
      • getEnd

        public LineConvexSubset getEnd()
        Get the line subset at the end of the path or null if it does not exist.
        Returns:
        the line subset at the end of the path
      • append

        public LinePath.Builder append​(LineConvexSubset subset)
        Append a line subset to the end of the path.
        Parameters:
        subset - line subset to append to the path
        Returns:
        the current builder instance
        Throws:
        java.lang.IllegalStateException - if the path contains a previous element and the end vertex of the previous element is not equivalent to the start vertex of the argument
      • append

        public LinePath.Builder append​(Vector2D vertex)
        Add a vertex to the end of this path. If the path already has an end vertex, then a line segment is added between the previous end vertex and this vertex, using the configured precision context.
        Parameters:
        vertex - the vertex to add
        Returns:
        this instance
        See Also:
        setPrecision(Precision.DoubleEquivalence)
      • appendVertices

        public LinePath.Builder appendVertices​(java.util.Collection<? extends Vector2D> vertices)
        Convenience method for appending a collection of vertices to the path in a single method call.
        Parameters:
        vertices - the vertices to append
        Returns:
        this instance
        See Also:
        append(Vector2D)
      • appendVertices

        public LinePath.Builder appendVertices​(Vector2D... vertices)
        Convenience method for appending multiple vertices to the path at once.
        Parameters:
        vertices - the vertices to append
        Returns:
        this instance
        See Also:
        append(Vector2D)
      • prepend

        public LinePath.Builder prepend​(LineConvexSubset subset)
        Prepend a line subset to the beginning of the path.
        Parameters:
        subset - line subset to prepend to the path
        Returns:
        the current builder instance
        Throws:
        java.lang.IllegalStateException - if the path contains a start element and the end vertex of the argument is not equivalent to the start vertex of the start element.
      • prepend

        public LinePath.Builder prepend​(Vector2D vertex)
        Add a vertex to the front of this path. If the path already has a start vertex, then a line segment is added between this vertex and the previous start vertex, using the configured precision context.
        Parameters:
        vertex - the vertex to add
        Returns:
        this instance
        See Also:
        setPrecision(Precision.DoubleEquivalence)
      • prependVertices

        public LinePath.Builder prependVertices​(java.util.Collection<Vector2D> vertices)
        Convenience method for prepending a collection of vertices to the path in a single method call. The vertices are logically prepended as a single group, meaning that the first vertex in the given collection appears as the first vertex in the path after this method call. Internally, this means that the vertices are actually passed to the prepend(Vector2D) method in reverse order.
        Parameters:
        vertices - the vertices to prepend
        Returns:
        this instance
        See Also:
        prepend(Vector2D)
      • prependVertices

        public LinePath.Builder prependVertices​(Vector2D... vertices)
        Convenience method for prepending multiple vertices to the path in a single method call. The vertices are logically prepended as a single group, meaning that the first vertex in the given collection appears as the first vertex in the path after this method call. Internally, this means that the vertices are actually passed to the prepend(Vector2D) method in reverse order.
        Parameters:
        vertices - the vertices to prepend
        Returns:
        this instance
        See Also:
        prepend(Vector2D)
      • close

        public LinePath close()
        Close the current path and build a new LinePath instance. This method is equivalent to builder.build(true).
        Returns:
        new closed path instance
        Throws:
        java.lang.IllegalStateException - if the builder was given only a single unique vertex
      • build

        public LinePath build()
        Build a LinePath instance from the configured path. This method is equivalent to builder.build(false).
        Returns:
        new path instance
        Throws:
        java.lang.IllegalStateException - if the builder was given only a single unique vertex
      • build

        public LinePath build​(boolean close)
        Build a LinePath instance from the configured path.
        Parameters:
        close - if true, the path will be closed by adding an end point equivalent to the start point
        Returns:
        new path instance
        Throws:
        java.lang.IllegalStateException - if the builder was given only a single unique vertex
      • closePath

        private void closePath()
        Close the path by adding an end point equivalent to the path start point.
        Throws:
        java.lang.IllegalStateException - if the path cannot be closed
      • validateConnected

        private void validateConnected​(LineConvexSubset previous,
                                       LineConvexSubset next)
        Validate that the given line subsets are connected, meaning that the end vertex of previous is equivalent to the start vertex of next. The line subsets are considered valid if either line subset is null.
        Parameters:
        previous - previous line subset
        next - next line subset
        Throws:
        java.lang.IllegalStateException - if previous and next are not null and the end vertex of previous is not equivalent the start vertex of next
      • getAddVertexPrecision

        private org.apache.commons.numbers.core.Precision.DoubleEquivalence getAddVertexPrecision()
        Get the precision context used when adding raw vertices to the path. An exception is thrown if no precision has been specified.
        Returns:
        the precision context used when creating working with raw vertices
        Throws:
        java.lang.IllegalStateException - if no precision context is configured
      • appendInternal

        private void appendInternal​(LineConvexSubset subset)
        Append the given, validated line subsets to the path.
        Parameters:
        subset - validated line subset to append
      • prependInternal

        private void prependInternal​(LineConvexSubset subset)
        Prepend the given, validated line subset to the path.
        Parameters:
        subset - validated line subset to prepend
      • getFirst

        private LineConvexSubset getFirst​(java.util.List<? extends LineConvexSubset> list)
        Get the first element in the list or null if the list is null or empty.
        Parameters:
        list - the list to return the first item from
        Returns:
        the first item from the given list or null if it does not exist
      • getLast

        private LineConvexSubset getLast​(java.util.List<? extends LineConvexSubset> list)
        Get the last element in the list or null if the list is null or empty.
        Parameters:
        list - the list to return the last item from
        Returns:
        the last item from the given list or null if it does not exist