com.yworks.yfiles.layout.radial

Class RadialLayout

java.lang.Object

com.yworks.yfiles.layout.MultiStageLayout

com.yworks.yfiles.layout.radial.RadialLayout

All Implemented Interfaces:

ILayoutAlgorithm

public class RadialLayout
extends MultiStageLayout

This layout algorithm arranges graphs in a radial fashion.

Layout Style

The nodes are distributed into circles (layers) around a common center based on predefined layering strategies. Some potential applications include visualization of social networks, data clustering and bioinformatics. Sample output of the layout algorithm with default settings and one center node Sample output of the layout algorithm with straight-line edges and five center nodes using CenterNodesPolicy.CUSTOM policy

Concept

The layout algorithm creates a virtual tree structure for the input graph whose root node is placed in the center of the circles. All children of a tree node are placed on a higher layer (i.e. on a circle of larger radius) than their parent. A sector is calculated for each node such that the sector of each child node in the virtual tree is a sub-sector of its parent's sector. The radii of the circles are calculated based on the sizes of the sectors required to accommodate each whole subtree.

Features

There are different center nodes policies that can be applied in order to determine the nodes that will be placed in the center (single center node) or on the innermost circle (more than one center node). The distribution of the nodes to the circles is specified by a layering strategy.

The edges are routed based on the edge routing strategy. Note that the edge routing cannot always prevent node-edge overlaps.

The minimum distance between nodes of the same circle is specified using MinimumNodeToNodeDistance. If there are too many nodes assigned to a circle, the radius of the particular circle will be increased until all nodes fit onto it.

The distance between consecutive layers is specified using LayerSpacing. The radii of the circles are a multiple of this spacing value. If the layer spacing is 0, the radii are chosen such that all nodes fit on their corresponding circles. A minimum layer distance is specified by MinimumLayerDistance.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RadialLayout.NodeInfo Info object used for retrieving information about each node from the layout algorithm.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<RadialLayout.NodeInfo>	NODE_INFO_DPKEY A DataAcceptor key for publishing the circle ID and sector data For each node, the ID of the circle and data regarding the circular sector on which it was placed will be stored.

Constructor Summary

Constructors

Constructor and Description
RadialLayout() Creates a new RadialLayout instance with the default settings.

Method Summary

Modifier and Type	Method and Description
void	applyLayoutCore(LayoutGraph graph) Calculates a radial arrangement for the given graph.
Object	getCenterNodesDpKey() Gets the IDataProvider key used for looking up the selected nodes that should be placed in the center.
CenterNodesPolicy	getCenterNodesPolicy() Gets the policy that determines which nodes are selected as roots of the (virtual) tree for the layout process and are set in the center of the circles.
EdgeBundling	getEdgeBundling() Gets the EdgeBundling instance that defines the settings of the edge bundling feature.
EdgeRoutingStrategy	getEdgeRoutingStrategy() Gets the edge routing strategy.
LayeringStrategy	getLayeringStrategy() Gets the layering strategy that determines how nodes are distributed into different layers.
double	getLayerSpacing() Gets the spacing between two consecutive circles (layers).
double	getMaximumChildSectorAngle() Gets the maximum sector angle around a node within which the node's children will be placed.
double	getMinimumBendAngle() Gets the minimum bend angle (in degrees) between two adjacent edge segments.
double	getMinimumLayerDistance() Gets the minimum distance between two circles.
double	getMinimumNodeToNodeDistance() Gets the minimum distance between two neighboring nodes of the same circle.
boolean	isNodeLabelConsiderationEnabled() Gets whether or not node labels are taken into account when calculating node positions.
void	setCenterNodesDpKey(Object value) Sets the IDataProvider key used for looking up the selected nodes that should be placed in the center.
void	setCenterNodesPolicy(CenterNodesPolicy value) Sets the policy that determines which nodes are selected as roots of the (virtual) tree for the layout process and are set in the center of the circles.
void	setEdgeRoutingStrategy(EdgeRoutingStrategy value) Sets the edge routing strategy.
void	setLayeringStrategy(LayeringStrategy value) Sets the layering strategy that determines how nodes are distributed into different layers.
void	setLayerSpacing(double value) Sets the spacing between two consecutive circles (layers).
void	setMaximumChildSectorAngle(double value) Sets the maximum sector angle around a node within which the node's children will be placed.
void	setMinimumBendAngle(double value) Sets the minimum bend angle (in degrees) between two adjacent edge segments.
void	setMinimumLayerDistance(double value) Sets the minimum distance between two circles.
void	setMinimumNodeToNodeDistance(double value) Sets the minimum distance between two neighboring nodes of the same circle.
void	setNodeLabelConsiderationEnabled(boolean value) Sets whether or not node labels are taken into account when calculating node positions.
void	setOrientationLayoutEnabled(boolean value) Sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.

Methods inherited from class com.yworks.yfiles.layout.MultiStageLayout

appendStage, applyLayout, checkNodeSize, disableAllStages, getComponentLayout, getHideGroupsStage, getLabeling, getLayoutOrientation, getOrientationLayout, getParallelEdgeRouter, getSelfLoopRouter, getSubgraphLayout, isComponentLayoutEnabled, isHideGroupsStageEnabled, isLabelingEnabled, isOrientationLayoutEnabled, isParallelEdgeRouterEnabled, isSelfLoopRouterEnabled, isSubgraphLayoutEnabled, prependStage, removeStage, setComponentLayout, setComponentLayoutEnabled, setHideGroupsStage, setHideGroupsStageEnabled, setLabeling, setLabelingEnabled, setLayoutOrientation, setOrientationLayout, setParallelEdgeRouter, setParallelEdgeRouterEnabled, setSelfLoopRouter, setSelfLoopRouterEnabled, setSubgraphLayout, setSubgraphLayoutEnabled

Methods inherited from class java.lang.Object

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

Field Detail

NODE_INFO_DPKEY

public static final NodeDpKey<RadialLayout.NodeInfo> NODE_INFO_DPKEY

A DataAcceptor key for publishing the circle ID and sector data

For each node, the ID of the circle and data regarding the circular sector on which it was placed will be stored.

If no IDataProvider is registered with this key, information about circle ID and sector data will be dropped.

The layout algorithm will not take into account any settings that are initially specified by a RadialLayout.NodeInfo provided by the IDataProvider registered with this key. It is only intended to publish information after the layout has been calculated.

Constructor Detail

RadialLayout

public RadialLayout()

Creates a new RadialLayout instance with the default settings.

Method Detail

applyLayoutCore

public void applyLayoutCore(LayoutGraph graph)

Calculates a radial arrangement for the given graph.

Specified by:

applyLayoutCore in class MultiStageLayout

Parameters:

graph - the input graph

getCenterNodesDpKey

public Object getCenterNodesDpKey()

Gets the IDataProvider key used for looking up the selected nodes that should be placed in the center.

Throws:

IllegalArgumentException - if the specified key is null

This option will only take effect if center node policy is set to CenterNodesPolicy.CUSTOM.

Default Value:

The default value is LayoutKeys.AFFECTED_NODES_DPKEY. The selected nodes are placed in the center.

Returns:

the IDataProvider key for the selection of center nodes

See Also:

setCenterNodesDpKey(Object)

getCenterNodesPolicy

public CenterNodesPolicy getCenterNodesPolicy()

Gets the policy that determines which nodes are selected as roots of the (virtual) tree for the layout process and are set in the center of the circles.

Throws:

IllegalArgumentException - if an invalid center node policy is given

Default Value:

The default value is CenterNodesPolicy.WEIGHTED_CENTRALITY. The node determined using weighted centrality is placed in the center.

Returns:

one of the predefined center node policies

See Also:

setCenterNodesPolicy(CenterNodesPolicy)

getEdgeBundling

public EdgeBundling getEdgeBundling()

Gets the EdgeBundling instance that defines the settings of the edge bundling feature.

The specified EdgeBundling defines global bundling properties. Settings for individual edges can be defined by assigning an EdgeBundleDescriptor to an edge using a IDataProvider registered with key EdgeBundling.EDGE_BUNDLE_DESCRIPTOR_DPKEY.

To enable bundling for all edges, set a default bundle descriptor which has bundling enabled.

Edge bundling may be of low quality if the virtual tree is not drawn planar, i.e., there exist tree-edges that cross each other. This is more likely to occur if hierarchic layering strategy is selected.

Returns:

the EdgeBundling instance defining the edge bundling setup

getEdgeRoutingStrategy

public EdgeRoutingStrategy getEdgeRoutingStrategy()

Gets the edge routing strategy.

Throws:

IllegalArgumentException - if an invalid edge routing strategy is set

The edge routing cannot always prevent node-edge overlaps.

Default Value:

The default value is EdgeRoutingStrategy.ARC. The edges will be routed as arcs.

Returns:

the edge routing strategy

See Also:

setEdgeRoutingStrategy(EdgeRoutingStrategy)

getLayeringStrategy

public LayeringStrategy getLayeringStrategy()

Gets the layering strategy that determines how nodes are distributed into different layers.

All nodes of a given layer will be placed on the same circle.

Throws:

IllegalArgumentException - if an invalid layering strategy is set

Default Value:

The default value is LayeringStrategy.BFS. The layers are determined using BFS.

Returns:

one of the predefined layering strategies

See Also:

setLayeringStrategy(LayeringStrategy)

getLayerSpacing

public double getLayerSpacing()

Gets the spacing between two consecutive circles (layers).

The spacing is a non-negative value, where 0 means that no spacing is considered.

The radius of each circle will be a multiple of this value.

Throws:

IllegalArgumentException - if the spacing value is negative

Default Value:

The default value is 25.

Returns:

the spacing value

See Also:

setLayerSpacing(double)

getMaximumChildSectorAngle

public double getMaximumChildSectorAngle()

Gets the maximum sector angle around a node within which the node's children will be placed.

Based on the location of a given node, the sector of its children that lie on the next outer layer is described by this angle. The vertex of the angle is located in the center of the node while its sides point away from the inner circles. The child nodes are placed inside this angle. If there is not enough space, the radius of the child circle is increased.

Throws:

IllegalArgumentException - if the sector angle is negative or greater than 360 degrees

Default Value:

The default value is 180.

Returns:

the maximum sector angle in degrees from the interval [0,360]

See Also:

setMaximumChildSectorAngle(double)

getMinimumBendAngle

public double getMinimumBendAngle()

Gets the minimum bend angle (in degrees) between two adjacent edge segments.

The minimum bend angle is defined to be a value between 0 and 90 degrees.

Throws:

IllegalArgumentException - if the given minimum bend angle is negative or greater than 90

Increasing this value reduces the number of bends such that the edge path becomes less smooth.

Default Value:

The default value is 5.

Returns:

an angle from the interval [0,90]

See Also:

setMinimumBendAngle(double)

getMinimumLayerDistance

public double getMinimumLayerDistance()

Gets the minimum distance between two circles.

Throws:

IllegalArgumentException - if the minimum layer distance is negative

Default Value:

The default value is 100.

Returns:

the non-negative distance between two circles

See Also:

setMinimumLayerDistance(double)

getMinimumNodeToNodeDistance

public double getMinimumNodeToNodeDistance()

Gets the minimum distance between two neighboring nodes of the same circle.

Throws:

IllegalArgumentException - if the given minimum distance is negative

Default Value:

The default value is 10.

Returns:

a non-negative distance

See Also:

setMinimumNodeToNodeDistance(double)

isNodeLabelConsiderationEnabled

public boolean isNodeLabelConsiderationEnabled()

Gets whether or not node labels are taken into account when calculating node positions.

Thereby, possible node/node label or node label/node label overlaps are prevented.

This option only works correctly if the layout orientation is set to LayoutOrientation.TOP_TO_BOTTOM (which is the default). Changing the layout orientation for an undirected layout algorithm like the RadialLayout doesn't make sense.

Default Value:

The default value is false. Node labels are not considered.

Returns:

true if node labels are considered, false otherwise

See Also:

setNodeLabelConsiderationEnabled(boolean)

setCenterNodesDpKey

public void setCenterNodesDpKey(Object value)

Sets the IDataProvider key used for looking up the selected nodes that should be placed in the center.

Throws:

IllegalArgumentException - if the specified key is null

This option will only take effect if center node policy is set to CenterNodesPolicy.CUSTOM.

Default Value:

The default value is LayoutKeys.AFFECTED_NODES_DPKEY. The selected nodes are placed in the center.

Parameters:

value - the IDataProvider key for the selection of center nodes

See Also:

getCenterNodesDpKey()

setCenterNodesPolicy

public void setCenterNodesPolicy(CenterNodesPolicy value)

Sets the policy that determines which nodes are selected as roots of the (virtual) tree for the layout process and are set in the center of the circles.

Throws:

IllegalArgumentException - if an invalid center node policy is given

Default Value:

The default value is CenterNodesPolicy.WEIGHTED_CENTRALITY. The node determined using weighted centrality is placed in the center.

Parameters:

value - one of the predefined center node policies

See Also:

getCenterNodesPolicy()

setEdgeRoutingStrategy

public void setEdgeRoutingStrategy(EdgeRoutingStrategy value)

Sets the edge routing strategy.

Throws:

IllegalArgumentException - if an invalid edge routing strategy is set

The edge routing cannot always prevent node-edge overlaps.

Default Value:

The default value is EdgeRoutingStrategy.ARC. The edges will be routed as arcs.

Parameters:

value - the edge routing strategy

See Also:

getEdgeRoutingStrategy()

setLayeringStrategy

public void setLayeringStrategy(LayeringStrategy value)

Sets the layering strategy that determines how nodes are distributed into different layers.

All nodes of a given layer will be placed on the same circle.

Throws:

IllegalArgumentException - if an invalid layering strategy is set

Default Value:

The default value is LayeringStrategy.BFS. The layers are determined using BFS.

Parameters:

value - one of the predefined layering strategies

See Also:

getLayeringStrategy()

setLayerSpacing

public void setLayerSpacing(double value)

Sets the spacing between two consecutive circles (layers).

The spacing is a non-negative value, where 0 means that no spacing is considered.

The radius of each circle will be a multiple of this value.

Throws:

IllegalArgumentException - if the spacing value is negative

Default Value:

The default value is 25.

Parameters:

value - the spacing value

See Also:

getLayerSpacing()

setMaximumChildSectorAngle

public void setMaximumChildSectorAngle(double value)

Sets the maximum sector angle around a node within which the node's children will be placed.

Based on the location of a given node, the sector of its children that lie on the next outer layer is described by this angle. The vertex of the angle is located in the center of the node while its sides point away from the inner circles. The child nodes are placed inside this angle. If there is not enough space, the radius of the child circle is increased.

Throws:

IllegalArgumentException - if the sector angle is negative or greater than 360 degrees

Default Value:

The default value is 180.

Parameters:

value - the maximum sector angle in degrees from the interval [0,360]

See Also:

getMaximumChildSectorAngle()

setMinimumBendAngle

public void setMinimumBendAngle(double value)

Sets the minimum bend angle (in degrees) between two adjacent edge segments.

The minimum bend angle is defined to be a value between 0 and 90 degrees.

Throws:

IllegalArgumentException - if the given minimum bend angle is negative or greater than 90

Increasing this value reduces the number of bends such that the edge path becomes less smooth.

Default Value:

The default value is 5.

Parameters:

value - an angle from the interval [0,90]

See Also:

getMinimumBendAngle()

setMinimumLayerDistance

public void setMinimumLayerDistance(double value)

Sets the minimum distance between two circles.

Throws:

IllegalArgumentException - if the minimum layer distance is negative

Default Value:

The default value is 100.

Parameters:

value - the non-negative distance between two circles

See Also:

getMinimumLayerDistance()

setMinimumNodeToNodeDistance

public void setMinimumNodeToNodeDistance(double value)

Sets the minimum distance between two neighboring nodes of the same circle.

Throws:

IllegalArgumentException - if the given minimum distance is negative

Default Value:

The default value is 10.

Parameters:

value - a non-negative distance

See Also:

getMinimumNodeToNodeDistance()

setNodeLabelConsiderationEnabled

public void setNodeLabelConsiderationEnabled(boolean value)

Sets whether or not node labels are taken into account when calculating node positions.

Thereby, possible node/node label or node label/node label overlaps are prevented.

This option only works correctly if the layout orientation is set to LayoutOrientation.TOP_TO_BOTTOM (which is the default). Changing the layout orientation for an undirected layout algorithm like the RadialLayout doesn't make sense.

Default Value:

The default value is false. Node labels are not considered.

Parameters:

value - true if node labels are considered, false otherwise

See Also:

isNodeLabelConsiderationEnabled()

setOrientationLayoutEnabled

public void setOrientationLayoutEnabled(boolean value)

Sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.

Overrides:

setOrientationLayoutEnabled in class MultiStageLayout

If the current layout orientation is LayoutOrientation.TOP_TO_BOTTOM, the orientation of the layout will not be modified.

Based on the undirected layout style, disabling OrientationLayout has no significant effect.

Default Value:

The default value is true. The orientation ILayoutStage is activated.

Parameters:

value - true if the stage that modifies the orientation is activated, false otherwise

See Also:

MultiStageLayout.isOrientationLayoutEnabled(), MultiStageLayout.setOrientationLayout(com.yworks.yfiles.layout.ILayoutStage), MultiStageLayout.setLayoutOrientation(com.yworks.yfiles.layout.LayoutOrientation), OrientationLayout