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 java.lang.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 ofAbstractPathConnector.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:
AbstractPathConnector.ConnectableElement
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
AbstractPathConnector.ConnectableElement<E extends AbstractPathConnector.ConnectableElement<E>>
Class used to represent connectable path elements for use withAbstractPathConnector
.
-
Field Summary
Fields Modifier and Type Field Description private java.util.NavigableSet<E>
pathElements
List of path elements.private java.util.NavigableSet<E>
pathElementsDescending
View of the path element set in descending order.private java.util.List<E>
possibleConnections
List used to store possible connections for the current element.private java.util.List<E>
possiblePointConnections
List used to store possible point-like (zero-length) connections for the current element.
-
Constructor Summary
Constructors Constructor Description AbstractPathConnector()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected 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.protected java.util.List<E>
computePathRoots()
Compute all connected paths and return a list of path elements representing the roots (start locations) of each.protected void
connectPathElements(java.lang.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, java.util.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, java.util.List<E> outgoingList)
Method called to select a connection to use for a given element when multiple zero-length connections are available.
-
-
-
Field Detail
-
pathElements
private final java.util.NavigableSet<E extends AbstractPathConnector.ConnectableElement<E>> pathElements
List of path elements.
-
pathElementsDescending
private final java.util.NavigableSet<E extends AbstractPathConnector.ConnectableElement<E>> pathElementsDescending
View of the path element set in descending order.
-
possibleConnections
private final java.util.List<E extends AbstractPathConnector.ConnectableElement<E>> possibleConnections
List used to store possible connections for the current element.
-
possiblePointConnections
private final java.util.List<E extends AbstractPathConnector.ConnectableElement<E>> possiblePointConnections
List used to store possible point-like (zero-length) connections for the current element.
-
-
Method Detail
-
connectPathElements
protected void connectPathElements(java.lang.Iterable<E> elements)
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
protected void addPathElement(E element)
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:
connectPathElements(Iterable)
,computePathRoots()
-
computePathRoots
protected java.util.List<E> 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
private void followForwardConnections(E start)
Find and follow forward connections from the given start element.- Parameters:
start
- element to begin the connection operation with
-
makeForwardConnection
private E makeForwardConnection(E element)
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
private void findPossibleConnections(E element)
Find possible connections for the given element and place them in thepossibleConnections
andpossiblePointConnections
lists.- Parameters:
element
- the element to find connections for
-
addPossibleConnection
private boolean addPossibleConnection(E element, E candidate)
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
protected E selectPointConnection(E incoming, java.util.List<E> outgoingList)
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
protected abstract E selectConnection(E incoming, java.util.List<E> outgoing)
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
-
-