y.layout.organic
Class SmartOrganicLayouter

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

All Implemented Interfaces:

Layouter

public class SmartOrganicLayouter
extends CanonicMultiStageLayouter

This class can be used as a convenience class to gain access to a variety of organic layout algorithms. Its strength lies in being able to conveniently specify a ratio between quality and running time, as well as the ability to specify the degree of the compactness of the drawing and to guarantee non-overlapping nodes.

Field Summary

static Object	GROUP_NODE_MODE_DATA The data provider key for specifying how to handle group nodes.
static Object	GROUP_NODE_MODE_FIX_BOUNDS Group node mode constant that can be used to tag a group node.
static Object	GROUP_NODE_MODE_FIX_CONTENTS Group node mode constant that can be used to tag a group node.
static Object	GROUP_NODE_MODE_NORMAL Group node mode constant that can be used to tag a group node.
static Object	NODE_SUBSET_DATA The data provider key for specifying the node subset to be laid out.
static Object	PREFERRED_EDGE_LENGTH_DATA The data provider key for specifying the preferred edge lengths for each edge The algorithm expects to find DataProvider.getInt(Object) integer values associated with each edge.
static byte	SCOPE_ALL scope constant - used for layouting all nodes
static byte	SCOPE_MAINLY_SUBSET scope constant - used for layouting mainly the subset of the nodes
static byte	SCOPE_SUBSET scope constant - used for layouting the subset of the nodes only

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

SmartOrganicLayouter()
Creates a new SmartOrganicLayouter instance

Method Summary

protected boolean	canLayoutCore(LayoutGraph graph) Subclasses have to provide information whether or not they can layout the given graph.
protected void	configureComponentLayouter(LayoutGraph graph, ComponentLayouter layouter) Configures the ComponentLayouter and graph instance to adhere to the NODE_SUBSET_DATA in case SCOPE_ALL is not set.
void	doLayout(LayoutGraph layoutGraph) Calculates a layout for the given graph.
protected void	doLayoutCore(LayoutGraph graph) Subclasses have to provide core layout code in this method.
double	getCompactness() Returns the property for the compactness of the resulting layout.
GroupBoundsCalculator	getGroupBoundsCalculator() Returns the GroupBoundsCalculator instance used for calculating the size of group nodes.
long	getMaximumDuration() Returns the maximum duration this algorithm is allowed to run.
double	getMinimalNodeDistance() Returns the current minimal node distance this algorithm should enforce if the node overlaps allowance property is set to true.
OutputRestriction	getOutputRestriction() Returns the current OutputRestriction instance set for this instance.
double	getPreferredEdgeLength() Returns the currently set default preferred edge length.
double	getPreferredMinimalNodeDistance() Returns the current preferred minimal node distance this algorithm should use for pairs of nodes that are not directly connected by adjacent edges.
double	getQualityTimeRatio() Returns the qualityTimeRatio.
byte	getScope() Returns the scope of the layout.
boolean	isDeterministic() Returns whether the algorithm will behave deterministically in the next layout run.
boolean	isNodeEdgeOverlapAvoided() Returns whether this algorithm is configured to try to avoid node/edge overlaps.
boolean	isNodeOverlapsAllowed() Returns whether node overlaps are allowed (but not encouraged) for the next run.
boolean	isNodeSizeAware() Determines whether the algorithm should consider the size of the nodes for the layout.
boolean	isSmartComponentLayoutEnabled() Determines whether this instance should configure the ComponentLayouter in such a way that it respects the scope's settings SCOPE_SUBSET and SCOPE_MAINLY_SUBSET by keeping other nodes pinned down.
void	setCompactness(double compactness) Sets the compactness property for the next layout run.
void	setDeterministic(boolean deterministic) Sets this algorithm to deterministic mode.
void	setGroupBoundsCalculator(GroupBoundsCalculator groupBoundsCalculator) Sets the GroupBoundsCalculator instance used for calculating the size of group nodes.
void	setMaximumDuration(long maximumDurationMillis) Sets the soft limit for the maximum duration this algorithm is allowed to execute.
void	setMinimalNodeDistance(double minimalNodeDistance) Sets the minimal node distance this algorithm should enforce between all pairs of nodes for the next run.
void	setNodeEdgeOverlapAvoided(boolean nodeEdgeOverlapAvoided) Configures this algorithm so that it tries to avoid node/edge overlaps.
void	setNodeOverlapsAllowed(boolean nodeOverlapsAllowed) Determines whether the next layout run should enforce non-overlapping nodes.
void	setNodeSizeAware(boolean nodeSizeAware) Instructs the algorithm to consider node sizes for the next layout run.
void	setOutputRestriction(OutputRestriction restriction) Sets a restriction on the output generated by this layouter
void	setPreferredEdgeLength(double preferredEdgeLength) Sets the default preferred edge length for the next algorithm run.
void	setPreferredMinimalNodeDistance(double preferredMinimalNodeDistance) Sets the minimal node distance this algorithm should try to obey for the next run.
void	setQualityTimeRatio(double qualityTimeRatio) Setter the qualityTimeRatio property.
void	setScope(byte scope) Sets the scope for the next layout run.
void	setSmartComponentLayoutEnabled(boolean smartComponentLayoutEnabled) Sets whether this instance should configure the ComponentLayouter in such a way that it respects the scope's settings SCOPE_SUBSET and SCOPE_MAINLY_SUBSET by keeping other nodes pinned, even if they reside in different components.
protected void	unconfigureComponentLayouter(LayoutGraph graph, ComponentLayouter layouter) Unconfigures the ComponentLayouter from previous configureComponentLayouter(y.layout.LayoutGraph, y.layout.ComponentLayouter) call.

Methods inherited from class y.layout.CanonicMultiStageLayouter

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

Methods inherited from class java.lang.Object

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

Field Detail

SCOPE_ALL

public static final byte SCOPE_ALL

scope constant - used for layouting all nodes

See Also:

Constant Field Values

SCOPE_SUBSET

public static final byte SCOPE_SUBSET

scope constant - used for layouting the subset of the nodes only

See Also:

Constant Field Values

SCOPE_MAINLY_SUBSET

public static final byte SCOPE_MAINLY_SUBSET

scope constant - used for layouting mainly the subset of the nodes

See Also:

Constant Field Values

NODE_SUBSET_DATA

public static final Object NODE_SUBSET_DATA

The data provider key for specifying the node subset to be laid out. The algorithm expects for each node in the graph to find a boolean that indicates whether the node belongs to the "sphere of action".

See Also:

setScope(byte)

GROUP_NODE_MODE_DATA

public static final Object GROUP_NODE_MODE_DATA

The data provider key for specifying how to handle group nodes. The algorithm expects for each node to find one of the following constants or null:

• GROUP_NODE_MODE_NORMAL
• GROUP_NODE_MODE_FIX_BOUNDS
• GROUP_NODE_MODE_FIX_CONTENTS

null will be treated like GROUP_NODE_MODE_NORMAL.

GROUP_NODE_MODE_NORMAL

public static final Object GROUP_NODE_MODE_NORMAL

Group node mode constant that can be used to tag a group node. Use the GROUP_NODE_MODE_DATA DataProvider key to associate this constant with a group node to indicate that it should be treated like an ordinary group node.

GROUP_NODE_MODE_FIX_BOUNDS

public static final Object GROUP_NODE_MODE_FIX_BOUNDS

Group node mode constant that can be used to tag a group node. Use the GROUP_NODE_MODE_DATA DataProvider key to associate this constant with a group node to indicate that its bounds should be treated as fixed an its contents should never exceed those bounds.

GROUP_NODE_MODE_FIX_CONTENTS

public static final Object GROUP_NODE_MODE_FIX_CONTENTS

Group node mode constant that can be used to tag a group node. Use the GROUP_NODE_MODE_DATA DataProvider key to associate this constant with a group node to indicate that it can be moved like an ordinary group node however its contents should remain fixed relative to the position of the group node. Note that this implicitly fixes all descendants of the group node.

PREFERRED_EDGE_LENGTH_DATA

public static final Object PREFERRED_EDGE_LENGTH_DATA

The data provider key for specifying the preferred edge lengths for each edge The algorithm expects to find DataProvider.getInt(Object) integer values associated with each edge.

Constructor Detail

SmartOrganicLayouter

public SmartOrganicLayouter()

Creates a new SmartOrganicLayouter instance

Method Detail

getGroupBoundsCalculator

public GroupBoundsCalculator getGroupBoundsCalculator()

Returns the GroupBoundsCalculator instance used for calculating the size of group nodes. The default is MinimumSizeGroupBoundsCalculator.

Returns:

the instance being used currently

isSmartComponentLayoutEnabled

public boolean isSmartComponentLayoutEnabled()

Determines whether this instance should configure the ComponentLayouter in such a way that it respects the scope's settings SCOPE_SUBSET and SCOPE_MAINLY_SUBSET by keeping other nodes pinned down. The default is false.

Returns:

Whether to configure the component layouter instance.

See Also:

isSmartComponentLayoutEnabled()

setSmartComponentLayoutEnabled

public void setSmartComponentLayoutEnabled(boolean smartComponentLayoutEnabled)

Sets whether this instance should configure the ComponentLayouter in such a way that it respects the scope's settings SCOPE_SUBSET and SCOPE_MAINLY_SUBSET by keeping other nodes pinned, even if they reside in different components. The default is false.

See Also:

isSmartComponentLayoutEnabled()

setGroupBoundsCalculator

public void setGroupBoundsCalculator(GroupBoundsCalculator groupBoundsCalculator)

Sets the GroupBoundsCalculator instance used for calculating the size of group nodes. The default is MinimumSizeGroupBoundsCalculator.

Throws:

NullPointerException - if the argument is null

Parameters:

groupBoundsCalculator - the instance to use

isNodeEdgeOverlapAvoided

public boolean isNodeEdgeOverlapAvoided()

Returns whether this algorithm is configured to try to avoid node/edge overlaps.

Returns:

whether the option is enabled

See Also:

setNodeEdgeOverlapAvoided(boolean)

setNodeEdgeOverlapAvoided

public void setNodeEdgeOverlapAvoided(boolean nodeEdgeOverlapAvoided)

Configures this algorithm so that it tries to avoid node/edge overlaps. The default is false. Note that the current implementation does not guarantee the non-existence of overlaps but tries to avoid them.

Parameters:

nodeEdgeOverlapAvoided - whether to enable that option

configureComponentLayouter

protected void configureComponentLayouter(LayoutGraph graph,
                                          ComponentLayouter layouter)

Configures the ComponentLayouter and graph instance to adhere to the NODE_SUBSET_DATA in case SCOPE_ALL is not set. This will result in the component layouter not rearranging components if they contain pinned-down nodes.

Parameters:

graph - the graph that will be arranged

layouter - the layouter to reconfigure

See Also:

unconfigureComponentLayouter(y.layout.LayoutGraph, y.layout.ComponentLayouter), setSmartComponentLayoutEnabled(boolean)

doLayout

public void doLayout(LayoutGraph layoutGraph)

Description copied from class: CanonicMultiStageLayouter

Calculates a layout for the given graph. The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph. This method is not side effect free in the sense that the order of edges or nodes in the input graph may change during the layout process.

Specified by:

doLayout in interface Layouter

Overrides:

doLayout in class CanonicMultiStageLayouter

unconfigureComponentLayouter

protected void unconfigureComponentLayouter(LayoutGraph graph,
                                            ComponentLayouter layouter)

Unconfigures the ComponentLayouter from previous configureComponentLayouter(y.layout.LayoutGraph, y.layout.ComponentLayouter) call.

Parameters:

graph - the graph that has been arranged

layouter - the layouter to unconfigure

See Also:

configureComponentLayouter(y.layout.LayoutGraph, y.layout.ComponentLayouter), setSmartComponentLayoutEnabled(boolean)

canLayoutCore

protected boolean canLayoutCore(LayoutGraph graph)

Description copied from class: CanonicMultiStageLayouter

Subclasses have to provide information whether or not they can layout the given graph.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

doLayoutCore

protected void doLayoutCore(LayoutGraph graph)

Description copied from class: CanonicMultiStageLayouter

Subclasses have to provide core layout code in this method.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

getQualityTimeRatio

public double getQualityTimeRatio()

Returns the qualityTimeRatio. This setting determines the ratio of layout quality versus time consumption. The higher the ratio, the better the quality of the resulting layout but the longer it may take to perform the layout.

Returns:

Value of property qualityTimeRatio [0.0d .. 1.0d]

setQualityTimeRatio

public void setQualityTimeRatio(double qualityTimeRatio)

Setter the qualityTimeRatio property. This setting determines the ratio of layout quality versus time consumption.

Parameters:

qualityTimeRatio - a value between 0.0 (low quality, fast) and 1.0 (high quality, slow)

See Also:

getQualityTimeRatio()

getMaximumDuration

public long getMaximumDuration()

Returns the maximum duration this algorithm is allowed to run. This is a soft limit

Returns:

the maximum duration in milliseconds

setMaximumDuration

public void setMaximumDuration(long maximumDurationMillis)

Sets the soft limit for the maximum duration this algorithm is allowed to execute.

Parameters:

maximumDurationMillis - the new soft limit for the duration in milliseconds

getScope

public byte getScope()

Returns the scope of the layout.

Returns:

the scope, one of SCOPE_ALL, SCOPE_SUBSET, or SCOPE_MAINLY_SUBSET

setScope

public void setScope(byte scope)

Sets the scope for the next layout run. The scope determines which of the nodes should be affected and how they should be affected by the layout run.

Parameters:

scope - the new scope, should be one of SCOPE_ALL, SCOPE_SUBSET, or SCOPE_MAINLY_SUBSET

getCompactness

public double getCompactness()

Returns the property for the compactness of the resulting layout. Lower values result in less compact drawings.

Returns:

a value indicating the resulting compactness in [0.0d .. 1.0d].

setCompactness

public void setCompactness(double compactness)

Sets the compactness property for the next layout run. Smaller values result in less compact drawings, greater values result in more compact drawings with 0.5d being a "normal" compactness.

Parameters:

compactness - the new compactness value [0.0d .. 1.0d]

getPreferredEdgeLength

public double getPreferredEdgeLength()

Returns the currently set default preferred edge length. The algorithm will try to find a drawing where most of the edges have this length. This default is applied to all edges where there is no specific edge length given using the double DataProvider instance bound to the graph using the PREFERRED_EDGE_LENGTH_DATA key.

Returns:

the preferred default length for edges

setPreferredEdgeLength

public void setPreferredEdgeLength(double preferredEdgeLength)

Sets the default preferred edge length for the next algorithm run.

Parameters:

preferredEdgeLength - the new default preferred edge length

See Also:

getPreferredEdgeLength()

getPreferredMinimalNodeDistance

public double getPreferredMinimalNodeDistance()

Returns the current preferred minimal node distance this algorithm should use for pairs of nodes that are not directly connected by adjacent edges.

Returns:

the preferred minimal distance

setPreferredMinimalNodeDistance

public void setPreferredMinimalNodeDistance(double preferredMinimalNodeDistance)

Sets the minimal node distance this algorithm should try to obey for the next run.

Parameters:

preferredMinimalNodeDistance - the new preferred minimal distance between two nodes that are not directly connected to each other

isNodeSizeAware

public boolean isNodeSizeAware()

Determines whether the algorithm should consider the size of the nodes for the layout. If set to true the algorithm will take the node size into account for given preferred edge lengths.

Returns:

whether node sizes are considered during the core layout

setNodeSizeAware

public void setNodeSizeAware(boolean nodeSizeAware)

Instructs the algorithm to consider node sizes for the next layout run. These settings do not affect the hard minimal node distance property.

Parameters:

nodeSizeAware - whether to consider the size of the nodes for the next layout run

isDeterministic

public boolean isDeterministic()

Returns whether the algorithm will behave deterministically in the next layout run.

Returns:

the current setting for the next layout run

setDeterministic

public void setDeterministic(boolean deterministic)

Sets this algorithm to deterministic mode. If set to true, the algorithm will yield the same results if given the exact same input and same settings.

Parameters:

deterministic - whether to operate in deterministic mode

getMinimalNodeDistance

public double getMinimalNodeDistance()

Returns the current minimal node distance this algorithm should enforce if the node overlaps allowance property is set to true.

Returns:

Value of property minimalNodeDistance.

setMinimalNodeDistance

public void setMinimalNodeDistance(double minimalNodeDistance)

Sets the minimal node distance this algorithm should enforce between all pairs of nodes for the next run.

Parameters:

minimalNodeDistance - the minimal distance between nodes that are not interconnected by a common edge

See Also:

setNodeOverlapsAllowed(boolean)

isNodeOverlapsAllowed

public boolean isNodeOverlapsAllowed()

Returns whether node overlaps are allowed (but not encouraged) for the next run.

Returns:

whether node overlaps are allowed to exist after the layout run

setNodeOverlapsAllowed

public void setNodeOverlapsAllowed(boolean nodeOverlapsAllowed)

Determines whether the next layout run should enforce non-overlapping nodes. The minimal distance between each pair of nodes is determined by the minimal node distance property.

Parameters:

nodeOverlapsAllowed - whether to allow node overlaps

See Also:

setMinimalNodeDistance(double)

setOutputRestriction

public void setOutputRestriction(OutputRestriction restriction)

Sets a restriction on the output generated by this layouter

Parameters:

restriction - the restriction to use

See Also:

OutputRestriction.NONE, OutputRestriction

getOutputRestriction

public OutputRestriction getOutputRestriction()

Returns the current OutputRestriction instance set for this instance. The default is OutputRestriction.NONE.

Returns:

an OutputRestriction