com.yworks.yfiles.layout.organic

Class ShuffleLayout

java.lang.Object

com.yworks.yfiles.layout.organic.ShuffleLayout

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class ShuffleLayout
extends Object
implements ILayoutStage

This layout algorithm removes overlaps between nodes in a graph.

Note: The usage of RemoveOverlapsStage instead of this class is recommended for most use cases involving the mere removal of overlaps. That stage offers a more powerful strategy to do the task.

Layout Style

The style of results often resembles the look of tiles which have been dropped onto each other, where tiles correspond to nodes of the graph. The reason is that overlapping nodes are moved in order to resolve the overlap. During this process, several nodes moving in the same direction may be stacked next to or above each other.

This algorithm does not route the edges of the input graph - edges might although be stretched due to the node movement.

Example with overlaps (left) and after executing the shuffle layout (right) Example with overlaps (left) and after executing the shuffle layout (right)

Concept

Nodes overlapping with other nodes will be moved in horizontal or vertical direction in order to remove overlaps. The concept behind this removal step is based on a famous Russian arcade game.

Features

This layout stage can also be executed on its own, without specifying a core layout algorithm.

A minimum distance between nodes can be specified such that not only overlaps will be removed but nodes will keep this specified distance to other nodes. This distance can be defined separately for each node using a IDataProvider registered with key MINIMUM_DISTANCE_DPKEY. The minimum distance can also be specified globally via MinimumNodeDistance.

To specify that specific nodes should not be moved, they can be marked as fixed using a IDataProvider registered with key FIXED_NODE_DPKEY.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<Boolean>	FIXED_NODE_DPKEY A DataProvider key for marking nodes as fixed A node marked as fixed will not be moved by this algorithm but stay at its current position.
static NodeDpKey<Double>	MINIMUM_DISTANCE_DPKEY A DataProvider key for specifying a minimum distance for each node The default minimum distance specified by MinimumNodeDistance will be ignored for a node if the IDataProvider registered with this key contains a valid minimum distance for that node.

Constructor Summary

Constructors

Constructor and Description
ShuffleLayout() Creates a new instance of ShuffleLayout with default settings.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Performs the overlap removal (shuffle) algorithm on the given graph, after the core layout algorithm was applied to it.
ILayoutAlgorithm	getCoreLayout() Gets the core layout algorithm.
HorizontalOverlapCriterion	getHorizontalOverlapCriterion() Gets the criterion for marking an overlap as horizontal.
double	getMinimumNodeDistance() Gets the default minimum distance that has to be obeyed between any two nodes.
boolean	isBarycenterModeEnabled() Gets whether or not the barycenter mode is used for node shuffling when removing overlaps.
boolean	isSimpleModeEnabled() Gets whether or not the simple, fast layout mode of this algorithm is active.
void	setBarycenterModeEnabled(boolean value) Sets whether or not the barycenter mode is used for node shuffling when removing overlaps.
void	setCoreLayout(ILayoutAlgorithm value) Sets the core layout algorithm.
void	setHorizontalOverlapCriterion(HorizontalOverlapCriterion value) Sets the criterion for marking an overlap as horizontal.
void	setMinimumNodeDistance(double value) Sets the default minimum distance that has to be obeyed between any two nodes.
void	setSimpleModeEnabled(boolean value) Sets whether or not the simple, fast layout mode of this algorithm is active.

Methods inherited from class java.lang.Object

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

Field Detail

FIXED_NODE_DPKEY

public static final NodeDpKey<Boolean> FIXED_NODE_DPKEY

A DataProvider key for marking nodes as fixed

A node marked as fixed will not be moved by this algorithm but stay at its current position.

If two nodes overlap and both nodes are fixed, then this algorithm will not remove the corresponding overlap.

MINIMUM_DISTANCE_DPKEY

public static final NodeDpKey<Double> MINIMUM_DISTANCE_DPKEY

A DataProvider key for specifying a minimum distance for each node

The default minimum distance specified by MinimumNodeDistance will be ignored for a node if the IDataProvider registered with this key contains a valid minimum distance for that node.

Minimum distance values need to be greater than 0.

If no IDataProvider with this key is registered, the minimum distance for all nodes is specified by MinimumNodeDistance.

Constructor Detail

ShuffleLayout

public ShuffleLayout()

Creates a new instance of ShuffleLayout with default settings.

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Performs the overlap removal (shuffle) algorithm on the given graph, after the core layout algorithm was applied to it.

Specified by:

applyLayout in interface ILayoutAlgorithm

Parameters:

graph - the input graph

getCoreLayout

public ILayoutAlgorithm getCoreLayout()

Description copied from interface: ILayoutStage

Gets the core layout algorithm.

This algorithm is wrapped by this stage. It is invoked in ILayoutAlgorithm.applyLayout(com.yworks.yfiles.layout.LayoutGraph). The ILayoutStage may add pre- and post-processing steps before and after calling the core layout algorithm.

Specified by:

getCoreLayout in interface ILayoutStage

Returns:

the core layout algorithm

See Also:

ILayoutStage.setCoreLayout(ILayoutAlgorithm)

getHorizontalOverlapCriterion

public HorizontalOverlapCriterion getHorizontalOverlapCriterion()

Gets the criterion for marking an overlap as horizontal.

This criterion influences how overlaps will be resolved. If an overlap is considered horizontal, it will preferably be solved by moving nodes horizontally, else vertically.

Throws:

IllegalArgumentException - if the given criterion is unknown

This criterion will only have an effect if the simple mode is disabled.

Default Value:

The default value is HorizontalOverlapCriterion.LESS_MOVEMENT

Returns:

one of the predefined overlap criteria

See Also:

setHorizontalOverlapCriterion(HorizontalOverlapCriterion)

getMinimumNodeDistance

public double getMinimumNodeDistance()

Gets the default minimum distance that has to be obeyed between any two nodes.

This default distance will be considered for a node if the IDataProvider registered with the graph with key MINIMUM_DISTANCE_DPKEY does not contain a valid, positive distance for that node. If there is no IDataProvider registered with the mentioned key, then this default distance will be applied to all nodes.

The minimum distance needs to be a non-negative value.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 5.

Returns:

the non-negative minimum node distance

See Also:

MINIMUM_DISTANCE_DPKEY, setMinimumNodeDistance(double)

isBarycenterModeEnabled

public boolean isBarycenterModeEnabled()

Gets whether or not the barycenter mode is used for node shuffling when removing overlaps.

If this mode is active, the overlap removal step will be executed two times for each direction, once with the normal node ordering and once with the reversed ordering. Finally, the barycenter between both results will be used for assigning the node coordinates.

Activating the barycenter mode allows more symmetric results for some graphs. However, the runtime might increase.

Default Value:

The default value is false. The barycenter mode is disabled.

Returns:

true if the barycenter placement mode is active false otherwise

See Also:

setBarycenterModeEnabled(boolean)

isSimpleModeEnabled

public boolean isSimpleModeEnabled()

Gets whether or not the simple, fast layout mode of this algorithm is active.

Enabling this mode, the overlap removal step will be executed using a simpler and less sophisticated approach. All overlaps will only be solved by moving nodes vertically. The algorithm will not try to figure out which direction might be better for overlap removal.

The runtime will improve, but results may be of lower quality when using this mode.

When enabling this mode, the specified horizontal overlap criterion will not have any effect.

Default Value:

The default value is false.

Returns:

true if the simple and fast layout mode is enabled, false otherwise.

See Also:

setSimpleModeEnabled(boolean)

setBarycenterModeEnabled

public void setBarycenterModeEnabled(boolean value)

Sets whether or not the barycenter mode is used for node shuffling when removing overlaps.

If this mode is active, the overlap removal step will be executed two times for each direction, once with the normal node ordering and once with the reversed ordering. Finally, the barycenter between both results will be used for assigning the node coordinates.

Activating the barycenter mode allows more symmetric results for some graphs. However, the runtime might increase.

Default Value:

The default value is false. The barycenter mode is disabled.

Parameters:

value - true if the barycenter placement mode is active false otherwise

See Also:

isBarycenterModeEnabled()

setCoreLayout

public void setCoreLayout(ILayoutAlgorithm value)

Description copied from interface: ILayoutStage

Sets the core layout algorithm.

This algorithm is wrapped by this stage. It is invoked in ILayoutAlgorithm.applyLayout(com.yworks.yfiles.layout.LayoutGraph). The ILayoutStage may add pre- and post-processing steps before and after calling the core layout algorithm.

Specified by:

setCoreLayout in interface ILayoutStage

Parameters:

value - the core layout algorithm

See Also:

ILayoutStage.getCoreLayout()

setHorizontalOverlapCriterion

public void setHorizontalOverlapCriterion(HorizontalOverlapCriterion value)

Sets the criterion for marking an overlap as horizontal.

This criterion influences how overlaps will be resolved. If an overlap is considered horizontal, it will preferably be solved by moving nodes horizontally, else vertically.

Throws:

IllegalArgumentException - if the given criterion is unknown

This criterion will only have an effect if the simple mode is disabled.

Default Value:

The default value is HorizontalOverlapCriterion.LESS_MOVEMENT

Parameters:

value - one of the predefined overlap criteria

See Also:

getHorizontalOverlapCriterion()

setMinimumNodeDistance

public void setMinimumNodeDistance(double value)

Sets the default minimum distance that has to be obeyed between any two nodes.

This default distance will be considered for a node if the IDataProvider registered with the graph with key MINIMUM_DISTANCE_DPKEY does not contain a valid, positive distance for that node. If there is no IDataProvider registered with the mentioned key, then this default distance will be applied to all nodes.

The minimum distance needs to be a non-negative value.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 5.

Parameters:

value - the non-negative minimum node distance

See Also:

MINIMUM_DISTANCE_DPKEY, getMinimumNodeDistance()

setSimpleModeEnabled

public void setSimpleModeEnabled(boolean value)

Sets whether or not the simple, fast layout mode of this algorithm is active.

Enabling this mode, the overlap removal step will be executed using a simpler and less sophisticated approach. All overlaps will only be solved by moving nodes vertically. The algorithm will not try to figure out which direction might be better for overlap removal.

The runtime will improve, but results may be of lower quality when using this mode.

When enabling this mode, the specified horizontal overlap criterion will not have any effect.

Default Value:

The default value is false.

Parameters:

value - true if the simple and fast layout mode is enabled, false otherwise.

See Also:

isSimpleModeEnabled()