Radial Layout
Class RadialLayout is a layout algorithm, that arranges the nodes of a graph on concentric circles. The layout calculation starts by conceptually reducing the graph to a tree structure whose root node is taken as the center of all circles. Each child node in this tree structure is then placed on the next outer circle within the sector of the circle that was reserved by its parent node. All edges that were initially ignored are re-established and the radii of the circles are calculated taking the sector sizes needed by each whole subtree into account.
This layout style is well suited for the visualization of directed graphs and tree-like structures.
Basic Options
The policy to choose the center node from the node set of the graph can be determined by using the centerNodesPolicy property. The following policies are available:
- DIRECTED
- Chooses the center node from the set of nodes that have no predecessors. If this set is empty, an arbitrary node of the graph becomes the center node.
- CENTRALITY
- The node that has the highest centrality becomes the center node.
- WEIGHTED_CENTRALITY
- The node that has the highest weighted centrality becomes the center node. This is the default setting.
- CUSTOM
- Uses a custom selection of nodes that has been specified by means of layout data. If there is more than one node marked as center node, these nodes get placed on the innermost circle and the actual center position remains empty.
The layeringStrategy property specifies how nodes will be distributed to the layers. The following strategies are available:
- BFS
- Layering based on a breadth-first search (BFS). All edges will span at most one layer in the resulting drawing. Edges between nodes that belong to the same layer are possible. This is the default setting.
- HIERARCHICAL
- The layer distance of an edge is the absolute difference between the layer numbers of its source and target node. Layer assignment will be done in such a way that the overall sum of the layer distances of all edges in the layout is minimal.
- DENDROGRAM
- Layering strategy that leads to a dendrogram drawing. The layer assignment places the nodes on the outermost circle possible without them passing their successors. In tree graphs, this means that the leaves are placed on the outermost circle and their parents further inside. For general graphs, the outermost circle is populated with nodes who have no successors in their sector.
The distance between the layers depends on the space that is needed by the subtrees. However, the layer spacing can be controlled and a minimal distance can be defined.
- Layer Spacing
- layerSpacing
- Defines a unit value for the distance between circles, i.e., each circle radius is a multiple of this value.
- Minimal Layer Distance
- minimumLayerDistance
- Defines the minimal layer distance.
Edge routing options include different routing policies that can be specified using the edgeRoutingStrategy property:
- POLYLINE
- Polyline edge routing. Edges will be routed straight-line, if possible, or have bends on the circles.
- ARC
- Arc edge routing. Source and target of an edge as well as one bend on each spanned circle are used as main control points. Additional control points are inserted in-between to create an arc-like edge. This is the default setting.
- RADIAL_POLYLINE
- Radial polyline routing. Edges will be routed as a series of straight and arc segments. At the angle of the source and the target node the edge will go straight from the center and when the angle changes the edge follows the circles.
- CURVED
- Curved edge routing. Edges will be routed as curved bezier paths.
Note that with both edge routing policies overlaps of edge paths with nodes cannot always be prevented. In particular, this affects edges that span multiple circles (i.e., layers).
Labeling
Besides the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms, RadialLayout additionally features integrated node labeling.
Node labels can be taken into consideration when determining the positions for the nodes of the graph. With this strategy it is guaranteed that no label will overlap other objects in the diagram. Integrated labeling can be enabled or disabled using the following property:
- integratedNodeLabeling
- Determines whether integrated labeling is enabled.
Enabling the integrated node labeling support of class RadialLayout means that each node label will be placed and arranged such that there are no overlaps of node labels with each other or with graph elements (other than their respective node).
RadialLayout supports different node labeling policies that can be configured using the nodeLabelingPolicy property. The following policies are available:
- HORIZONTAL
- Each node label will be placed at the center of its node, with horizontal orientation. Multiple node labels will be placed center aligned and stacked.
- RAY_LIKE
- Node labels of all nodes, except from the root node, will be oriented ray-like, i.e. with the same angle as the node. Additionally, the node labels of nodes without successors within their sector will be placed outside of their node and in the available space between their circle and the next circle. The node labels of all other nodes will be placed on the available space between their circle and the previous one. Multiple, ray-like oriented node labels will be left aligned. The node labels of the root node will be placed at the center of their node, with horizontal orientation. Also, node labels that do not use a "free" label model, will be placed this way. See also below. This is the default setting.
- RAY_LIKE_LEAVES
- The node labels of nodes without successors within their sector will be oriented ray-like, i.e. with the same angle as the node. Additionally, these node labels will be placed outside of their node and in the available space between their circle and the next circle. Other node labels will be placed at the center of their node, with horizontal orientation. Also, node labels that do not use a "free" label model, will be placed this way. See also below.
Note that ray-like oriented node labels are only supported by integrated labeling for node labels that use a "free" label model, e.g., FreeNodeLabelModel. Furthermore, instead of using the integrated node labeling, property considerNodeLabels allows to specify that the algorithm considers the current position of the labels without producing overlaps.
Node Halos
RadialLayout by default supports node halos as soon as they are declared. It considers any specified additional padding around nodes, however, edges can cross through these areas in the resulting diagram.
Edge Bundling
RadialLayout supports edge bundling for the non-tree edges in a diagram to bundle their paths so that they follow similar routes.
Using edge bundling significantly reduces the visual clutter in drawings of large graphs with many edges. In addition, high-level patterns of edge routes and relations between different groups of nodes can be highlighted and easily recognized. Edge bundling is commonly used in bio-informatics, social network analysis, telecommunications, and in fraud detection.
Edge bundling in RadialLayout is supported for the non-tree edges of a diagram.
The actual setup and edge bundling configuration is the responsibility of the EdgeBundling class. RadialLayout provides the following property to access the instance it holds of this class:
- edgeBundling: EdgeBundling
- Property to access the EdgeBundling instance to configure edge bundling-related drawing options.
This EdgeBundling instance holds an instance of class EdgeBundleDescriptor to store and retrieve default edge bundling values for non-tree edges. The following property can be used to retrieve this default EdgeBundleDescriptor instance:
- defaultBundleDescriptor: EdgeBundleDescriptor
- Property to access the default edge bundling descriptor held by EdgeBundling.
In addition to the instance held by EdgeBundling, edge bundling descriptors can also be associated with single non-tree edges in order to specify individual settings for them. Setting individual descriptors for non-tree edges is done through layout data.
Classes EdgeBundling and EdgeBundleDescriptor provide the means to configure drawing options related to the edge bundling support in RadialLayout. Class EdgeBundling defines global settings regarding the edge bundling, for example, the strength and the quality of the bundling. It also holds a default EdgeBundleDescriptor instance with fallback settings for the edges of a graph. Class EdgeBundleDescriptor can be used to configure the bundling settings of an individual edge. It can be specified whether or not:
- an edge shall be bundled
- the direction of an edge should be taken into consideration
- an edge should be approximated by a cubic Bezier curve
To configure the global edge bundling settings class EdgeBundling provides the following properties:
- Bundling Strength
- bundlingStrength: number
- Determines the tightness of the edge bundles. It takes values from interval [0.0, 1.0] where 0.0 corresponds to straight-line, non-bundled edges and 1.0 to strongly bundled edges. For good readability featuring clearly visible bundles, a bundling strength greater than 0.8 is recommended.
- Bundling Quality
- bundlingQuality: number
- Determines the quality of the edge bundling. Higher values require more sophisticated methods to calculate the bundles and, thus, the running time can significantly increase. The setting can take values from interval [0.0, 1.0]. For large graphs, values smaller than 0.2 are recommended.
The per-edge settings can be configured via the following properties in class EdgeBundleDescriptor:
- Bundle Edge
- bundled: boolean
- Determines whether or not an edge shall be bundled.
- Consider Edge Direction
- considerDirection: boolean
- Determines if the direction of an edge should be taken into consideration. If enabled, incoming and outgoing edges incident to a node are bundled separately.
- Use Bezier Fitting
- bezierFitting: boolean
- Determines whether or not the path of an edge should be approximated by a cubic Bezier curve. The number of bends may be significantly reduced by the approximation.
An EdgeBundleDescriptor instance can be specified individually for single edges by means of layout data. In the absence of an individual descriptor for an edge, the default EdgeBundleDescriptor instance that is registered with EdgeBundling will be used.
Layout Data
When using class RadialLayout, supplemental layout data for a graph’s elements can be specified either by using class RadialLayoutData or by registering data providers with the graph using given look-up keys. Supplemental layout data lists all properties of RadialLayoutData and the corresponding look-up keys that RadialLayout tests during the layout process in order to query supplemental data.
Providing supplemental layout data is described in detail in Layout Data.
Supplemental layout data
centerNodes - For each node a boolean value indicating whether it shall be placed in the center.Data Provider Key: AFFECTED_NODES_DP_KEYMaps from node to boolean
nodeInfos - For each node a value indicating on which circle and in which sector the node has been placed by the layout.Data Provider Key: NODE_INFO_DP_KEYMaps from node to NodeInfo
nodeHalos - A NodeHalo object that specifies the halo sizes at each side of a node.Data Provider Key: NODE_HALO_DP_KEYMaps from node to NodeHalo
layerIds - For each node a non-negative integer value representing the layer/circle ID of each node.Data Provider Key: LAYER_ID_DP_KEYMaps from node to Integer
edgeBundleDescriptors - For each edge an EdgeBundleDescriptor object that configures edge bundling options.Data Provider Key: EDGE_BUNDLE_DESCRIPTOR_DP_KEYMaps from edge to EdgeBundleDescriptor
abortHandler - An AbortHandler instance that will be queried by the layout algorithm to determine whether layout calculation shall be terminated.Data Provider Key: ABORT_HANDLER_DP_KEYMaps from graph to AbortHandler
- nodeTypes
- For each node an arbitrary Object indicating the node’s type, see Layout with Custom Node Types for more details.Data Provider Key: NODE_TYPE_DP_KEYMaps from node to Object