Circular Layout

Class CircularLayout is a layout algorithm that portraits interconnected ring and star topologies and is excellent for applications in:

Social networking (criminology, economics, etc.)
Network management
WWW visualization
eCommerce

CircularLayout produces layouts that emphasize group and tree structures within a network. It creates node partitions by analyzing the connectivity structure of the network, and arranges the partitions as separate circles. The circles themselves are arranged in a radial tree layout fashion. CircularLayout delegates these two major layout tasks to other, more specialized layout providers, namely classes SingleCycleLayout and BalloonLayout.

Sample layouts produced by class CircularLayout

Basic Options

Class CircularLayout provides a set of options that affect its layout behavior. These options can be set using the properties of class CircularLayout. The options are documented within the API documentation of class CircularLayout.

Additionally, there are properties that grant access to the layout delegates SingleCycleLayout and BalloonLayout. These layout algorithms are responsible for arranging the circle and the tree components of the diagram, respectively. Modifying the options of these layout algorithms does also affect the overall layout behavior of CircularLayout.

The options for CircularLayout affect the general layout strategy and the interplay between SingleCycleLayout and BalloonLayout.

The global layout style is set using the layoutStyle property. It controls which policy is used to partition the nodes of the graph. Each node partition will be arranged either on a separate circle or as a separate disk (see also node partition layout style below). Available options are

BCC_COMPACT: Each partition will represent a so-called biconnected component of the graph. A biconnected component consists of nodes that are reachable by two edge-disjoint paths. Nodes that belong to more than one biconnected component will be assigned exclusively to one partition.
BCC_ISOLATED: Node partitions will be formed as with BCC_COMPACT with the difference that all nodes belonging to more than one biconnected component will be assigned an isolated partition.
SINGLE_CYCLE: All nodes will be arranged on a single circle.
CUSTOM_GROUPS: The node partitions that form circles can be specified by means of layout data.

Effect of option Layout Style shows the effect of different layout styles applied to CircularLayout.

The BCC styles partition the nodes by examining the two-connectivity property of the input graph. SINGLE_CYCLE places all nodes one a single cycle.

Use Existing Drawing as Sketch
fromSketchMode: If enabled, the layout algorithm interprets the initial graph layout as a sketch for the desired outcome of the layout process. The algorithm tries to identify the nodes that should lie on a node partition’s circle/disk boundary and maintain their cyclic order around the center of the node partition. (See also Partition Arrangement Options below.) Additionally, when layout style BCC Compact is used, the layout algorithm also tries to maintain the cyclic order of entire node partitions that connect to a common node.

Partition Arrangement Options

Node Partition Layout Style

partitionStyle

Determines the layout style for the node partitions of a graph. The nodes from a partition can be arranged either as a circle or using one of the available disk flavors:

Arranging as a circle means that all nodes from a given partition are placed on a circle.
Arranging as a disk means that those nodes from a given partition which connect to nodes from other partitions are placed on the disk’s boundary while all other nodes are placed on the inside.
Arranging as an organic disk means that the organic layout paradigm is used to arrange the nodes from a partition. Nodes which connect to nodes from other partitions can be placed both on the inside or on the boundary of the disk.
Arranging as an compact disk means that the nodes of the given partition are densely packed on the disk. This style is mostly suitable for partitions with few edges. Further, it is recommended to enable external edge routing.

All three disk arrangement styles result in graph layouts that are smaller in size, i.e., consume less space than the circle arrangement style. Node partition layout styles presents the available node partition layout styles and their effects for a given graph.

The options for the internally used singleCycleLayout influence the size and compactness of the circles/disks formed by this layout algorithm.

Minimal Node Distance
minimumNodeDistance: Determines the minimal distance between the borders of two adjacent nodes on the circle/the disk’s boundary. The smaller the distance, the more compact the resulting layout.

Automatic Radius
automaticRadius: Whether or not to determine the radius of each circle/disk in the layout automatically. An automatically chosen radius is usually the smallest possible radius that obeys minimumNodeDistance.

Fixed Radius
fixedRadius: If automaticRadius is not set, then this option determines the fixed radius for all circles/disks in the resulting layout. minimumNodeDistance will be ignored in this case.

Edge Routing Policy

Edges are by default all routed as simple straight lines (interior routing). Edges that connect nodes that belong to the same circle (i.e. partition) can optionally be routed around the exterior of the circle. They are routed in an arc-like fashion. This can increase the readability of the layouts of a single cycle as the number of edge crossing inside the circle can be reduced. Therefore, this is a suitable option mainly when having partitions or single cycles where the nodes are highly connected with each other.

The property edgeRoutingPolicy controls the routing policy, i.e., determines which edges are interior and which are exterior.

INTERIOR: All edges are routed internally and as straight lines (default behavior).
EXTERIOR: Edges connecting nodes of the same partition are routed around the exterior of the circle. Only edges that connect direct neighbors are still routed as straight lines.
AUTOMATIC: The set of edges that become exterior is chosen automatically. The heuristic selection aims to reduce the number of edge crossings on the interior of the circle and avoids producing edge crossings between exterior edges.
MARKED_EXTERIOR: The set of exterior edges is user-defined by the layout data property exteriorEdges, see also Supplemental layout data. The other edges are routed internally.

Exterior Edges - Settings

The exterior edges routed around the circle can be further configured by means of class ExteriorEdgeLayoutDescriptor. It offers various properties, like, e.g., the distance between adjacent exterior edges. See the API documentation for details.

Tree Arrangement Options

The options for the internally used balloonLayout influence the compactness of the tree-like components that this layout algorithm produces. The tree-like structures are the parts of the layout that are not part of the circular arranged node groups.

Preferred Child Wedge
preferredChildWedge: This setting determines the angular range of the sector that will be reserved for the children of a root node. The possible angular range lies between 1 and 359. The remaining angular range (360 minus x) will be automatically used to accommodate the edge that connects to the root node. The smaller the chosen value, the greater the impression that the nodes drive away from their root nodes and the center of the graph. Generally speaking, the compactness of the layout will decrease with smaller values. Very small values will lead to layouts that consume a lot of space.
Minimal Edge Length
minimumEdgeLength: Determines the minimal length of an edge that connects two nodes that lie on separate circles (tree-edges). The smaller the chosen value, the more compact the resulting layout.
Compactness Factor
compactnessFactor: This parameter influences the length of the tree-edges as it is computed by the layout algorithm. The smaller the compactness factor, the shorter the tree-edges and the more compact the overall layout. The bigger the compactness factor the more difficult, and hence slower, the layout computation.
Allow Overlaps
allowOverlaps: If activated, this option further increases compactness of the resulting layout, but potentially introduces slight node overlaps.

The following tree arrangement options which also influence the compactness are set directly on the CircularLayout.

Maximal Deviation Angle
maximumDeviationAngle: Whenever tree edges connect to a node that lies on a circle together with other nodes, the layout algorithm tries to direct that edge in such a way that its prolongation crosses through the center of the circle. This is not always possible though, for example, if more than one tree-edge connect to the same circle node. This parameter determines the allowed angular deviation from the optimal edge direction as described above. The bigger the chosen value, the more compact the resulting layout. If a value smaller than 90 degrees is chosen, then the tree-edges might cross through the circular arranged components.
Place Children on Common Radius
placeChildrenOnCommonRadius: Enables tighter drawings by using adapted radii for child nodes. By default, the nodes in tree-like structures connecting to a circle are always placed on a common radius according to their distance from the root node. Tighter drawings can be achieved by abandoning the common radius and instead placing these child nodes using radii adapted to the size of an actual child node and the sizes of nodes in its vicinity.

Child node placement in tree structures shows a circular layout using the default setting and the result of using adapted radii for the nodes in tree-like structures connecting to a circle. Note that the circle(s) themselves are left unaltered.

Labeling

Edge labels can be placed automatically using the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms.

Additionally, CircularLayout can be set up to take node labels into account during layout. With such a setup 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 CircularLayout 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).

CircularLayout 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. See also below.
RAY_LIKE: The algorithm places the label of nodes that belong to the perimeter of a circle ray-like outside the node with the same orientation as their nodes' incoming edge. If the partition style is BCC_COMPACT or BCC_ISOLATED, the labels of the nodes that are connected to more than one circular components will be also placed horizontal, even if they are placed on the perimeter of the circle. Labels of nodes that belong to a chain will be placed ray-like but inside the node with the same orientation as their nodes' incoming edge. See also below.
RAY_LIKE_LEAVES: The algorithm places the label of nodes with no children or of nodes that belong to the perimeter of a circle and have neighbors at the same circle ray-like outside the node with the same orientation as their nodes' incoming edge. The labels of the other nodes will be oriented horizontally and placed at the center of the corresponding node. This is the default setting. 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.

Results with different node labeling policies

Node Halos

CircularLayout by default supports node halos as soon as they are declared. It considers any specified additional padding around nodes, however, due to the straight-line routing of the edges, they can cross through these areas in the resulting diagram. Also, node halo overlaps may occur if the internally used BalloonLayout allows overlapping nodes.

Edge Bundling

CircularLayout supports edge bundling, a feature to bundle the paths of edges in cluster-like structures in a diagram so that they follow similar routes.

In order to perform the edge bundling, a clustering algorithm is applied such that possible "community structures", i.e. densely connected sets of nodes, in the graph are revealed. The paths of edges incident to nodes that belong to the same cluster are bundled.

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 CircularLayout is supported

with the partitionStyle set to arrange as a circle
and the layoutStyle set to one of: BCC_COMPACT, SINGLE_CYCLE, or CUSTOM_GROUPS

The actual setup and edge bundling configuration is the responsibility of the EdgeBundling class. CircularLayout 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 all 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 edges in order to specify individual settings for them. Setting individual descriptors for edges is done through layout data.

Classes EdgeBundling and EdgeBundleDescriptor provide the means to configure drawing options related to the edge bundling support in CircularLayout. 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.

Optimizing Compactness

There are several options that have impact on the compactness of the circular layout. Optimizing for compactness, e.g., is achieved by

choosing DISK or ORGANIC as CircularLayout.partitionStyle
reducing BalloonLayout.compactnessFactor (say, to 0.1)
setting BalloonLayout.allowOverlaps to true (note that this may introduce node overlaps)
reducing BalloonLayout.minimumEdgeLength
reducing SingleCycleLayout.minimumNodeDistance
increasing CircularLayout.maximumDeviationAngle
disable CircularLayout.placeChildrenOnCommonRadius
removing any node halos

Increasing layout compactness shows the cumulative effect on layout compactness when changing the settings of the layout algorithm.

Returning Circle Indices

As an option, CircularLayout can write integer values for every node to the layout data which represent the circle indices after layout calculation.

Layout of Star Substructures

The circular layout algorithm can identify star substructures in a graph and arranges them in an optimized manner which makes them more compact and easily recognizable in the resulting layout.

To enable the support for identifying and arranging star substructures, the following properties are available.

starSubstructureStyle
starSubstructureSize
starSubstructureTypeSeparation: The properties to configure star substructures and their layout style.

As an option, the logic to identify the star substructures can take node types into account. The types can be specified via the layout data property nodeTypes.

Another option that influences the detection of star substructures is the edge directedness. This means that within a substructure all edges need to have the same direction. To enable this option, define supplemental layout data that specifies the directedness for edges by setting the edgeDirectedness property.

An edge can be marked using one of the following directedness values:

0 denotes a regular, i.e., undirected edge
1 denotes an edge that should be oriented from source to target
-1 denotes an edge that should be oriented from target to source

Carefully observe that the support for edge directedness is only provided by the logic that identifies the star substructures in a graph and is only taken into account in conjunction with substructure layout. The circular layout algorithm in general has no notion of edge direction. Consequently, by default, all edges are assumed to have a directedness value of 0.

Layout Data

When using class CircularLayout, supplemental layout data for a graph’s elements can be specified either by using class CircularLayoutData or by registering data providers with the graph using given look-up keys. Supplemental layout data lists all properties of CircularLayoutData and the corresponding look-up keys that CircularLayout 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

customGroups: For each node an arbitrary Object indicating the group it is affiliated with.
Data Provider Key: CUSTOM_GROUPS_DP_KEY
Maps from node to Object
circleIds: The layout algorithm writes an integer value for each node. This value represents the index of the actual circle a node is part of.
Data Provider Key: CIRCLE_ID_DP_KEY
Maps from node to Integer
nodeHalos: A NodeHalo object that specifies the halo sizes at each side of a node.
Data Provider Key: NODE_HALO_DP_KEY
Maps from node to NodeHalo
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_KEY
Maps from graph to AbortHandler
edgeBundleDescriptors: For each edge an EdgeBundleDescriptor object that configures edge bundling options.
Data Provider Key: EDGE_BUNDLE_DESCRIPTOR_DP_KEY
Maps from edge to EdgeBundleDescriptor
exteriorEdges: For marking an edge as exterior edge when using the edge routing policy MARKED_EXTERIOR.
Data Provider Key: EXTERIOR_EDGES_DP_KEY
Maps from edge to boolean
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_KEY
Maps from node to Object
edgeDirectedness: For each edge a floating point value that indicates the directedness of the edge. Note that the directedness is only taken into account in conjunction with star substructures.
Data Provider Key: EDGE_DIRECTEDNESS_DP_KEY
Maps from edge to double

Orthogonal Layouts Radial Layout