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
public class LinePath extends java.lang.Object implements BoundarySource2D, Sized
Class representing a connected path ofline 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 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 aLinePath.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 byLine.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
-
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 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
-
boundaryStream
public java.util.stream.Stream<LineConvexSubset> 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
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 bygetEnd()
.- 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 bygetStart()
.- 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 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
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 byLine.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 classjava.lang.Object
- Empty path
-
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 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:
java.lang.IllegalStateException
- ifvertices
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 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:
java.lang.IllegalStateException
- ifvertices
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 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:
java.lang.IllegalStateException
- ifvertices
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 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
-
-