Class AbstractPathConnector<E extends AbstractPathConnector.ConnectableElement<E>>
java.lang.Object
org.apache.commons.geometry.euclidean.internal.AbstractPathConnector<E>
- Type Parameters:
E
- Element type
- Direct Known Subclasses:
AbstractGreatArcConnector
,AbstractLinePathConnector
public abstract class AbstractPathConnector<E extends AbstractPathConnector.ConnectableElement<E>>
extends Object
Abstract base class for joining unconnected path elements into connected, directional
paths. The connection algorithm is exposed as a set of protected methods, allowing subclasses
to define their own public API. Implementations must supply their own subclass of
AbstractPathConnector.ConnectableElement
specific for the objects being connected.
The connection algorithm proceeds as follows:
- Create a sorted list of
AbstractPathConnector.ConnectableElement
s. - For each element, attempt to find other elements with start points next the
first instance's end point by calling
AbstractPathConnector.ConnectableElement.getConnectionSearchKey()
and using the returned instance to locate a search start location in the sorted element list. - Search up through the sorted list from the start location, testing each element for possible connectivity
with
AbstractPathConnector.ConnectableElement.canConnectTo(AbstractPathConnector.ConnectableElement)
. Collect possible connections in a list. Terminate the search whenAbstractPathConnector.ConnectableElement.shouldContinueConnectionSearch(AbstractPathConnector.ConnectableElement, boolean)
returns false. - Repeat the previous step searching downward through the list from the start location.
- Select the best connection option from the list of possible connections, using
selectPointConnection(AbstractPathConnector.ConnectableElement, List)
and/orselectConnection(AbstractPathConnector.ConnectableElement, List)
when multiple possibilities are found. - Repeat the above steps for each element. When done, the elements represent a linked list of connected paths.
This class is not thread-safe.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
Class used to represent connectable path elements for use withAbstractPathConnector
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final NavigableSet
<E> List of path elements.private final NavigableSet
<E> View of the path element set in descending order.List used to store possible connections for the current element.List used to store possible point-like (zero-length) connections for the current element. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
addPathElement
(E element) Add a single path element to the connector, leaving it unconnected until a later call to toconnectPathElements(Iterable)
orcomputePathRoots()
.private boolean
addPossibleConnection
(E element, E candidate) Add the candidate to one of the connection lists if it represents a possible connection.Compute all connected paths and return a list of path elements representing the roots (start locations) of each.protected void
connectPathElements
(Iterable<E> elements) Add a collection of path elements to the connector and attempt to connect each new element with previously added ones.private void
findPossibleConnections
(E element) Find possible connections for the given element and place them in thepossibleConnections
andpossiblePointConnections
lists.private void
followForwardConnections
(E start) Find and follow forward connections from the given start element.private E
makeForwardConnection
(E element) Connect the end point of the given element to the start point of another element.protected abstract E
selectConnection
(E incoming, List<E> outgoing) Method called to select a connection to use for a given segment when multiple non-length-zero connections are available.protected E
selectPointConnection
(E incoming, List<E> outgoingList) Method called to select a connection to use for a given element when multiple zero-length connections are available.
-
Field Details
-
pathElements
List of path elements. -
pathElementsDescending
private final NavigableSet<E extends AbstractPathConnector.ConnectableElement<E>> pathElementsDescendingView of the path element set in descending order. -
possibleConnections
List used to store possible connections for the current element. -
possiblePointConnections
List used to store possible point-like (zero-length) connections for the current element.
-
-
Constructor Details
-
AbstractPathConnector
public AbstractPathConnector()
-
-
Method Details
-
connectPathElements
Add a collection of path elements to the connector and attempt to connect each new element with previously added ones.- Parameters:
elements
- path elements to connect
-
addPathElement
Add a single path element to the connector, leaving it unconnected until a later call to toconnectPathElements(Iterable)
orcomputePathRoots()
.- Parameters:
element
- value to add to the connector- See Also:
-
computePathRoots
Compute all connected paths and return a list of path elements representing the roots (start locations) of each. Each returned element is the head of a (possibly circular) linked list that follows a connected path.The connector is reset after this call. Further calls to add elements will result in new paths being generated.
- Returns:
- a list of root elements for the computed connected paths
-
followForwardConnections
Find and follow forward connections from the given start element.- Parameters:
start
- element to begin the connection operation with
-
makeForwardConnection
Connect the end point of the given element to the start point of another element. Returns the newly connected element or null if no forward connection was made.- Parameters:
element
- element to connect- Returns:
- the next element in the path or null if no connection was made
-
findPossibleConnections
Find possible connections for the given element and place them in thepossibleConnections
andpossiblePointConnections
lists.- Parameters:
element
- the element to find connections for
-
addPossibleConnection
Add the candidate to one of the connection lists if it represents a possible connection. Returns true if the candidate was added, otherwise false.- Parameters:
element
- element to check for connections withcandidate
- candidate connection element- Returns:
- true if the candidate is a possible connection
-
selectPointConnection
Method called to select a connection to use for a given element when multiple zero-length connections are available. The algorithm here attempts to choose the point most likely to produce a logical path by selecting the outgoing element with the smallest relative angle with the incoming element, with unconnected element preferred over ones that are already connected (thereby allowing other connections to occur in the path).- Parameters:
incoming
- the incoming elementoutgoingList
- list of available outgoing point-like connections- Returns:
- the connection to use
-
selectConnection
Method called to select a connection to use for a given segment when multiple non-length-zero connections are available. In this case, the selection of the outgoing connection depends only on the desired characteristics of the connected path.- Parameters:
incoming
- the incoming segmentoutgoing
- list of available outgoing connections; will always contain at least two elements- Returns:
- the connection to use
-