com.yworks.yfiles.layout.router

Class OrganicEdgeRouter

java.lang.Object

com.yworks.yfiles.layout.router.OrganicEdgeRouter

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class OrganicEdgeRouter
extends Object
implements ILayoutStage

This edge routing algorithm applies organic routes to the edges of the graph.

Layout Style

Edges are routed organically, i.e. in smooth curves around the nodes observing a minimum distance to the nodes.

During the routing process, the positions of the nodes are considered to be fixed and the router will not modify their locations or their sizes in any way.

The edge routing algorithm can be applied whenever edge paths should avoid crossing any nodes in organic or cyclic layout styles.

Concept

The edge routing algorithm uses a force-directed approach to calculate the edge paths. Nodes are considered to be repulsive forces while edges will try to become as short as possible.

Each edge is routed separately and is influenced by the nodes in a certain area around it. The algorithm will add bends to the edge path that are placed by balancing the forces.

The quality of the result highly depends on how much space there is between the nodes. More precisely, the distance between each pair of nodes should be at least twice the specified minimum distance. If it is not necessary that the nodes keep their locations, this can be ensured using a combination of RemoveOverlapsStage and node enlargement stage.

Features

MinimumDistance will make edges keep a custom distance to the nodes. However, if there is not enough space between the nodes, this distance may be undershot (i.e. edges will be closer to nodes).

OrganicEdgeRouter is able to reuse existing bends. Edges will contain those bends along with other bends added by the layout algorithm.

This edge routing algorithm is realized as a ILayoutStage which can be applied to a graph directly or using a core layout algorithm.

Field Summary

Fields

Modifier and Type	Field and Description
static EdgeDpKey<Boolean>	AFFECTED_EDGES_DPKEY A DataProvider key for selecting edges that should be routed

Constructor Summary

Constructors

Constructor and Description
OrganicEdgeRouter() Creates a new OrganicEdgeRouter instance with the default settings.
OrganicEdgeRouter(ILayoutAlgorithm core) Creates a new OrganicEdgeRouter with the given core layout algorithm.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Performs the organic routing of the edges of the input graph.
protected void	checkNodeSize(LayoutGraph g) Checks the sizes of the nodes to be non-zero.
ILayoutStage	createNodeEnlargementStage() Returns a ILayoutStage which temporarily increases the sizes of the nodes to avoid overlaps.
ILayoutAlgorithm	getCoreLayout() Gets the core layout algorithm which arranges the graph before edge routing.
double	getMinimumDistance() Gets the minimum distance the algorithm should guarantee between nodes and non-incident edges.
boolean	isEdgeNodeOverlapAllowed() Gets whether or not edges are allowed to cross nodes.
boolean	isKeepingExistingBendsEnabled() Gets whether or not the initial bend coordinates are kept when determining the edge path.
boolean	isRoutingAllEdgesEnabled() Gets whether a rerouting step is performed on all edges or just on a subset where distances are violated.
void	setCoreLayout(ILayoutAlgorithm value) Sets the core layout algorithm which arranges the graph before edge routing.
void	setEdgeNodeOverlapAllowed(boolean value) Sets whether or not edges are allowed to cross nodes.
void	setKeepingExistingBendsEnabled(boolean value) Sets whether or not the initial bend coordinates are kept when determining the edge path.
void	setMinimumDistance(double value) Sets the minimum distance the algorithm should guarantee between nodes and non-incident edges.
void	setRoutingAllEdgesEnabled(boolean value) Sets whether a rerouting step is performed on all edges or just on a subset where distances are violated.

Methods inherited from class java.lang.Object

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

Field Detail

AFFECTED_EDGES_DPKEY

public static final EdgeDpKey<Boolean> AFFECTED_EDGES_DPKEY

A DataProvider key for selecting edges that should be routed

Constructor Detail

OrganicEdgeRouter

public OrganicEdgeRouter()

Creates a new OrganicEdgeRouter instance with the default settings.

OrganicEdgeRouter

public OrganicEdgeRouter(ILayoutAlgorithm core)

Creates a new OrganicEdgeRouter with the given core layout algorithm.

Parameters:

core - the core layout algorithm

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Performs the organic routing of the edges of the input graph.

Specified by:

applyLayout in interface ILayoutAlgorithm

The given graph will not be copied during the edge routing process and the result will be immediately applied to the input graph.

Parameters:

graph - the input graph

checkNodeSize

protected void checkNodeSize(LayoutGraph g)

Checks the sizes of the nodes to be non-zero.

Parameters:

g - The graph to check.

createNodeEnlargementStage

public ILayoutStage createNodeEnlargementStage()

Returns a ILayoutStage which temporarily increases the sizes of the nodes to avoid overlaps.

The edges will keep a greater distance to the nodes. Therefore, they won't cross them.

The stage should be used in conjunction with RemoveOverlapsStage, see the provided example. The following example demonstrates how to use this stage:

 OrganicEdgeRouter router = new OrganicEdgeRouter();
 CompositeLayoutStage cls = new CompositeLayoutStage();
 cls.AppendStage(router.CreateNodeEnlargementStage());
 cls.AppendStage(new RemoveOverlapsLayoutStage(0));
 router.CoreLayouter = cls;
 graph.ApplyLayout(router);
 

Returns:

the ILayoutStage that resizes the nodes

getCoreLayout

public ILayoutAlgorithm getCoreLayout()

Gets the core layout algorithm which arranges the graph before edge routing.

Specified by:

getCoreLayout in interface ILayoutStage

Default Value:

The default value is null.

Returns:

the layout algorithm that arranges the graph

See Also:

setCoreLayout(ILayoutAlgorithm)

getMinimumDistance

public double getMinimumDistance()

Gets the minimum distance the algorithm should guarantee between nodes and non-incident edges.

The distance also influences how many bends are added to the path (a higher distance leads to less bends).

The minimum distance is defined to be a non-negative value.

Throws:

IllegalArgumentException - if the given minimum distance is negative

For best results, the distance should be at least 10.

If there is not enough space, the minimum distance may not be respected.

Default Value:

The default value is 10.

Returns:

the non-negative minimum distance between edges and nodes

See Also:

setMinimumDistance(double)

isEdgeNodeOverlapAllowed

public boolean isEdgeNodeOverlapAllowed()

Gets whether or not edges are allowed to cross nodes.

Allowing edges to overlap with nodes will produce smoother edges, because the edge paths can be closer to the nodes.

If nodes cannot be enlarged, e.g., because the nodes should not move, allowing overlaps between nodes and edges may lead to better results in case the distances between nodes are small. The minimum distance cannot always be maintained.

Default Value:

The default value is true. Edges are allowed to cross nodes.

Returns:

true if edge-node overlaps are allowed, false otherwise

See Also:

createNodeEnlargementStage(), setMinimumDistance(double), setEdgeNodeOverlapAllowed(boolean)

isKeepingExistingBendsEnabled

public boolean isKeepingExistingBendsEnabled()

Gets whether or not the initial bend coordinates are kept when determining the edge path.

The bends are considered as fixed nodes and stay part of the path.

Default Value:

The default value is false. Bends in the input graph are not considered for edge routing.

Returns:

true if the initial bend coordinates are kept, false otherwise

See Also:

setKeepingExistingBendsEnabled(boolean)

isRoutingAllEdgesEnabled

public boolean isRoutingAllEdgesEnabled()

Gets whether a rerouting step is performed on all edges or just on a subset where distances are violated.

If only a subset of edges is rerouted, only those edges which cross nodes or come too close to a node are included. During rerouting, more bends are added to the edges that will be influenced by the repulsive forces.

Rerouting all edges will result in a more organic routing that considers the minimum distances more closely. Disabling this feature, i.e., keeping the first calculated path will take less runtime.

Default Value:

The default value is false. Only edges being too close to nodes are rerouted.

Returns:

true if all edges are rerouted, false if only a subset is rerouted

See Also:

setRoutingAllEdgesEnabled(boolean)

setCoreLayout

public void setCoreLayout(ILayoutAlgorithm value)

Sets the core layout algorithm which arranges the graph before edge routing.

Specified by:

setCoreLayout in interface ILayoutStage

Default Value:

The default value is null.

Parameters:

value - the layout algorithm that arranges the graph

See Also:

getCoreLayout()

setEdgeNodeOverlapAllowed

public void setEdgeNodeOverlapAllowed(boolean value)

Sets whether or not edges are allowed to cross nodes.

Allowing edges to overlap with nodes will produce smoother edges, because the edge paths can be closer to the nodes.

If nodes cannot be enlarged, e.g., because the nodes should not move, allowing overlaps between nodes and edges may lead to better results in case the distances between nodes are small. The minimum distance cannot always be maintained.

Default Value:

The default value is true. Edges are allowed to cross nodes.

Parameters:

value - true if edge-node overlaps are allowed, false otherwise

See Also:

createNodeEnlargementStage(), setMinimumDistance(double), isEdgeNodeOverlapAllowed()

setKeepingExistingBendsEnabled

public void setKeepingExistingBendsEnabled(boolean value)

Sets whether or not the initial bend coordinates are kept when determining the edge path.

The bends are considered as fixed nodes and stay part of the path.

Default Value:

The default value is false. Bends in the input graph are not considered for edge routing.

Parameters:

value - true if the initial bend coordinates are kept, false otherwise

See Also:

isKeepingExistingBendsEnabled()

setMinimumDistance

public void setMinimumDistance(double value)

Sets the minimum distance the algorithm should guarantee between nodes and non-incident edges.

The distance also influences how many bends are added to the path (a higher distance leads to less bends).

The minimum distance is defined to be a non-negative value.

Throws:

IllegalArgumentException - if the given minimum distance is negative

For best results, the distance should be at least 10.

If there is not enough space, the minimum distance may not be respected.

Default Value:

The default value is 10.

Parameters:

value - the non-negative minimum distance between edges and nodes

See Also:

getMinimumDistance()

setRoutingAllEdgesEnabled

public void setRoutingAllEdgesEnabled(boolean value)

Sets whether a rerouting step is performed on all edges or just on a subset where distances are violated.

If only a subset of edges is rerouted, only those edges which cross nodes or come too close to a node are included. During rerouting, more bends are added to the edges that will be influenced by the repulsive forces.

Rerouting all edges will result in a more organic routing that considers the minimum distances more closely. Disabling this feature, i.e., keeping the first calculated path will take less runtime.

Default Value:

The default value is false. Only edges being too close to nodes are rerouted.

Parameters:

value - true if all edges are rerouted, false if only a subset is rerouted

See Also:

isRoutingAllEdgesEnabled()