This layout algorithm arranges graphs in a circular fashion.
Remarks
Layout Style
The nodes are arranged in circles and stars which emphasize group and tree structures inside a graph. Circular layout algorithms find applications in many areas such as social networking, network management, WWW visualization, eCommerce, telecommunications.
Concept
The layout algorithm performs three steps when calculating a circular arrangement for a graph:
- It searches for partitions in the input graph depending on connectivity and on the given partitioningPolicy. Considering each partition as a node, the resulting graph has a tree-like structure.
- The partitions are laid out as circles using the selected style.
- The algorithm delegates the layout calculation for the underlying tree (in which each node corresponds to a partition) to a specialized layout algorithm accessible by backboneLayout. The partitions are moved to their final location.
Features
The layout algorithm places the nodes in circles that represent a partition. There are several ways to find partitions in the input graph. Which one is applied is defined using partitioningPolicy.
The nodes in a partition can either lie on or in the interior of a circle. The placement of the nodes affects the compactness of the layout and can be specified using partitionDescriptor.
Since edges are routed as straight lines, they may overlap with nodes or node labels. To resolve these overlaps, an edge routing algorithm (e.g. EdgeRouter or OrganicEdgeRouter) can be appended.
Edges that belong to the same circle partition can be routed around the exterior of the circle. The edgeRoutingPolicy determines which edges are exterior and routing details of these edges can be configured via exteriorEdgeDescriptor. Exterior edge routes consist of smooth arcs. Edges that are routed externally can significantly improve the readability of the circular layout by reducing the edge clutter in the interior of the circle. This holds true especially for graph with a large number of edges. On the other hand, it significantly increases the amount of required space and, thus, is not recommended when maximally compact layouts are desired.
This layout algorithm supports edgeBundling. In order to bundle the edges, the nodes of the graph are clustered in groups. Edge bundling is supported only if the partition style is set to CYCLE and partitioningPolicy is other than BCC_ISOLATED.
This layout algorithm handles port placement constraints by applying the PortPlacementStage as a postprocessing step.
Layout Stages
This class provides a configurable pipeline that contains various ILayoutStages. Each ILayoutStage can incorporate preprocessing or postprocessing steps into the layout calculation to streamline the input graph and enhance the resulting layout. Additionally, custom ILayoutStages can be added and executed either before or after the predefined ones.
The following default ILayoutStages are included:
- PortPlacementStage: Assigns edges to ports.
- GroupHidingStage: Removes group nodes and their adjacent edges before layout processing, and reinserts them afterward. The property hidingEmptyGroupNodes is set to
false, and resetEdgePaths is set totrue. - SubgraphLayoutStage: Filters a graph to include only specific nodes and edges from a subgraph while maintaining the positions of excluded elements. Note: This stage is disabled by default.
- ComponentLayout: Arranges graph components with customizable styles. The property style is set to circular component arrangement style.
- GenericLabeling: Efficiently places node and edge labels. The property fillEmptyScope is set to
falseand stopDuration is set to ZERO. - selfLoopRouter: Routes self-loops in a graph, allowing for either orthogonal or rounded routing styles. The property routingStyle is set to ROUNDED.
- parallelEdgeRouter: Routes multiple edges between the same nodes in parallel.
With these layoutStages the layout algorithm is configured well, so they usually don't need to be changed.
Performance
The CircularLayout algorithm is a fast algorithm that is generally well-suited to handle even large graphs.
With disconnected graphs that contain large unconnected components, it can be beneficial to change the component arrangement style of the used componentLayout from the default style PACKED_CIRCLE to the faster ROWS style.
With graphs containing a large number of edges, applying edgeBundling can cause the algorithm to take noticeably longer to arrive at a result.
Default Values of Properties
| edgeLabelPlacement | GENERIC | Edge labels are placed by an independent labeling algorithm. |
| edgeRoutingPolicy | INTERIOR | Edges are routed as simple straight lines on the interior. |
| fromSketchMode | false | The layout algorithm does not consider the initial coordinates of the nodes. |
| maximumDeviationAngle | 90 | |
| nodeLabelPlacement | CONSIDER | Node labels are considered. |
| partitioningPolicy | BCC_COMPACT | |
| placeChildrenOnCommonRadius | true | Children are placed on a common radius. |
Type Details
- yFiles module
- algorithms
See Also
Constructors
Creates a new CircularLayout instance with the default settings.
Parameters
A map of options to pass to the method.
- nodeLabelPlacement - RadialNodeLabelPlacement
- How the layout handles the position of node labels. This option sets the nodeLabelPlacement property on the created object.
- edgeLabelPlacement - RadialEdgeLabelPlacement
- How the layout handles the position of edge labels. This option sets the edgeLabelPlacement property on the created object.
- nodeLabelSpacing - number
- The distance between node labels belonging to the same node. This option sets the nodeLabelSpacing property on the created object.
- placeChildrenOnCommonRadius - boolean
- Whether or not, in the underlying tree, the children of a tree node are placed on a common radius. This option sets the placeChildrenOnCommonRadius property on the created object.
- fromSketchMode - boolean
- Whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves. This option sets the fromSketchMode property on the created object.
- starSubstructureStyle - CircularLayoutStarSubstructureStyle
- The layout style for star substructures. This option sets the starSubstructureStyle property on the created object.
- starSubstructureSize - number
- The minimum size (number of nodes including the root) a star needs to have to be detected and handled as a star substructure. This option sets the starSubstructureSize property on the created object.
- starSubstructureTypeSeparation - boolean
- Whether star substructures should be separated by the node type. This option sets the starSubstructureTypeSeparation property on the created object.
- maximumDeviationAngle - number
- The maximum deviation angle in degrees allowed for an edge. This option sets the maximumDeviationAngle property on the created object.
- partitioningPolicy - CircularLayoutPartitioningPolicy
- The global partitioning policy for this layout algorithm. This option sets the partitioningPolicy property on the created object.
- partitionDescriptor - PartitionDescriptor
- The descriptor that defines settings for the layouts of the circle partitions. This option either sets the value directly or recursively sets properties to the instance of the partitionDescriptor property on the created object.
- exteriorEdgeDescriptor - CircularLayoutExteriorEdgeDescriptor
- The descriptor that defines settings for the exterior edges. This option either sets the value directly or recursively sets properties to the instance of the exteriorEdgeDescriptor property on the created object.
- edgeDescriptor - CircularLayoutEdgeDescriptor
- The descriptor that defines settings for the non-exterior edges, that is, edges that are routed within or between circle partitions. This option either sets the value directly or recursively sets properties to the instance of the edgeDescriptor property on the created object.
- edgeRoutingPolicy - CircularLayoutEdgeRoutingPolicy
- The edge routing policy that determines whether edges are routed internally or externally with respect to a single partition circle. This option sets the edgeRoutingPolicy property on the created object.
Properties
Gets the RadialTreeLayout instance used for arranging multiple partitions.
Remarks
Property Value
See Also
Gets the ComponentLayout from the layoutStages of this instance.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- If there is no instance of the respective type in the
See Also
Gets the EdgeBundling instance that defines the settings of the edge bundling feature.
Remarks
Property Value
See Also
Gets or sets the descriptor that defines settings for the non-exterior edges, that is, edges that are routed within or between circle partitions.
Remarks
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given descriptor is
null
See Also
Gets or sets how the layout handles the position of edge labels.
Default Value
Property Value
See Also
Gets or sets the edge routing policy that determines whether edges are routed internally or externally with respect to a single partition circle.
Remarks
There are two types of supported edges, exterior and non-exterior edges.
- Non-exterior edges are routed as simple straight lines that directly connect the source and target node. This is the default style for the circular layout.
- Exterior edges get an arc-like curved path around the exterior of the circle. Only edges between nodes of the same partition (i.e. on the same circle) can be exterior edges. These edges may be beneficial in cases with a large number of edge crossings inside the circle: by moving some edges out, the number of crossings is reduced and the layout may become more readable. The drawback is the larger space that is required.
If the predefined routing policies for controlling the routing of edges inside and outside of circles are not suitable for your specific use case, you can use the exteriorEdges property to define your own policy.
Default Value
Property Value
See Also
Gets or sets the descriptor that defines settings for the exterior edges.
Remarks
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given descriptor is
null
See Also
Gets or sets whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves.
Remarks
If enabled:
- For complex partitions (those consisting of more than one node), the layout algorithm tries to keep peripheral nodes and maintain their circular order around the center of the disk/circle. Other partitions that connect to this node are moved accordingly, if possible.
- For multiple partitions that connect to the same node, the layout algorithm tries to keep their circular order around this node. This only works as expected for BCC_COMPACT as partitioning policy, since otherwise the underlying tree structure is not well-defined.
This setting has no effect if there is a user-defined nodeComparator set or edge bundling is enabled. nodeTypes are not considered for the node order if fromSketchMode enabled.
Default Value
false.The layout algorithm does not consider the initial coordinates of the nodes.
Property Value
true if the initial coordinates of the nodes are used, false otherwiseSee Also
Sample Graphs
Gets the mutable stack of ILayoutStage that will be applied to this layout.
Gets or sets the maximum deviation angle in degrees allowed for an edge.
Remarks
Default Value
90.Property Value
See Also
Sample Graphs
Gets or sets how the layout handles the position of node labels.
Default Value
Property Value
- IGNORE if node label positions relative to their owner should be maintained and ignored during the layout process.
- CONSIDER if node label positions relative to their owner should be maintained and considered for the placement of other graph elements to avoid overlaps.
- HORIZONTAL if horizontal node label positions should be calculated by this layout algorithm, assuring that no overlaps occur.
- RAY_LIKE if ray-like node label positions should be calculated by this layout algorithm, assuring that no overlaps occur.
- RAY_LIKE_LEAVES if a mix of horizontal and ray-like node label positions should be calculated by this layout algorithm, assuring that no overlaps occur.
- GENERIC if the node labels should be placed by an independent labeling algorithm. The used generic labeling algorithm can be accessed for further configuration on the layoutStages, using get.
See Also
Sample Graphs
Gets or sets the distance between node labels belonging to the same node.
Remarks
It also defines the distance between labels and the node they belong to in case of label placement outside of the node (e.g. for ray-like label placement).
The spacing must have a non-negative value.
Default Value
2.0.Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given spacing value is negative
See Also
Sample Graphs
0, node labels will be maximally close to each other and to their node.Gets the ParallelEdgeRouter from the layoutStages of this instance.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- If there is no instance of the respective type in the
See Also
Gets or sets the descriptor that defines settings for the layouts of the circle partitions.
Property Value
See Also
Gets or sets the global partitioning policy for this layout algorithm.
Remarks
This property allows to define how nodes within the input graph are partitioned by the CircularLayout. Each policy dictates a different method of partitioning nodes.
The arrangement of individual partitions can be controlled with the partitionDescriptor property.
If the predefined policies do not suit specific needs, custom partitions can be defined using the partitions property. In this case, the value of partitioningPolicy will be ignored.
Default Value
Property Value
See Also
Gets or sets whether or not, in the underlying tree, the children of a tree node are placed on a common radius.
Remarks
Default Value
true.Children are placed on a common radius.
Property Value
true if a common radius is used, false otherwiseSee Also
Sample Graphs
Gets the SelfLoopRouter from the layoutStages of this instance.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- If there is no instance of the respective type in the
See Also
Gets or sets the minimum size (number of nodes including the root) a star needs to have to be detected and handled as a star substructure.
Default Value
4.Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given minimum size is less than
3
See Also
Gets or sets the layout style for star substructures.
Remarks
A star consists of a set of nodes with degree one that are all connected to the same node (called the root of the star). Use property starSubstructureSize to define the minimum number of nodes, including the root, a star must contain to be detected as a substructure.
If there are user-defined nodeTypes, by default, a star substructure only contains nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.
Default Value
Property Value
See Also
Gets or sets whether star substructures should be separated by the node type.
Remarks
Default Value
true.Star substructures are strictly separated by node type.
Property Value
true if star substructures are separated by node type, false if they may contain nodes of different typesSee Also
Sample Graphs
Methods
Calculates a circular layout for the given graph.
Remarks
The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.
This method is not side effect-free in the sense that the order of edges or nodes in the input graph may change during the layout process.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Arranges the given graph in a circular fashion.
createLayoutData
(graph: LayoutGraph) : CircularLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the CircularLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪CircularLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>
- an instance of layout data that can be used to perform item-specific configurations for the given CircularLayout.
Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the CircularLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪CircularLayoutData<INode,IEdge,ILabel,ILabel>
- an instance of layout data that can be used to perform item-specific configurations for the given CircularLayout.
LayoutExecutor type is available at runtime.Constants
A data key for publishing the final circle information.
Remarks
See Also
A data key for marking edges that should be routed externally, around the circle instead of inside.
Remarks
If the predefined routing policies for controlling the routing of edges inside and outside of circles are not suitable for your specific use case, you can use this data key to define your own policy.
The IMapper<K,V> registered with the input with this key allows to individually select the edges that are routed around the exterior of the circle.
Mark an edge with true if the edge should become an exterior edge routed outside the circle, or false if the edge should be an interior edge.
See Also
A data key for defining custom node partitions.
Remarks
If the predefined partitioning policies do not suit specific needs, custom partitions can be defined using this data key. In this case, the value of partitioningPolicy will be ignored.
The IMapper<K,V> needs to provide a mapping from LayoutNodes to unique Object IDs for each group of nodes. These groups will form the circles in the layout.