org.apache.commons.geometry.euclidean.internal

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:

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.ConnectableElements.
• 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 when AbstractPathConnector.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/or selectConnection(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 and Description
static class	AbstractPathConnector.ConnectableElement<E extends AbstractPathConnector.ConnectableElement<E>> Class used to represent connectable path elements for use with AbstractPathConnector.

Constructor Summary

Constructors

Constructor and Description
AbstractPathConnector()

Method Summary

Modifier and Type	Method and Description
protected void	addPathElement(E element) Add a single path element to the connector, leaving it unconnected until a later call to to connectPathElements(Iterable) or computePathRoots().
protected List<E>	computePathRoots() 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.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractPathConnector

public AbstractPathConnector()

Method Detail

connectPathElements

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.

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 to connectPathElements(Iterable) or computePathRoots().

Parameters:

element - value to add to the connector

See Also:

connectPathElements(Iterable), computePathRoots()

computePathRoots

protected 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

selectPointConnection

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. 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 element

outgoingList - list of available outgoing point-like connections

Returns:

the connection to use

selectConnection

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. In this case, the selection of the outgoing connection depends only on the desired characteristics of the connected path.

Parameters:

incoming - the incoming segment

outgoing - list of available outgoing connections; will always contain at least two elements

Returns:

the connection to use