gumbo.visualize.data.layout
Class GraphLayoutEngine

java.lang.Object
  |
  +--gumbo.visualize.data.layout.WholeLayoutEngine
        |
        +--gumbo.visualize.data.layout.GraphLayoutEngine

All Implemented Interfaces:

LayoutGraphicTransform

Direct Known Subclasses:

KinkyGraphLayoutEngine

public abstract class GraphLayoutEngine

extends WholeLayoutEngine

implements LayoutGraphicTransform

Base class for graph layout engines. Assumes that the target graph structure is relatively static (i.e. the user must call doLayout() if the graph model changes). Works for cyclic graphs and in 2D or 3D.

Layout occurs using layout nodes (GraphLayoutNode) and the links between them, with one node per graph vertex (GraphLayoutVertex) and edge kink, and one or more links per graph edge (GraphLayoutEdge). Ports are ignored, and their edges are considered to belong to the root vertex.

Layout occurs in "layout" space, independent of the layout direction in graphic space. The first layout dimension is the "major" axis, the two remaining dimensions are the "minor" axes. The layout can be "gridded", with all nodes positioned in a grid whose spacing is determined by the size of the largest node; or, it can be "natural", with the size of vertices determined from their graphic shape bounds. Conversion between layout space and graphic space occurs through the LayoutGraphicTransform interface.

Version:

$Revision: 1.17 $

Author:

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

Nested Class Summary

Nested classes inherited from class gumbo.visualize.data.layout.WholeLayoutEngine

WholeLayoutEngine.LayoutAction

Field Summary

static double

DECO_SIZE_FACTOR Factor applied to gap size for link decoration size.

Constructor Summary

GraphLayoutEngine(GraphLayoutWholeView whole)

Method Summary

Point3	fromGraphicPosition(Point3 point, Point3 retVal) Transforms a position from graphic to layout space.
Size3	fromGraphicSize(Size3 size, Size3 retVal) Transforms a size from graphic to layout space.
Size3	getGraphicGap() Gets an immutable view of the graphic space gap size (see setGraphicGap()).
GraphLayoutWholeView	getGraphLayoutWholeView() Convenience method for getting the whole layout view as a GraphLayoutWhole.
boolean	getGridAligned(int layoutDim) Gets the grid-aligned layout setting for a given layout dimension.
Size3	graphicCellSize(Size3 retVal) Computes the layout "cell" size, in graphic space, which is the size of the largest vertex in graphic space plus the gap size.
Size3	graphicDecoSize(Size3 retVal) Computes the layout "decoration" size, in graphic space, which is a constant portion of the gap size.
protected void	initLayoutGraphicTransform() Initializes the layout-graphic space transform.
protected void	realizeDisplay() Implemented by subclasses to show the results of the layout generated by realizeLayout(), by transfering the layout state to the part view graphics, and making any changes visible in the whole view graphic.
void	setGraphicGap(Size3 gap) Sets the gap size between vertices, in graphic space.
void	setGridAligned(boolean first, boolean second, boolean third) Sets whether or not graph nodes (vertices and edge kinks) are grid-aligned, by layout space dimension.
Point3	toGraphicPosition(Point3 point, Point3 retVal) Transforms a position from layout to graphic space.
Size3	toGraphicSize(Size3 size, Size3 retVal) Transforms a size from layout to graphic space.

Methods inherited from class gumbo.visualize.data.layout.WholeLayoutEngine

doLayout, doLayoutWork, getAnimationSpeed, getDimensionality, getDimensionMap, getDirectionMap, getLayoutWholeView, realizeLayout, setAnimationSpeed, setDirections, showLayoutFrame

Methods inherited from class java.lang.Object

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

Field Detail

DECO_SIZE_FACTOR

public static final double DECO_SIZE_FACTOR

Factor applied to gap size for link decoration size.

See Also:

Constant Field Values

Constructor Detail

GraphLayoutEngine

public GraphLayoutEngine(GraphLayoutWholeView whole)

Parameters:

whole - The layout whole view managed by this layout engine. Represents the input data model to be laid out and the whole view used for display of the layout. The layout engine will never modify the data model, but it may modify its view by adding part views. Never null.

Throws:

java.lang.IllegalArgumentException - Whole is not a GraphLayoutWholeView.

Method Detail

getGraphLayoutWholeView

public GraphLayoutWholeView getGraphLayoutWholeView()

Convenience method for getting the whole layout view as a GraphLayoutWhole.

initLayoutGraphicTransform

protected void initLayoutGraphicTransform()

Initializes the layout-graphic space transform. Must be called before using any methods in LayoutSpaceTransform.

Returns:

Reference to retVal.

setGridAligned

public void setGridAligned(boolean first,
                           boolean second,
                           boolean third)

Sets whether or not graph nodes (vertices and edge kinks) are grid-aligned, by layout space dimension. The grid size is defined by the cell size, which is the size of the largest vertex in graphic space plus the graphic space node gap. The default is false (unaligned).

Parameters:

first - If true, this layout dimension is grid-aligned.

second - If true, this layout dimension is grid-aligned.

third - If true, this layout dimension is grid-aligned.

getGridAligned

public boolean getGridAligned(int layoutDim)

Gets the grid-aligned layout setting for a given layout dimension.

Returns:

True if grid-aligned, false if not grid-aligned.

setGraphicGap

public void setGraphicGap(Size3 gap)

Sets the gap size between vertices, in graphic space. The default is 1 in all dimensions. Special edges, including self-loops and adjacent-loops, and edge decorations, such as arrow heads, will be sized according to this gap size.

Parameters:

gap - Gap size. Never null.

getGraphicGap

public Size3 getGraphicGap()

Gets an immutable view of the graphic space gap size (see setGraphicGap()).

graphicCellSize

public Size3 graphicCellSize(Size3 retVal)

Computes the layout "cell" size, in graphic space, which is the size of the largest vertex in graphic space plus the gap size. Used for "gridded" layouts.

graphicDecoSize

public Size3 graphicDecoSize(Size3 retVal)

Computes the layout "decoration" size, in graphic space, which is a constant portion of the gap size.

toGraphicPosition

public Point3 toGraphicPosition(Point3 point,
                                Point3 retVal)

Description copied from interface: LayoutGraphicTransform

Transforms a position from layout to graphic space.

Specified by:

toGraphicPosition in interface LayoutGraphicTransform

Parameters:

point - Position in layout space. Never null.

retVal - Return value object. Position in graphic space. Never null.

Returns:

Reference to retVal. Never null.

fromGraphicPosition

public Point3 fromGraphicPosition(Point3 point,
                                  Point3 retVal)

Description copied from interface: LayoutGraphicTransform

Transforms a position from graphic to layout space.

Specified by:

fromGraphicPosition in interface LayoutGraphicTransform

Parameters:

point - Position in graphic space. Never null.

retVal - Return value object. Position in layout space. Never null.

Returns:

Reference to retVal. Never null.

toGraphicSize

public Size3 toGraphicSize(Size3 size,
                           Size3 retVal)

Description copied from interface: LayoutGraphicTransform

Transforms a size from layout to graphic space.

Specified by:

toGraphicSize in interface LayoutGraphicTransform

Parameters:

size - Size in layout space. Never null.

retVal - Return value object. Size in graphic space. Never null.

Returns:

Reference to retVal. Never null.

fromGraphicSize

public Size3 fromGraphicSize(Size3 size,
                             Size3 retVal)

Description copied from interface: LayoutGraphicTransform

Transforms a size from graphic to layout space.

Specified by:

fromGraphicSize in interface LayoutGraphicTransform

Parameters:

size - Size in graphic space. Never null.

retVal - Return value object. Size in layout space. Never null.

Returns:

Reference to retVal. Never null.

realizeDisplay

protected void realizeDisplay()

Description copied from class: WholeLayoutEngine

Implemented by subclasses to show the results of the layout generated by realizeLayout(), by transfering the layout state to the part view graphics, and making any changes visible in the whole view graphic.

Specified by:

realizeDisplay in class WholeLayoutEngine