y.layout
Class EdgeBundling

java.lang.Object
  y.layout.EdgeBundling

public class EdgeBundling
extends java.lang.Object

An EdgeBundling instance defines if and how the edges of a graph should be bundled by a layout algorithm, given that the algorithm supports edge bundling.

Bundling together multiple edges means that their common parts are to some degree merged into a bundled part. At the source and target point, the edges are again clearly split. Edge bundling is useful to increase the readability of graph drawings with a high number of edges that connect a comparably small number of nodes. Without bundling, such drawings can often contain visual clutter and feature bad readability.

The bundling strength and quality are global settings for the bundling process. On the other hand, each edge can get specific settings by assigning a EdgeBundleDescriptor to it. A DataProvider can be registered with the input graph with key EDGE_BUNDLE_DESCRIPTOR_DPKEY to assign descriptors to edges. This allows, for example, to define which edges should actually be bundled.

The following layout algorithms/stages currently support bundling.

• CircularLayouter
• RadialLayouter
• TreeReductionStage: only for graphs that do not contain multi-parent structures
• EdgeBundlingStage: a generic bundling stage, any core layout algorithm may be used

Example of edge bundling with CircularLayouter

Example of edge bundling when applying TreeReductionStage and BalloonLayouter on a general graph

See Also:

EdgeBundleDescriptor, CircularLayouter.getEdgeBundling(), RadialLayouter.getEdgeBundling(), TreeReductionStage.getEdgeBundling(), EdgeBundlingStage.getEdgeBundling()

Field Summary

static java.lang.Object

EDGE_BUNDLE_DESCRIPTOR_DPKEY A DataProvider key for specifying individual bundling settings for edges If no EdgeBundleDescriptor is mapped to an edge, the default descriptor is used by the layout algorithm to obtain the bundling setup of that edge.

Constructor Summary

EdgeBundling()
Creates a new EdgeBundling instance with default settings.

EdgeBundling(double bundlingStrength, double bundlingQuality)
Creates a new EdgeBundling instance with the given bundling strength and bundling quality.

Method Summary

double	getBundlingQuality() Returns the desired quality of the calculated edge bundling.
double	getBundlingStrength() Returns the strength of the edge bundling.
EdgeBundleDescriptor	getDefaultBundleDescriptor() Returns the default EdgeBundleDescriptor used for all edges which do not have a specific descriptor assigned via a DataProvider registered with key EDGE_BUNDLE_DESCRIPTOR_DPKEY.
void	setBundlingQuality(double bundlingQuality) Specifies the desired quality of the calculated edge bundling.
void	setBundlingStrength(double bundlingStrength) Specifies the strength of the edge bundling.
void	setDefaultBundleDescriptor(EdgeBundleDescriptor defaultBundleDescriptor) Specifies the default EdgeBundleDescriptor used for all edges which do not have a specific descriptor assigned via a DataProvider registered with key EDGE_BUNDLE_DESCRIPTOR_DPKEY.

Methods inherited from class java.lang.Object

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

Field Detail

EDGE_BUNDLE_DESCRIPTOR_DPKEY

public static final java.lang.Object EDGE_BUNDLE_DESCRIPTOR_DPKEY

A DataProvider key for specifying individual bundling settings for edges

If no EdgeBundleDescriptor is mapped to an edge, the default descriptor is used by the layout algorithm to obtain the bundling setup of that edge.

See Also:

getDefaultBundleDescriptor()

Constructor Detail

EdgeBundling

public EdgeBundling()

Creates a new EdgeBundling instance with default settings.

EdgeBundling

public EdgeBundling(double bundlingStrength,
                    double bundlingQuality)

Creates a new EdgeBundling instance with the given bundling strength and bundling quality.

Parameters:

bundlingStrength - the bundling strength from the interval [0,1]

bundlingQuality - the bundling quality from the interval [0,1]

Throws:

java.lang.IllegalArgumentException - if the given bundling strength or quality is not within [0,1]

Method Detail

getBundlingQuality

public double getBundlingQuality()

Returns the desired quality of the calculated edge bundling.

Higher quality indicates that the bundling procedure uses more sophisticated methods to compute the actual bundles and the routing of the edges. If the applied layout algorithm is the CircularLayouter, this may lead to a significantly higher running time, especially for large graphs. On the other hand, a low quality indicates that run-time is more important than highly optimized bundling results, leading to, for example, more crossings between different bundles (for CircularLayouter) or completely straight-line un-bundled edges for the EdgeBundlingStage.

The quality is defined to lie within [0,1], where higher values stand for higher quality.

This feature has an effect if the applied layout algorithm is the CircularLayouter or the EdgeBundlingStage.

Returns:

a value between 0 (low quality, fast) and 1 (high quality, slow)

See Also:

setBundlingQuality(double)

setBundlingQuality

public void setBundlingQuality(double bundlingQuality)

Specifies the desired quality of the calculated edge bundling.

Higher quality indicates that the bundling procedure uses more sophisticated methods to compute the actual bundles and the routing of the edges. If the applied layout algorithm is the CircularLayouter, this may lead to a significantly higher running time, especially for large graphs. On the other hand, a low quality indicates that run-time is more important than highly optimized bundling results, leading to, for example, more crossings between different bundles (for CircularLayouter) or completely straight-line un-bundled edges for the EdgeBundlingStage.

The quality is defined to lie within [0,1], where higher values stand for higher quality.

This feature has an effect if the applied layout algorithm is the CircularLayouter or the EdgeBundlingStage.

Default Value:

The default value is 0.5.

Parameters:

bundlingQuality - a value between 0 (low quality, fast) and 1 (high quality, slow)

Throws:

java.lang.IllegalArgumentException - if the given quality value is not within [0,1]

getBundlingStrength

public double getBundlingStrength()

Returns the strength of the edge bundling.

The strength controls how tightly the edges are bundled and influences the shape of the curves of bundled edges. Low values lead to only slightly bundled edges; results will mostly show individual node-to-node connectivity information. High values show the connectivity on a higher level, strongly bundling edges together and generating highly curved edge paths.

The bundling strength is defined as a value from the interval [0,1].

For all other algorithms except from the EdgeBundlingStage, to obtain results with clearly observable larger bundles, it is recommended to use a strength value of 0.8 or higher. For the EdgeBundlingStage, it is recommended to use a value, close to 0.4.

A bundling strength of 0 leads to straight-line edges where edges are basically not bundled.

For the EdgeBundlingStage, high values can significantly affect the performance of the algorithm, especially for large graphs.

Returns:

the bundling strength between 0 (no bundling) and 1 (strongly bundled edges).

See Also:

setBundlingStrength(double)

setBundlingStrength

public void setBundlingStrength(double bundlingStrength)

Specifies the strength of the edge bundling.

The strength controls how tightly the edges are bundled and influences the shape of the curves of bundled edges. Low values lead to only slightly bundled edges; results will mostly show individual node-to-node connectivity information. High values show the connectivity on a higher level, strongly bundling edges together and generating highly curved edge paths.

The bundling strength is defined as a value from the interval [0,1].

For all other algorithms except from the EdgeBundlingStage, to obtain results with clearly observable larger bundles, it is recommended to use a strength value of 0.8 or higher. For the EdgeBundlingStage, it is recommended to use a value, close to 0.4.

A bundling strength of 0 leads to straight-line edges where edges are basically not bundled.

For the EdgeBundlingStage, high values can significantly affect the performance of the algorithm, especially for large graphs.

Default Value:

The default value is 0.95.

Parameters:

bundlingStrength - the bundling strength between 0 (no bundling) and 1 (strongly bundled edges).

Throws:

java.lang.IllegalArgumentException - if the given strength is less than 0 or greater than 1

Sample Graphs:

0.95 (using CircularLayouter)

1.0 (using CircularLayouter)

0.8 (using CircularLayouter)

0.0 (using CircularLayouter)

getDefaultBundleDescriptor

public EdgeBundleDescriptor getDefaultBundleDescriptor()

Returns the default EdgeBundleDescriptor used for all edges which do not have a specific descriptor assigned via a DataProvider registered with key EDGE_BUNDLE_DESCRIPTOR_DPKEY.

Returns:

the default descriptor responsible for edges with no specific descriptor

See Also:

EDGE_BUNDLE_DESCRIPTOR_DPKEY, setDefaultBundleDescriptor(EdgeBundleDescriptor)

setDefaultBundleDescriptor

public void setDefaultBundleDescriptor(EdgeBundleDescriptor defaultBundleDescriptor)

Specifies the default EdgeBundleDescriptor used for all edges which do not have a specific descriptor assigned via a DataProvider registered with key EDGE_BUNDLE_DESCRIPTOR_DPKEY.

Default Value:

The default value is EdgeBundleDescriptor

Parameters:

defaultBundleDescriptor - the default descriptor responsible for edges with no specific descriptor

Throws:

java.lang.IllegalArgumentException - if the given descriptor is null

See Also:

EDGE_BUNDLE_DESCRIPTOR_DPKEY