Class LinePath
java.lang.Object
org.apache.commons.geometry.euclidean.twod.path.LinePath
- All Implemented Interfaces:
BoundarySource<LineConvexSubset>
,Sized
,BoundarySource2D
,Linecastable2D
- Direct Known Subclasses:
LinePath.SimplifiedLinePath
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Class used to build line paths.private static final class
Internal class returned when a line path is simplified to remove unnecessary line subset divisions. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final List
<LineConvexSubset> The line convex subsets comprising the path.private static final LinePath
Line path instance containing no elements. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionReturn a stream containing the boundaries for this instance.static LinePath.Builder
builder
(org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return aLinePath.Builder
instance configured with the given precision context.static LinePath
empty()
Return a path containing no elements.static LinePath
from
(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
(Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a new path from the given vertices.static LinePath
fromVertices
(Collection<Vector2D> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a new path from the given vertices.static LinePath
fromVertices
(Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a new path from the given vertices.Get the sequence of line subsets comprising the path.getEnd()
Get the line subset at the end of the path or null if the path is empty.private Vector2D
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.getStart()
Get the line subset at the start of the path or null if the path is empty.private Vector2D
Get the start vertex for the path or null if the path is empty or has an infinite start line subset.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
Return true if the path has an element with infinite size.reverse()
Return a new instance with all line subset directions, and their order, reversed.simplify()
Simplify this path, if possible, by combining adjacent elements that lie on the same line (as determined byLine.equals(Object)
).toString()
Return a string representation of the path.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
Methods inherited from interface org.apache.commons.geometry.euclidean.twod.BoundarySource2D
getBounds, linecast, linecastFirst, toList, toTree
Methods inherited from interface org.apache.commons.geometry.euclidean.twod.Linecastable2D
linecast, linecastFirst
-
Field Details
-
EMPTY
Line path instance containing no elements. -
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
Return a stream containing the boundaries for this instance.- Specified by:
boundaryStream
in interfaceBoundarySource<LineConvexSubset>
- Returns:
- a stream containing the boundaries for this instance
-
getElements
Get the sequence of line subsets comprising the path.- Returns:
- the sequence of line subsets comprising the path
-
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 bygetEnd()
.- Returns:
- the line subset at the start of the path or null if the path is empty
- See Also:
-
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 bygetStart()
.- Returns:
- the line subset at the end of the path or null if the path is empty
- See Also:
-
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 interfaceSized
- 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. -
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.
-
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
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
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
Simplify this path, if possible, by combining adjacent elements that lie on the same line (as determined byLine.equals(Object)
).- Returns:
- a simplified instance
-
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)]]
- Empty path
-
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
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
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
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 callingfromVertices(vertices, true, precision)
- Parameters:
vertices
- the vertices to construct the closed path fromprecision
- precision context used to construct the line segment instances for the path- Returns:
- new closed path constructed from the given vertices
- Throws:
IllegalStateException
- ifvertices
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 callingfromVertices(vertices, false, precision)
.- Parameters:
vertices
- the vertices to construct the path fromprecision
- precision context used to construct the line segment instances for the path- Returns:
- new path constructed from the given vertices
- Throws:
IllegalStateException
- ifvertices
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 fromclose
- 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
- ifvertices
contains only a single unique vertex
-
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 aLinePath.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
-