y.layout.organic
Class SplitEdgeLayoutStage

java.lang.Object
  y.layout.organic.SplitEdgeLayoutStage

All Implemented Interfaces:

Layouter, LayoutStage

public class SplitEdgeLayoutStage
extends java.lang.Object
implements LayoutStage

This layout stage replaces edges by a path of split-edges with a specified length before it calls a core layout algorithm.

Concept

Each edge segment (or only segments that belong to a particular subset of edges) in the input graph will be split up into several segments such that all segments have a maximum length defined by the specified split segment length. If an edge segment is already shorter than the split segment length, then it will not be split up.

At each split location, a dummy node (the so-called split-node) will be inserted. Split-nodes inserted for the same original edge and the actual source and target node of the original edge will be connected by so called split-edges. In consequence, the original source and target node are not connected by a single edge but by a path consisting of split-edges. Furthermore, all edges are simple straight lines.

After this replacement step, the core layout algorithm will be invoked.

When the core layout algorithm has finished, the split-nodes will be removed from the graph and the original edge will be restored. The coordinates of the bends will be the center-coordinates of the corresponding split-node.

Features

The DataProvider registered with key getSplitNodesDpKey() can be used by the core layout algorithm to determine whether or not a certain node is a split-node that was created by this stage. This information may be useful when providing a custom core layout algorithm which should handle split-nodes in a different way than normal nodes. If no DataProvider is registered with this key, this information is dropped.

By registering a DataProvider with key getSplitEdgesDpKey(), the subset of edges that should be split by this layout stage can be specified. If no DataProvider with this key is registered, all edges of the input graph will be split by the layout stage.

The amount of split-nodes replacing a single original edge can be controlled via the split segment length. The smaller the value, the more split-nodes this stage will insert.

This stage can be useful if bends should be kept, even when using a layout algorithm which generally only draws straight-line edges. Simply specify the straight-line algorithm as core layout algorithm and execute this stage.

Field Summary

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

SplitEdgeLayoutStage()
Creates a new SplitEdgeLayoutStage with default settings.

Method Summary

boolean	canLayout(LayoutGraph graph) Accepts general graphs without exception.
void	doLayout(LayoutGraph graph) Replaces the edges of the given graph by a path of split-edges, executes the core layout algorithm and restores the original edges, introducing bends at the locations of the split-nodes.
Layouter	getCoreLayouter() Returns the core layout algorithm.
double	getProxyNodeSize() Returns the size of the split-nodes that are inserted when splitting edges.
java.lang.Object	getSplitEdgesDpKey() Returns the DataProvider key to determine which edges are to be split by this layout stage.
java.lang.Object	getSplitNodesDpKey() Returns the DataProvider key for marking the nodes that were created by splitting edges, i.e., the split-nodes.
double	getSplitSegmentLength() Returns the maximum length for a split-edge.
void	setCoreLayouter(Layouter l) Specifies the core layout algorithm.
void	setProxyNodeSize(double splitNodeSize) Specifies the size of the split-nodes that are inserted when splitting edges.
void	setSplitEdgesDpKey(java.lang.Object key) Specifies the DataProvider key to determine which edges are to be split by this layout stage.
void	setSplitNodesDpKey(java.lang.Object key) Specifies the DataProvider key for marking the nodes that were created by splitting edges, i.e., the split-nodes.
void	setSplitSegmentLength(double splitSegmentLength) Specifies the maximum length for a split-edge.

Methods inherited from class java.lang.Object

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

Constructor Detail

SplitEdgeLayoutStage

public SplitEdgeLayoutStage()

Creates a new SplitEdgeLayoutStage with default settings.

Method Detail

getSplitEdgesDpKey

public java.lang.Object getSplitEdgesDpKey()

Returns the DataProvider key to determine which edges are to be split by this layout stage.

If no DataProvider is registered with this key, all edges will be split.

Returns:

the DataProvider key for marking edges that should be split

See Also:

setSplitEdgesDpKey(Object)

setSplitEdgesDpKey

public void setSplitEdgesDpKey(java.lang.Object key)

Specifies the DataProvider key to determine which edges are to be split by this layout stage.

If no DataProvider is registered with this key, all edges will be split.

Default Value:

The default value is Layouter.SELECTED_EDGES

Parameters:

key - the DataProvider key for marking edges that should be split

Throws:

java.lang.IllegalArgumentException - if the specified key is null

See Also:

getSplitEdgesDpKey()

getSplitNodesDpKey

public java.lang.Object getSplitNodesDpKey()

Returns the DataProvider key for marking the nodes that were created by splitting edges, i.e., the split-nodes.

The information provided by the DataProvider registered with this key is useful for the core layout algorithm to know whether or not some node is a (dummy) split-node. After doLayout(LayoutGraph) finishes, the split-nodes will have been removed and this information will not be available anymore.

If there is already a DataProvider registered with this key, information about marked nodes will be ignored by the stage during the layout process. However, this information will be restored after the layout has finished. However, it is recommended to specify a custom key - only used for this purpose - if the core layout algorithm should be able to clearly distinguish the newly created split-nodes.

Returns:

the DataProvider key for marking newly created split-nodes

See Also:

setSplitNodesDpKey(Object)

setSplitNodesDpKey

public void setSplitNodesDpKey(java.lang.Object key)

Specifies the DataProvider key for marking the nodes that were created by splitting edges, i.e., the split-nodes.

The information provided by the DataProvider registered with this key is useful for the core layout algorithm to know whether or not some node is a (dummy) split-node. After doLayout(LayoutGraph) finishes, the split-nodes will have been removed and this information will not be available anymore.

If there is already a DataProvider registered with this key, information about marked nodes will be ignored by the stage during the layout process. However, this information will be restored after the layout has finished. However, it is recommended to specify a custom key - only used for this purpose - if the core layout algorithm should be able to clearly distinguish the newly created split-nodes.

Default Value:

The default value is Layouter.SELECTED_NODES

Parameters:

key - the DataProvider key for marking newly created split-nodes

Throws:

java.lang.IllegalArgumentException - if the specified key is null

See Also:

getSplitNodesDpKey()

setSplitSegmentLength

public void setSplitSegmentLength(double splitSegmentLength)

Specifies the maximum length for a split-edge.

The length of the original edge path divided by the given split segment length yields the number of nodes on the new path.

The split segment length must be a strictly positive value.

Default Value:

The default value is 100.

Parameters:

splitSegmentLength - the split segment length

Throws:

java.lang.IllegalArgumentException - if the given split segment length is smaller than or equal to zero

getSplitSegmentLength

public double getSplitSegmentLength()

Returns the maximum length for a split-edge.

The length of the original edge path divided by the given split segment length yields the number of nodes on the new path.

The split segment length must be a strictly positive value.

Returns:

the split segment length

See Also:

setSplitSegmentLength(double)

getProxyNodeSize

public double getProxyNodeSize()

Returns the size of the split-nodes that are inserted when splitting edges.

The given size will be used for defining the height and the width of the split-nodes.

Since some layout algorithms cannot handle zero-sized nodes, the size needs to be increased when using this stage with such an algorithm as core layout algorithm.

Returns:

the size the inserted split nodes will have

See Also:

setProxyNodeSize(double)

setProxyNodeSize

public void setProxyNodeSize(double splitNodeSize)

Specifies the size of the split-nodes that are inserted when splitting edges.

The given size will be used for defining the height and the width of the split-nodes.

Since some layout algorithms cannot handle zero-sized nodes, the size needs to be increased when using this stage with such an algorithm as core layout algorithm.

Default Value:

The default value is 1.0.

Parameters:

splitNodeSize - the size the inserted split nodes will have

Throws:

java.lang.IllegalArgumentException - if the given size is negative

canLayout

public boolean canLayout(LayoutGraph graph)

Accepts general graphs without exception.

Specified by:

canLayout in interface Layouter

Parameters:

graph - the input graph

Returns:

true for all inputs

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

Replaces the edges of the given graph by a path of split-edges, executes the core layout algorithm and restores the original edges, introducing bends at the locations of the split-nodes.

Specified by:

doLayout in interface Layouter

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

See Also:

Layouter.canLayout(LayoutGraph)

getCoreLayouter

public Layouter getCoreLayouter()

Description copied from interface: LayoutStage

Returns the core layout algorithm. This algorithm is wrapped by this stage. It is invoked in Layouter.doLayout(LayoutGraph). The LayoutStage may add pre- and post-processing steps before and after calling the core layout algorithm.

Specified by:

getCoreLayouter in interface LayoutStage

Returns:

the core layout algorithm

setCoreLayouter

public void setCoreLayouter(Layouter l)

Description copied from interface: LayoutStage

Specifies the core layout algorithm. This algorithm is wrapped by this stage. It is invoked in Layouter.doLayout(LayoutGraph). The LayoutStage may add pre- and post-processing steps before and after calling the core layout algorithm.

Specified by:

setCoreLayouter in interface LayoutStage

Parameters:

l - the core layout algorithm