org.kynosarges.tektosyne.graph

Interface Graph<T>

Type Parameters:

T - the type of all nodes in the Graph

All Known Implementing Classes:

PolygonGrid, Subdivision

public interface Graph<T>

Provides a navigable graph whose nodes map to regions in two-dimensional space. Suitable for pathfinding and other graph algorithms. Makes no assumptions about topology, except that nodes must map to two-dimensional space. Nodes cannot be null and must provide meaningful Object.equals(java.lang.Object) and Object.hashCode() implementations.

Method Summary

Modifier and Type	Method and Description
int	connectivity() Gets the maximum number of direct neighbors for any Graph node.
boolean	contains(T node) Determines whether the Graph contains the specified node.
T	findNearestNode(PointD location) Finds the Graph node nearest to the specified PointD world location.
double	getDistance(T source, T target) Gets the distance between two specified Graph nodes.
java.util.Collection<T>	getNeighbors(T node) Gets all direct neighbors of the specified Graph node.
default java.util.Collection<T>	getNeighbors(T node, int steps) Gets all neighbors of the specified Graph node within the specified step distance.
PointD	getWorldLocation(T node) Gets the world location of the specified Graph node.
PointD[]	getWorldRegion(T node) Gets the world region covered by the specified Graph node.
int	nodeCount() Gets the total number of nodes() in the Graph.
java.util.Collection<T>	nodes() Gets all nodes in the Graph.

Method Detail

connectivity

int connectivity()

Gets the maximum number of direct neighbors for any Graph node. Always greater than zero. Direct neighbors of a given Graph node are those that are directly connected, without any intermediate nodes.

Returns:

the maximum number of direct neighbors for any Graph node

nodeCount

int nodeCount()

Gets the total number of nodes() in the Graph. Never less than zero.

Returns:

the total number of nodes() in the Graph

nodes

java.util.Collection<T> nodes()

Gets all nodes in the Graph. Always contains nodeCount() elements. The element order depends on the concrete implementation of Graph.

Returns:

a Collection of all nodes in the Graph

contains

boolean contains(T node)

Determines whether the Graph contains the specified node.

Parameters:

node - the Graph node to examine

Returns:

true if the Graph contains node, else false

Throws:

java.lang.NullPointerException - if node is null

findNearestNode

T findNearestNode(PointD location)

Finds the Graph node nearest to the specified PointD world location. Always returns a valid node, even if the distance between its getWorldLocation(T) result and location is very large. The returned node is not necessarily the one whose getWorldRegion(T) result contains location.

Parameters:

location - the PointD location, in world coordinates, to examine

Returns:

the Graph node whose getWorldLocation(T) result is nearest to the specified location

Throws:

java.lang.NullPointerException - if location is null

getDistance

double getDistance(T source,
                   T target)

Gets the distance between two specified Graph nodes. Uses an arbitrary distance measurement, as documented by the implementation. However, the result must always conform to the following invariants:

• The distance between identical nodes is always zero.
• The distance between different nodes is always positive.
• The sum of the distances between all successive nodes within a sequence is never less than the distance between any two nodes from the same sequence.
• The distance between two nodes is always equal to or less than the result of GraphAgent.getStepCost(T, T) for the same two nodes.
• The distance between two nodes remains unchanged if the arguments are reversed.
• The distance is undefined if one or both nodes are invalid. In this case only, the result may be negative.

Parameters:

source - the source node in the Graph

target - the target node in the Graph

Returns:

the non-negative distance between source and target

Throws:

java.lang.NullPointerException - if source or target is null

getNeighbors

java.util.Collection<T> getNeighbors(T node)

Gets all direct neighbors of the specified Graph node. Returns an empty Collection if node or all its direct neighbors are not part of the Graph. The returned Collection is the complete set of target nodes for which GraphAgent.canMakeStep(T, T) could possibly succeed, given the specified node as the source node.

Parameters:

node - the Graph node whose direct neighbors to collect

Returns:

a Collection of all Graph nodes that are directly connected with node, numbering from zero to connectivity()

Throws:

java.lang.NullPointerException - if node is null

getNeighbors

default java.util.Collection<T> getNeighbors(T node,
                                             int steps)

Gets all neighbors of the specified Graph node within the specified step distance. Returns an empty Collection if node or all its direct neighbors are not part of the Graph. Otherwise, returns a Collection containing all direct neighbors, direct neighbors of those neighbors, etc. repeated for steps.

The default implementation uses two lists for gathering direct neighbors to inspect, and returns a HashSet with all valid neighbors found within steps. This requires the node type T to offer a useful Object.hashCode() function. Specific Graph implementations may be able to use more efficient algorithms.

Parameters:

node - the Graph node whose neighbors within steps to collect

steps - the distance around node, in movement steps, in which other nodes are considered neighbors of node

Returns:

a Collection of all Graph nodes whose step distance from node is greater than zero, but equal to or less than steps

Throws:

java.lang.IllegalArgumentException - if steps is equal to or less than zero

java.lang.NullPointerException - if node is null

getWorldLocation

PointD getWorldLocation(T node)

Gets the world location of the specified Graph node. Uses an arbitrary “world” coordinate system, as documented by the implementation. The world location always resides within the result of getWorldRegion(T) for the same node. The result of getDistance(T, T) for any two nodes is usually the Euclidean distance between their world locations, but this is not required.

Parameters:

node - the Graph node whose world location to find

Returns:

the PointD location of node, in world coordinates

Throws:

java.lang.NullPointerException - if node is null

getWorldRegion

PointD[] getWorldRegion(T node)

Gets the world region covered by the specified Graph node. Uses an arbitrary “world” coordinate system, as documented by the implementation. The returned polygon is implicitly assumed to be closed, with an edge connecting its last and first vertex. The polygon should be simple and enclose a positive area that contains the result of getWorldLocation(T) for node.

Parameters:

node - the Graph node whose world region to find

Returns:

an array of PointD vertices defining the polygonal region covered by node, in world coordinates

Throws:

java.lang.NullPointerException - if node is null