gumbo.visualize.data.layout
Class GraphLayoutNode

java.lang.Object
  |
  +--gumbo.visualize.data.layout.GraphLayoutPart
        |
        +--gumbo.visualize.data.layout.GraphLayoutNode

All Implemented Interfaces:

LayoutPart

Direct Known Subclasses:

GraphLayoutVertex

public class GraphLayoutNode

extends GraphLayoutPart

A layout part that occupies space, connects to other nodes via none or more GraphLayoutLink, and is explicitely positioned by a GraphLayoutEngine. In layout space a graphic node's shape is a box of size getSize() centered about its position at getPosition(). Note that duplicate links between nodes are ignored.

Version:

$Revision: 1.13 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary

static class	GraphLayoutNode.BoundComparator A comparator for ordering nodes (GraphLayoutNode) by min or max extent along a given dimension.
static class	GraphLayoutNode.IndexCenterComparator A comparator for ordering nodes (GraphLayoutNode) by index barycenter (see getIndexCenter()).
static class	GraphLayoutNode.PositionComparator A comparator for ordering nodes (GraphLayoutNode) by position along a given dimension.
static class	GraphLayoutNode.PriorityComparator A comparator for ordering nodes (GraphLayoutNode) by before and/or after rank priority (see getBeforePriority(), getAfterPriority()).

Constructor Summary

GraphLayoutNode()

Method Summary

static void	addLink(GraphLayoutNode tail, GraphLayoutNode head) Adds a link from a tail node to a head node.
static java.util.Set	backwardNodes(java.util.Collection nodes, boolean withSources, java.util.Set retVal) Gets the set of nodes connected by links "to" a group of nodes.
static void	centerNodes(int dim, double center, java.util.Collection nodes) Centers a group of nodes in layout space along a given dimension about a center point.
static void	compactNodes(int dim, java.util.Set nodes) Compacts a group of nodes in layout space along a given position dimension by removing extra space between planes bounding the nodes and perpendicular to the dimension axis so there are no gaps.
static java.util.Set	connectedNodes(java.util.Collection nodes, boolean withSources, boolean withSinks, java.util.Set retVal) Gets the set of nodes connected by links "to" or "from" a group of nodes.
static void	expandBalancedNodes(int dim, java.util.Collection nodes) Deprecated. No longer used.
static void	expandNodes(int dim, boolean noCompress, java.util.Collection nodes) Expands a group of nodes in layout space along a given position dimension by adding extra space between planes bounding the nodes and perpendicular to the dimension axis so there are no overlaps.
static java.util.Set	forwardNodes(java.util.Collection nodes, boolean withSinks, java.util.Set retVal) Gets the set of nodes connected by links "from" a group of nodes.
java.util.Set	getAfterNodes() Gets an immutable view of the after rank nodes for this node, as set by setAfterNodes().
double	getAfterPriority() Gets the position priority of this node, as set by setAfterPriority().
java.util.Set	getBackwardNodes() Gets a reference to the immutable set of nodes on links to this node.
java.util.Set	getBeforeNodes() Gets an immutable view of the before rank nodes for this node, as set by setBeforeNodes().
double	getBeforePriority() Gets the position priority of this node, as set by setBeforePriority().
java.util.Set	getConnectedNodes() Gets a reference to the immutable set of nodes on links to and from this node.
java.util.Set	getForwardNodes() Gets a reference to the immutable set of nodes on links from this node.
double	getIndexCenter() Gets the index barycenter of this node, as set by setIndexCenter().
AxisBound3	getLayoutBound(AxisBound3 retVal) Returns the smallest bounds containing this part, in layout space.
Point3	getPosition(Point3 retVal) Gets the layout postion of this node, which is at its center.
Size3	getSize(Size3 retVal) Gets the layout size of this node, including any inter-node gap, as set by setSize().
static void	gridAlignNodes(int dim, double origin, java.util.Collection nodes) Adjusts the positions of a group of nodes along a given dimension aligning them in a grid.
static java.util.List	indexCenterList(java.util.Collection nodes, java.util.List retVal) Returns a list with the nodes in a node group ordered according to their index barycenters (see GraphLayoutNode.IndexCenterComparator).
static double[]	indexCenters(java.util.Collection nodes) Returns an array with the index barycenters of a group of nodes.
boolean	intersectLayout(LayoutPart part) Returns true if the target part intersects this part in layout space.
boolean	isSingular() Convenience method.
boolean	isSink() Convenience method.
boolean	isSource() Convenience method.
static void	offsetNodes(Tuple3 offset, java.util.Collection nodes) Adds a position offset in layout space to a group of nodes.
static java.util.Set	otherNodes(java.util.Collection nodes, java.util.Set retVal) Gets the set of other (non source, non sink, non singular) nodes in a group of nodes.
double	positionCenter(int dim, boolean withBefore, boolean withAfter) Returns the position barycenter of this node along a given dimension as computed from the specified friend nodes.
static double[]	positionCenters(int dim, boolean withBefore, boolean withAfter, java.util.Collection nodes) Returns an array with the position barycenters of a group of nodes.
static java.util.List	priorityList(java.util.Collection nodes, boolean sortAll, boolean useBefore, java.util.List retVal) Returns a list with the nodes in a node group ordered according to their before and/or after priorities (see GraphLayoutNode.PriorityComparator).
static void	removeLink(GraphLayoutNode tail, GraphLayoutNode head) Removes a link from a tail node to a head node.
static void	scaleNodes(Point3 point, Vector3 scale, java.util.Collection nodes) Scales the position of a group of nodes about a reference point, in layout space.
void	setAfterNodes(java.util.Set nodes) Sets the nodes connected to this node that are in the rank immediately after (rankI+1) that of this node.
void	setAfterPriority(double priority) Sets the position priority of this node based on its relative number of after node links.
void	setBeforeNodes(java.util.Set nodes) Sets the nodes connected to this node that are in the rank immediately before (rankI-1) that of this node.
void	setBeforePriority(double priority) Sets the position priority of this node based on its relative number of before node links.
void	setIndexCenter(double center) Sets the index barycenter of this node, which is based on the barycenter on this node's before or after node indices.
void	setPosition(Point3 pos) Sets the layout position of this node, which is at its center.
void	setSize(Size3 size) Sets the layout size of this node, including any inter-node gap.
static java.util.Set	singularNodes(java.util.Collection nodes, java.util.Set retVal) Gets the set of singular nodes in a group of nodes.
static java.util.Set	sinkNodes(java.util.Collection nodes, java.util.Set retVal) Gets the set of sink nodes in a group of nodes.
static java.util.Set	sourceNodes(java.util.Collection nodes, java.util.Set retVal) Gets the set of source nodes in a group of nodes.
java.lang.String	toString()
static SetList	traceNodes(java.util.Collection seeds, boolean traceForward, boolean traceBackward, boolean traceSources, boolean traceSinks, boolean keepSeeds, java.util.Set prunes) Traces nodes from the seed nodes and returns all the nodes that are found by simply adding the individual seed traces (see traceConnected()), in seed order, to the output trace.
static SetList	traceNodes(GraphLayoutNode seed, boolean traceForward, boolean traceBackward, boolean traceSources, boolean traceSinks, boolean keepSeed, java.util.Set prunes) Traces nodes from the seed node and returns the nodes found.

Methods inherited from class java.lang.Object

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

Constructor Detail

GraphLayoutNode

public GraphLayoutNode()

Method Detail

getBackwardNodes

public java.util.Set getBackwardNodes()

Gets a reference to the immutable set of nodes on links to this node.

getForwardNodes

public java.util.Set getForwardNodes()

Gets a reference to the immutable set of nodes on links from this node.

getConnectedNodes

public java.util.Set getConnectedNodes()

Gets a reference to the immutable set of nodes on links to and from this node.

setBeforeNodes

public void setBeforeNodes(java.util.Set nodes)

Sets the nodes connected to this node that are in the rank immediately before (rankI-1) that of this node.

Parameters:

nodes - Before rank nodes (GraphLayoutNode), by value. Never null.

getBeforeNodes

public java.util.Set getBeforeNodes()

Gets an immutable view of the before rank nodes for this node, as set by setBeforeNodes().

setAfterNodes

public void setAfterNodes(java.util.Set nodes)

Sets the nodes connected to this node that are in the rank immediately after (rankI+1) that of this node.

Parameters:

nodes - After rank nodes (GraphLayoutNode), by value. Never null.

getAfterNodes

public java.util.Set getAfterNodes()

Gets an immutable view of the after rank nodes for this node, as set by setAfterNodes().

isSource

public boolean isSource()

Convenience method. Returns true if this node is a graph source (i.e. no incoming links, even from itself).

isSink

public boolean isSink()

Convenience method. Returns true if this node is a graph sink (i.e. no outgoing links, even to itself).

isSingular

public boolean isSingular()

Convenience method. Returns true if this vertex is singular (i.e. no links, or all links to itself).

setSize

public void setSize(Size3 size)

Sets the layout size of this node, including any inter-node gap.

Parameters:

size - Node size. Never null. Defaults to (1,1,1).

getSize

public Size3 getSize(Size3 retVal)

Gets the layout size of this node, including any inter-node gap, as set by setSize().

Parameters:

retVal - Return value object. Never null.

Returns:

Reference to retVal. Never null.

setPosition

public void setPosition(Point3 pos)

Sets the layout position of this node, which is at its center.

Parameters:

pos - Value of the position. Never null. Defaults to the origin (0, 0, 0).

getPosition

public Point3 getPosition(Point3 retVal)

Gets the layout postion of this node, which is at its center.

Parameters:

retVal - Return value object. Never null.

Returns:

Reference to retVal. Never null.

setIndexCenter

public void setIndexCenter(double center)

Sets the index barycenter of this node, which is based on the barycenter on this node's before or after node indices.

Parameters:

center - The new index barycenter.

getIndexCenter

public double getIndexCenter()

Gets the index barycenter of this node, as set by setIndexCenter().

Returns:

The index barycenter.

setBeforePriority

public void setBeforePriority(double priority)

Sets the position priority of this node based on its relative number of before node links.

Parameters:

priority - The new position priority. Zero is lowest, increasing towards positive infinity.

getBeforePriority

public double getBeforePriority()

Gets the position priority of this node, as set by setBeforePriority().

Returns:

The position priority.

setAfterPriority

public void setAfterPriority(double priority)

Sets the position priority of this node based on its relative number of after node links.

Parameters:

priority - The new position priority. Zero is lowest, increasing towards positive infinity.

getAfterPriority

public double getAfterPriority()

Gets the position priority of this node, as set by setAfterPriority().

Returns:

The position priority.

positionCenter

public double positionCenter(int dim,
                             boolean withBefore,
                             boolean withAfter)

Returns the position barycenter of this node along a given dimension as computed from the specified friend nodes. If no friend nodes, returns the position of this node.

Parameters:

dim - The position dimension (0:2).

withBefore - If true, includes before node position.

withAfter - If true, includes after node position.

Returns:

The position barycenter.

positionCenters

public static double[] positionCenters(int dim,
                                       boolean withBefore,
                                       boolean withAfter,
                                       java.util.Collection nodes)

Returns an array with the position barycenters of a group of nodes.

Parameters:

dim - The position dimension (0:2).

withBefore - If true, includes before node position.

withAfter - If true, includes after node position.

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

Returns:

A new array the size of nodes with the node values in iterator order. Never null.

intersectLayout

public boolean intersectLayout(LayoutPart part)

Description copied from interface: LayoutPart

Returns true if the target part intersects this part in layout space.

Parameters:

part - The target part. Never null.

Returns:

True if the target part intersects this part.

getLayoutBound

public AxisBound3 getLayoutBound(AxisBound3 retVal)

Description copied from interface: LayoutPart

Returns the smallest bounds containing this part, in layout space.

Parameters:

retVal - Return value object. Never null.

Returns:

Reference to retVal. Never null.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

addLink

public static void addLink(GraphLayoutNode tail,
                           GraphLayoutNode head)

Adds a link from a tail node to a head node. The client is responsible for maintaining the original topology of the graph. Allows self links. Ignores duplicate links.

Parameters:

tail - Tail node. Never null.

head - Head node. Never null.

removeLink

public static void removeLink(GraphLayoutNode tail,
                              GraphLayoutNode head)

Removes a link from a tail node to a head node. The client is responsible for maintaining the original topology of the graph. Ignores missing links.

Parameters:

tail - Tail node. Never null.

head - Head node. Never null.

sourceNodes

public static java.util.Set sourceNodes(java.util.Collection nodes,
                                        java.util.Set retVal)

Gets the set of source nodes in a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

sinkNodes

public static java.util.Set sinkNodes(java.util.Collection nodes,
                                      java.util.Set retVal)

Gets the set of sink nodes in a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

singularNodes

public static java.util.Set singularNodes(java.util.Collection nodes,
                                          java.util.Set retVal)

Gets the set of singular nodes in a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

otherNodes

public static java.util.Set otherNodes(java.util.Collection nodes,
                                       java.util.Set retVal)

Gets the set of other (non source, non sink, non singular) nodes in a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

forwardNodes

public static java.util.Set forwardNodes(java.util.Collection nodes,
                                         boolean withSinks,
                                         java.util.Set retVal)

Gets the set of nodes connected by links "from" a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

withSinks - If true, sink nodes are included in the result.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

backwardNodes

public static java.util.Set backwardNodes(java.util.Collection nodes,
                                          boolean withSources,
                                          java.util.Set retVal)

Gets the set of nodes connected by links "to" a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

connectedNodes

public static java.util.Set connectedNodes(java.util.Collection nodes,
                                           boolean withSources,
                                           boolean withSinks,
                                           java.util.Set retVal)

Gets the set of nodes connected by links "to" or "from" a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Filtered nodes (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

indexCenters

public static double[] indexCenters(java.util.Collection nodes)

Returns an array with the index barycenters of a group of nodes.

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

Returns:

A new array the size of nodes with the node values in iterator order. Never null.

indexCenterList

public static java.util.List indexCenterList(java.util.Collection nodes,
                                             java.util.List retVal)

Returns a list with the nodes in a node group ordered according to their index barycenters (see GraphLayoutNode.IndexCenterComparator).

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

retVal - Return value object. Ordered list (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

priorityList

public static java.util.List priorityList(java.util.Collection nodes,
                                          boolean sortAll,
                                          boolean useBefore,
                                          java.util.List retVal)

Returns a list with the nodes in a node group ordered according to their before and/or after priorities (see GraphLayoutNode.PriorityComparator).

Parameters:

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

sortAll - If true, all nodes are sorted, with equal nodes being sorted by hash code; otherwise, duplicates are left out.

useBefore - If true, uses before priorities; otherwise, uses after priorities.

retVal - Return value object. Ordered list (GraphLayoutNode). Never null.

Returns:

Reference to retVal. Never null.

traceNodes

public static SetList traceNodes(GraphLayoutNode seed,
                                 boolean traceForward,
                                 boolean traceBackward,
                                 boolean traceSources,
                                 boolean traceSinks,
                                 boolean keepSeed,
                                 java.util.Set prunes)

Traces nodes from the seed node and returns the nodes found. Nodes are traced breadth-first, with their order indicating relative depth. At a given node in the trace, forward links are added to the trace before backward links.

Parameters:

seed - The trace seed node. The seed node may be excluded from the result, but it will never be excluded from the trace. Never null.

traceForward - If true, forward links are traced.

traceBackward - If true, backward links are traced.

traceSources - If false, sources are not traced but are included in the result. Use prunes to exclude sources from the trace and result.

traceSinks - If false, sinks are not traced but are included in the result. Use prunes to exclude sinks from the trace and result.

keepSeed - If true, the seed will be in the trace. If false, the seed will be pruned from the trace if it is in prunes.

prunes - Nodes (GraphLayoutNode) that will be excluded from the trace and result, except for the seed, which will be traced even if pruned (at the end). If null, all traced nodes will be included in the result.

Returns:

A new setlist containing the traced nodes. Always contains the seed, unless none or pruned. Never null.

traceNodes

public static SetList traceNodes(java.util.Collection seeds,
                                 boolean traceForward,
                                 boolean traceBackward,
                                 boolean traceSources,
                                 boolean traceSinks,
                                 boolean keepSeeds,
                                 java.util.Set prunes)

Traces nodes from the seed nodes and returns all the nodes that are found by simply adding the individual seed traces (see traceConnected()), in seed order, to the output trace.

Parameters:

seeds - The trace seed nodes (GraphLayoutNode). The seed nodes may be excluded from the result, but they will never be excluded from the trace. Never null.

traceForward - If true, forward links are traced.

traceBackward - If true, backward links are traced.

traceSources - If false, sources are not traced but are included in the result. Use prunes the exclude sources from the trace and result.

traceSinks - If false, sinks are not traced but are included in the result. Use prunes the exclude sinks from the trace and result.

keepSeeds - If true, the seeds will be in the trace. If false, a seed will be pruned from the trace if it is in prunes.

prunes - Nodes (GraphLayoutNode) that will be excluded from the trace and result, except for the seed, which will be traced even if pruned (at the end). If null, all traced nodes will be included in the result.

Returns:

A new setlist containing the traced nodes. Always contains the seeds, unless none or a seed is excluded. Never null.

expandNodes

public static void expandNodes(int dim,
                               boolean noCompress,
                               java.util.Collection nodes)

Expands a group of nodes in layout space along a given position dimension by adding extra space between planes bounding the nodes and perpendicular to the dimension axis so there are no overlaps. The position of the most negative node remains unchanged. Uses getSize() for node size.

Parameters:

dim - Dimension to be compacted (0:2).

noCompress - If true, extra space between nodes is maintained. If false, extra space is absorbed in the expansion.

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

compactNodes

public static void compactNodes(int dim,
                                java.util.Set nodes)

Compacts a group of nodes in layout space along a given position dimension by removing extra space between planes bounding the nodes and perpendicular to the dimension axis so there are no gaps. Overlapping nodes remain overlapping. The position of the most negative node remains unchanged. Uses getSize() for node size.

Parameters:

dim - Dimension to be compacted (0:2).

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

gridAlignNodes

public static void gridAlignNodes(int dim,
                                  double origin,
                                  java.util.Collection nodes)

Adjusts the positions of a group of nodes along a given dimension aligning them in a grid. Assumes that all nodes are the same size, and that the node size includes any inter-node gap.

Parameters:

dim - Dimension to be grid-aligned (0:2).

origin - The grid origin, which is the position of the minimum extent of the origin grid cell. used only for grid alignment, not large-scale offset.

nodes - The group of nodes (GraphLayoutNode). Never null.

expandBalancedNodes

public static void expandBalancedNodes(int dim,
                                       java.util.Collection nodes)

Deprecated. No longer used.

Expands the positions of a group of nodes along a given dimension to prevent overlap while preserving the original positions if possible. The expansion is balanced in the positive and negative directions. A node is assumed to be 1x1x1 in size.

Parameters:

dim - Node position dimension affected (0:2).

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

centerNodes

public static void centerNodes(int dim,
                               double center,
                               java.util.Collection nodes)

Centers a group of nodes in layout space along a given dimension about a center point. Inter-node spacing and other layout dimensions are unaffected. Uses getSize() for size.

Parameters:

dim - Dimension to be centered (0:2).

center - Center point. Never null.

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

offsetNodes

public static void offsetNodes(Tuple3 offset,
                               java.util.Collection nodes)

Adds a position offset in layout space to a group of nodes.

Parameters:

offset - Offset value. Never null.

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.

scaleNodes

public static void scaleNodes(Point3 point,
                              Vector3 scale,
                              java.util.Collection nodes)

Scales the position of a group of nodes about a reference point, in layout space.

Parameters:

point - Reference point. Never null.

scale - Scale factor. Positive for magnification, negative for minification. Never null.

nodes - AbstractGroup of nodes (GraphLayoutNode). Never null.