y.layout.organic
Class GRIP

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.organic.GRIP

All Implemented Interfaces:

Layouter

public class GRIP
extends CanonicMultiStageLayouter

This layout algorithm arranges graphs in an organic fashion.

It is strongly recommended to use SmartOrganicLayouter instead of GRIP. SmartOrganicLayouter is a much more advanced layout algorithm (e.g. it supports grouping and node labels), while covering all functionality of GRIP.

Layout Style

The organic layout style is characterized by a natural distribution of nodes. It is well suited to exhibit clusters and symmetric properties of a graph. Nodes are placed in a space-saving manner, close to their adjacent nodes. Distances between neighbors and edge lengths are highly uniform and edges are drawn as straight-line segments without bends.

Organic diagrams are commonly used for visualizing relations in large networks for example in bioinformatics, enterprise networking, visualizing social networks, mesh visualization or system management.

A mesh-like graph arranged using default settings

A network graph

Concept

This algorithm implements a variant of the GRIP algorithm by P Gajer and SG Kobourov: Graph Drawing with Intelligent Placement.

Field Summary

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

GRIP()
Creates a new instance of GRIP with default settings.

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts general graphs without exception.
void	doLayoutCore(LayoutGraph graph) Calculates an organic arrangement of the graph.
int	getFinalRounds() Returns the number of Fruchterman-Reingold refinement rounds which are considered as the final algorithm rounds.
int	getInitialTemperature() Returns the initial temperature for each optimization round.
double	getLaxity() Returns the laxity value which is used in conjunction with the preferred edge length and influences how strict the algorithm should be regarding that length.
int	getPreferredEdgeLength() Returns the preferred edge length.
int	getRounds() Returns the number of Kamada-Kawai refinement rounds which are considered as the initial algorithm rounds.
boolean	isDeterministic() Returns whether or not the deterministic mode of the layout algorithm is enabled.
boolean	isMultiThreadingAllowed() Returns whether or not the layout algorithm may use multi-threading to reduce the running time.
boolean	isNodeSizeAware() Returns whether or not to consider average node sizes during layout calculation.
boolean	isSmartInitialPlacement() Returns whether or not the initial placement of nodes is determined using a more involved, smart strategy.
void	setComponentLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.
void	setDeterministic(boolean deterministic) Specifies whether or not the deterministic mode of the layout algorithm is enabled.
void	setFinalRounds(int finalRounds) Specifies the number of Fruchterman-Reingold refinement rounds which are considered as the final algorithm rounds.
void	setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled) Specifies whether or not the LayoutStage used for hiding group nodes is activated.
void	setInitialTemperature(int tInit) Sets the initial temperature for each optimization round.
void	setLaxity(double laxity) Specifies the laxity value which is used in conjunction with the preferred edge length and influences how strict the algorithm should be regarding that length.
void	setMultiThreadingAllowed(boolean multiThreadingAllowed) Specifies whether or not the layout algorithm may use multi-threading to reduce the running time.
void	setNodeSizeAware(boolean nodeSizeAware) Specifies whether or not to consider average node sizes during layout calculation.
void	setOrientationLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage that modifies the orientation of the layout is activated.
void	setPreferredEdgeLength(int preferredEdgeLength) Specifies the preferred edge length.
void	setRounds(int rounds) Specifies the number of Kamada-Kawai refinement rounds which are considered as the initial algorithm rounds.
void	setSmartInitialPlacement(boolean smartInitialPlacement) Specifies whether or not the initial placement of nodes is determined using a more involved, smart strategy.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setGroupNodeHider, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setParallelEdgeLayouter, setParallelEdgeLayouterEnabled, setSelfLoopLayouter, setSelfLoopLayouterEnabled, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Constructor Detail

GRIP

public GRIP()

Creates a new instance of GRIP with default settings.

Method Detail

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Accepts general graphs without exception.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true for all general graphs, false if the given graph is null

isMultiThreadingAllowed

public boolean isMultiThreadingAllowed()

Returns whether or not the layout algorithm may use multi-threading to reduce the running time.

Returns:

true if multi-threading is used, false otherwise

See Also:

setMultiThreadingAllowed(boolean)

setMultiThreadingAllowed

public void setMultiThreadingAllowed(boolean multiThreadingAllowed)

Specifies whether or not the layout algorithm may use multi-threading to reduce the running time.

Default Value:

The default value is false. The layout algorithm runs single-threaded.

Parameters:

multiThreadingAllowed - true if multi-threading should be used, false otherwise

setRounds

public void setRounds(int rounds)

Specifies the number of Kamada-Kawai refinement rounds which are considered as the initial algorithm rounds.

It is recommended to keep the number of rounds within the interval [5,50].

Default Value:

The default value is 10. Initially, 10 rounds are executed.

Parameters:

rounds - the number of initial rounds

setFinalRounds

public void setFinalRounds(int finalRounds)

Specifies the number of Fruchterman-Reingold refinement rounds which are considered as the final algorithm rounds.

It is recommended to keep the number of final rounds within the interval [0,100].

Default Value:

The default value is 25.

Parameters:

finalRounds - the number of final rounds

setPreferredEdgeLength

public void setPreferredEdgeLength(int preferredEdgeLength)

Specifies the preferred edge length.

This length does not define the actual absolute length of edges, but the layout algorithm considers the preference where possible.

The preferred edge length needs to be non-negative.

Default Value:

The default value is 40.

Parameters:

preferredEdgeLength - the non-negative preferred edge length

Throws:

java.lang.IllegalArgumentException - if the specified edge length is negative

Sample Graphs:

Preferred edge length 40

Preferred edge length 100

setInitialTemperature

public void setInitialTemperature(int tInit)

Sets the initial temperature for each optimization round.

The algorithm starts with an initial temperature. During the iterations of the layout process, this temperature decreases and if it reaches a certain limit, the process terminates.

The temperature value should lie within the interval [10,80].

Default Value:

The default value is 15.

Parameters:

tInit - the initial temperature

getRounds

public int getRounds()

Returns the number of Kamada-Kawai refinement rounds which are considered as the initial algorithm rounds.

It is recommended to keep the number of rounds within the interval [5,50].

Returns:

the number of initial rounds

See Also:

setRounds(int)

getFinalRounds

public int getFinalRounds()

Returns the number of Fruchterman-Reingold refinement rounds which are considered as the final algorithm rounds.

It is recommended to keep the number of final rounds within the interval [0,100].

Returns:

the number final rounds

See Also:

setFinalRounds(int)

getPreferredEdgeLength

public int getPreferredEdgeLength()

Returns the preferred edge length.

This length does not define the actual absolute length of edges, but the layout algorithm considers the preference where possible.

The preferred edge length needs to be non-negative.

Returns:

the non-negative preferred edge length

See Also:

setPreferredEdgeLength(int)

getInitialTemperature

public int getInitialTemperature()

Returns the initial temperature for each optimization round.

The algorithm starts with an initial temperature. During the iterations of the layout process, this temperature decreases and if it reaches a certain limit, the process terminates.

The temperature value should lie within the interval [10,80].

Returns:

the initial temperature

See Also:

setInitialTemperature(int)

setComponentLayouterEnabled

public void setComponentLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.

Overrides:

setComponentLayouterEnabled in class CanonicMultiStageLayouter

GRIP can only handle single components. Disabling ComponentLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that arranges connected graph components is activated.

Parameters:

enabled - true if the stage that arranges the graph components is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isComponentLayouterEnabled(), CanonicMultiStageLayouter.setComponentLayouter(y.layout.LayoutStage), ComponentLayouter

setGroupNodeHidingEnabled

public void setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled)

Specifies whether or not the LayoutStage used for hiding group nodes is activated.

Overrides:

setGroupNodeHidingEnabled in class CanonicMultiStageLayouter

GRIP cannot handle group nodes. Disabling GroupNodeHider will lead to errors during execution.

Default Value:

The default value is true. The stage responsible for hiding group nodes is activated.

Parameters:

groupNodeHidingEnabled - true if the stage used for hiding group nodes is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isGroupNodeHidingEnabled(), CanonicMultiStageLayouter.setGroupNodeHider(y.layout.LayoutStage), GroupNodeHider

setOrientationLayouterEnabled

public void setOrientationLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage that modifies the orientation of the layout is activated.

Overrides:

setOrientationLayouterEnabled in class CanonicMultiStageLayouter

If the current layout orientation is LayoutOrientation.TOP_TO_BOTTOM, the orientation of the layout will not be modified.

Based on the undirected layout style, disabling OrientationLayouter has no significant effect.

Default Value:

The default value is true. The orientation LayoutStage is activated.

Parameters:

enabled - true if the stage that modifies the orientation is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isOrientationLayouterEnabled(), CanonicMultiStageLayouter.setOrientationLayouter(y.layout.LayoutStage), CanonicMultiStageLayouter.setLayoutOrientation(byte), OrientationLayouter

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Calculates an organic arrangement of the graph.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.

Parameters:

graph - the input graph

isSmartInitialPlacement

public boolean isSmartInitialPlacement()

Returns whether or not the initial placement of nodes is determined using a more involved, smart strategy.

Enabling this feature usually leads to aesthetically more pleasing results (e.g. less overlaps). However, the runtime may increase.

Returns:

true if the smart strategy for the initial node placement is enabled, false otherwise

See Also:

setSmartInitialPlacement(boolean)

setSmartInitialPlacement

public void setSmartInitialPlacement(boolean smartInitialPlacement)

Specifies whether or not the initial placement of nodes is determined using a more involved, smart strategy.

Enabling this feature usually leads to aesthetically more pleasing results (e.g. less overlaps). However, the runtime may increase.

Default Value:

The default value is true. A smart strategy for the initial node placement is applied.

Parameters:

smartInitialPlacement - true if the smart strategy for the initial node placement should be enabled, false otherwise

isDeterministic

public boolean isDeterministic()

Returns whether or not the deterministic mode of the layout algorithm is enabled.

In deterministic mode, the layout algorithm will yield the same results for the exact same input and algorithm settings.

Returns:

true if the layout algorithm operates in deterministic mode, false otherwise

See Also:

setDeterministic(boolean)

setDeterministic

public void setDeterministic(boolean deterministic)

Specifies whether or not the deterministic mode of the layout algorithm is enabled.

In deterministic mode, the layout algorithm will yield the same results for the exact same input and algorithm settings.

Default Value:

The default value is false. The layout algorithm works non-deterministically.

Parameters:

deterministic - true if the layout algorithm should operate in deterministic mode, false otherwise

getLaxity

public double getLaxity()

Returns the laxity value which is used in conjunction with the preferred edge length and influences how strict the algorithm should be regarding that length.

The laxity is defined to be a strictly positive value.

Returns:

the laxity value

See Also:

setLaxity(double)

setLaxity

public void setLaxity(double laxity)

Specifies the laxity value which is used in conjunction with the preferred edge length and influences how strict the algorithm should be regarding that length.

The laxity is defined to be a strictly positive value.

Default Value:

The default value is 2.

Parameters:

laxity - the laxity value

Throws:

java.lang.IllegalArgumentException - if the given laxity value is 0 or negative

isNodeSizeAware

public boolean isNodeSizeAware()

Returns whether or not to consider average node sizes during layout calculation.

If this feature is disabled, overlaps between nodes (e.g. due to large node sizes) may occur.

Returns:

true if the sizes of nodes are taken into account, false otherwise

See Also:

setNodeSizeAware(boolean)

setNodeSizeAware

public void setNodeSizeAware(boolean nodeSizeAware)

Specifies whether or not to consider average node sizes during layout calculation.

If this feature is disabled, overlaps between nodes (e.g. due to large node sizes) may occur.

Default Value:

The default value is false. Node sizes are not considered and overlaps may occur.

Parameters:

nodeSizeAware - true if the sizes of nodes should be taken into account, false otherwise

Sample Graphs:

true

false