A tree layout algorithm that arranges the subtrees of the tree in a balloon-like fashion.
Remarks
Layout Style
BalloonLayout is designed to arrange directed and undirected tree graphs. Subtrees rooted at a node are placed in a radial fashion around their root node. All direct children of one node can be placed on a common circle around their parent node (depending on the alignment policy). Therefore, subtrees look like balloons or stars, especially if subtrees have similar sizes. The edges of the tree are drawn as straight lines.
Concept
The algorithm executes the following steps:
- Select a root node according to the specified root policy.
- Determine the placement of subtrees around the root using a bottom-up recursive approach (starting with leaf nodes).
- For a leaf node: calculate the convex hull of the node.
- For a non-leaf node: arrange the children rooted at the node. Children are sorted according to a specified ordering policy and a distance to their parent is chosen. This distance will be chosen such that subtrees rooted at the current node fit into the preferred wedge angle. The wedge angle defines how much radial space a subtree occupies around its parent; it is computed using the convex hull of subtrees.
Finally, the convex hull of the subtree rooted at the current node is updated in order to include all the convex hulls of child nodes. This is possible, because distances and wedges of the child subtrees are now known.
- Assign the actual coordinates of nodes, again using a recursive approach (starting with the root node).
Features
The algorithm features integrated edge labeling as well as node labeling. Edge labels and node labels are placed automatically without generating overlaps with other labels or graph elements. There are different ways to place node labels. Edge labeling will take the settings of PreferredPlacementDescriptor into account.
Defining a preferred wedge angle has a great influence on the layout style. Subtrees rooted at a node get a certain amount of radial space to be placed around the parent node, such that a preferred angle close to 360 degrees will generate drawings where subtrees look like balloons, while an angle close to 180 degrees could be chosen to get drawings where subtrees look like semicircles.
Since it is computationally not very complex, BalloonLayout is very well suited for large tree graphs. It performs well even for huge graphs.
Node types are considered such that the type of the nodes is used as a criterion for sorting the child nodes of a local root node, with the effect that nodes of the same type are placed consecutively, if possible. If defined, the comparer is stronger than the node type criterion However, the node types are considered more important than the childOrderingPolicy.
This layout algorithm can only handle graphs with a tree structure. To apply it to a general graph, a TreeReductionStage can be appended. This stage will temporarily remove some edges of the input graph until a tree is obtained. These edges will later be reinserted and routed separately.
Default Values of Properties
| allowOverlaps | false | Nodes are not allowed to overlap. |
| chainStraighteningMode | false | There is no guarantee that chains are drawn straight. |
| compactnessFactor | 0.5 | A factor offering good balance between compactness and runtime. |
| componentLayoutEnabled | true | The stage that arranges connected graph components is activated. |
| hideGroupsStageEnabled | true | The stage responsible for hiding group nodes is activated. |
| integratedEdgeLabeling | false | Edge labels are not placed by this algorithm. |
| integratedNodeLabeling | false | Node labels are not placed by this algorithm. |
| interleavedMode | OFF | Interleaved placement is disabled. |
| minimumEdgeLength | 40 | |
| minimumNodeDistance | 10 | |
| nodeLabelingPolicy | RAY_LIKE | |
| orientationLayoutEnabled | true | The orientation |
| parallelEdgeRouterEnabled | true | The stage that routes parallel edges is activated. |
| preferredChildWedge | 340 | |
| preferredRootWedge | 360 | |
| selfLoopRouterEnabled | true | The stage that routes self-loops is activated. |
Type Details
- yfiles module
- layout-core
- yfiles-umd modules
- All layout modules, view-layout-bridge
- Legacy UMD name
- yfiles.tree.BalloonLayout
See Also
Constructors
Creates a new BalloonLayout instance with default settings.
Parameters
A map of options to pass to the method.
- comparer - IComparer<Object>
The IComparer<T> instance that determines the order of the outgoing edges for each node of the tree. This option sets the comparer property on the created object.
- childOrderingPolicy - ChildOrderingPolicy
The child ordering policy for sorting the child nodes around their parents. This option sets the childOrderingPolicy property on the created object.
- minimumNodeDistance - number
The minimum distance to be kept between the nodes in the tree. This option sets the minimumNodeDistance property on the created object.
- fromSketchMode - boolean
Whether or not to consider the given coordinates of the input diagram when arranging the tree. This option sets the fromSketchMode property on the created object.
- rootNodePolicy - RootNodePolicy
The root node selection policy of this layout algorithm. This option sets the rootNodePolicy property on the created object.
- preferredChildWedge - number
The preferred radial amount (wedge) in degrees that child nodes may in total occupy around their parent node. This option sets the preferredChildWedge property on the created object.
- preferredRootWedge - number
The preferred radial amount (wedge) in degrees that child nodes may in total occupy around the global root. This option sets the preferredRootWedge property on the created object.
- allowOverlaps - boolean
Whether or not (partially) overlapping nodes are allowed. This option sets the allowOverlaps property on the created object.
- compactnessFactor - number
The factor defining how compact layout results will potentially be, where a smaller factor produces potentially more compact layouts. This option sets the compactnessFactor property on the created object.
- minimumEdgeLength - number
The minimum length that this layout algorithm assigns to edges of the graph. This option sets the minimumEdgeLength property on the created object.
- considerNodeLabels - boolean
Whether or not the layout algorithm reserves space for node labels. This option sets the considerNodeLabels property on the created object.
- interleavedMode - InterleavedMode
The mode for child node arrangement. This option sets the interleavedMode property on the created object.
- childAlignmentPolicy - ChildAlignmentPolicy
The child alignment policy for this layout algorithm. This option sets the childAlignmentPolicy property on the created object.
- integratedNodeLabeling - boolean
Whether or not the layout algorithm automatically places node labels. This option sets the integratedNodeLabeling property on the created object.
- integratedEdgeLabeling - boolean
Whether or not the layout algorithm automatically places edge labels. This option sets the integratedEdgeLabeling property on the created object.
- nodeLabelingPolicy - NodeLabelingPolicy
The policy defining how node labels are placed by the integrated node labeling mechanism (for example, the desired label orientation). This option sets the nodeLabelingPolicy 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.
- edgeLabelSpacing - number
The distance between edge labels belonging to the same edge as well as the distance of the edge labels to the target node of the edge. This option sets the edgeLabelSpacing property on the created object.
- chainStraighteningMode - boolean
Whether or not chains are drawn straight or not. This option sets the chainStraighteningMode property on the created object.
- componentLayoutEnabled - boolean
Whether or not the ILayoutStage used for arranging the components of the graph is activated. This option sets the componentLayoutEnabled property on the created object.
- hideGroupsStageEnabled - boolean
Whether or not the ILayoutStage used for hiding group nodes is activated. This option sets the hideGroupsStageEnabled property on the created object.
- orientationLayoutEnabled - boolean
Whether or not the ILayoutStage that modifies the orientation of the layout is activated. This option sets the orientationLayoutEnabled property on the created object.
- parallelEdgeRouterEnabled - boolean
Whether or not the ILayoutStage used for routing parallel edges is activated. This option sets the parallelEdgeRouterEnabled property on the created object.
- selfLoopRouterEnabled - boolean
Whether or not the ILayoutStage used for routing self-loops is activated. This option sets the selfLoopRouterEnabled property on the created object.
- labeling - ILayoutStage
The ILayoutStage that places the labels of the input graph. This option sets the labeling property on the created object.
- selfLoopRouter - ILayoutStage
The ILayoutStage that routes self-loops. This option sets the selfLoopRouter property on the created object.
- parallelEdgeRouter - ILayoutStage
The ILayoutStage that routes parallel edges. This option sets the parallelEdgeRouter property on the created object.
- componentLayout - ILayoutStage
The ILayoutStage that arranges the connected components of an input graph. This option sets the componentLayout property on the created object.
- subgraphLayout - ILayoutStage
The ILayoutStage that constrains the layout process to a subgraph of the input graph. This option sets the subgraphLayout property on the created object.
- hideGroupsStage - ILayoutStage
The ILayoutStage that hides the group nodes of the input graph. This option sets the hideGroupsStage property on the created object.
- orientationLayout - ILayoutStage
The ILayoutStage that modifies the orientation of a computed layout. This option sets the orientationLayout property on the created object.
- layoutOrientation - LayoutOrientation
The main orientation of the layout. This option sets the layoutOrientation property on the created object.
- labelingEnabled - boolean
Whether or not the ILayoutStage used for placing the labels of the input graph is activated. This option sets the labelingEnabled property on the created object.
- subgraphLayoutEnabled - boolean
Whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated. This option sets the subgraphLayoutEnabled property on the created object.
Properties
Gets or sets whether or not (partially) overlapping nodes are allowed.
Remarks
Default Value
false.Nodes are not allowed to overlap.
See Also
Sample Graphs
Gets or sets whether or not chains are drawn straight or not.
Remarks
A chain is defined as a tree node with exactly one child node. If this feature is enabled, then the incoming edge and outgoing edge of the chain will have the same orientation, i.e., the whole chain looks straight.
Straightening all chains can lead to smoother, more symmetric results.
Default Value
false.There is no guarantee that chains are drawn straight.
See Also
Sample Graphs
Gets or sets the child alignment policy for this layout algorithm.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown policy is given
See Also
Gets or sets the child ordering policy for sorting the child nodes around their parents.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown ordering policy is given
See Also
Gets or sets the factor defining how compact layout results will potentially be, where a smaller factor produces potentially more compact layouts.
Remarks
The algorithm tries to optimize the child node arrangement around each tree node such that each subtree is as close to its root as possible, while still fitting into the preferred wedge angle and not overlapping with adjacent subtrees.
High compactness factor values induce the optimization procedure to be less strict and accept less optimal results, while low factor values mean that the optimization will only stop when being nearly optimal. Thus, lower values lead to a potentially higher runtime.
The minimum factor value is 0.05 and the maximum is 1.0.
Default Value
0.5.A factor offering good balance between compactness and runtime.
Throws
- Exception({ name: 'ArgumentError' })
- if the factor is smaller than
0.05or greater than1.0
See Also
Gets or sets the IComparer<T> instance that determines the order of the outgoing edges for each node of the tree.
Remarks
null), the outgoing edges will be sorted according to the current child ordering policy.Default Value
null.The algorithm uses a built-in sorting logic.
See Also
Gets or sets the ILayoutStage that arranges the connected components of an input graph.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.
Default Value
true.The stage that arranges connected graph components is activated.
See Also
Overrides
Gets or sets whether or not the layout algorithm reserves space for node labels.
Remarks
Default Value
false.Node labels are not considered.
See Also
Sample Graphs
Gets or sets the distance between edge labels belonging to the same edge as well as the distance of the edge labels to the target node of the edge.
Remarks
Default Value
4.0.Labels are close together and close to targets.
Throws
- Exception({ name: 'ArgumentError' })
- if the given label spacing value is negative
See Also
Sample Graphs
0, labels will touch each other and the target node.Gets or sets whether or not to consider the given coordinates of the input diagram when arranging the tree.
Remarks
Default Value
false.The coordinates of the input are not considered.
See Also
Sample Graphs
Gets or sets the ILayoutStage that hides the group nodes of the input graph.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for hiding group nodes is activated.
Default Value
true.The stage responsible for hiding group nodes is activated.
See Also
Overrides
Gets or sets whether or not the layout algorithm automatically places edge labels.
Remarks
Default Value
false.Edge labels are not placed by this algorithm.
See Also
Sample Graphs
Gets or sets whether or not the layout algorithm automatically places node labels.
Remarks
If enabled, this layout algorithm will calculate the positions for the node labels assuring that no overlaps occur.
Different labeling strategies may be selected using nodeLabelingPolicy.
Default Value
false.Node labels are not placed by this algorithm.
See Also
Sample Graphs
Gets or sets the mode for child node arrangement.
Remarks
Child nodes are either placed interleaved or on a single layer around their parent node. Interleaved placement means that child nodes are placed around their common parent in two different layers in an alternating fashion. For example, the first child is on the inner layer, the second child on the outer layer, the third one again on the inner layer, etc.
Independent of this mode, the alignment of child nodes on the same layer is still defined by the alignment policy. However, SMART is only supported for non-interleaved arrangement.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown mode for interleaved arrangement is given
See Also
Gets or sets the ILayoutStage that places the labels of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for placing the labels of the input graph is activated.
Remarks
Default Value
false.The stage responsible for label placement is deactivated.
See Also
Defined in
Gets or sets the main orientation of the layout.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified orientation does not match a default layout orientation
See Also
Defined in
Gets or sets the minimum length that this layout algorithm assigns to edges of the graph.
Remarks
A lower minimum edge length allows generally more compact layouts. It has the highest effect if most nodes of the graph have a low degree, as the minimum can potentially be met for such graphs.
The minimum length must be non-negative.
Default Value
40.Throws
- Exception({ name: 'ArgumentError' })
- if the given length is negative
See Also
Sample Graphs
Gets or sets the minimum distance to be kept between the nodes in the tree.
Gets or sets the policy defining how node labels are placed by the integrated node labeling mechanism (for example, the desired label orientation).
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown labeling policy is given
See Also
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
4.0.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 or sets the ILayoutStage that modifies the orientation of a computed layout.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.
Default Value
true.The orientation
See Also
Overrides
Gets or sets the ILayoutStage that routes parallel edges.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for routing parallel edges is activated.
Default Value
true.The stage that routes parallel edges is activated.
See Also
Overrides
Gets or sets the preferred radial amount (wedge) in degrees that child nodes may in total occupy around their parent node.
Remarks
The wedge angle controls the degree to which the child nodes may radiate from the center of layout. A value close to 360 means that the child nodes may radiate in (almost) any direction from their parent node, edge lengths can in consequence stay rather small. On the other hand, a small value means that children are restricted to a small angle; thus, edge lengths (and drawings) may become large.
The minimum allowed wedge angle is 1 and the maximum allowed value is 359.
Default Value
340.Throws
- Exception({ name: 'ArgumentError' })
- if the given angle is smaller than
1or larger than359
See Also
Sample Graphs
360 is needed.Gets or sets the preferred radial amount (wedge) in degrees that child nodes may in total occupy around the global root.
Remarks
This property allows to separately control the wedge angle for the designated root node of the tree, while preferredChildWedge controls the angles of all child nodes. The root node will be determined depending on the root node policy.
The minimum allowed root wedge angle is 1 and the maximum allowed value is 360.
Default Value
360.Throws
- Exception({ name: 'ArgumentError' })
- if the given angle is smaller than
1or larger than360
See Also
Sample Graphs
Gets or sets the root node selection policy of this layout algorithm.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown root node policy is given
See Also
Gets or sets the ILayoutStage that routes self-loops.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for routing self-loops is activated.
Default Value
true.The stage that routes self-loops is activated.
See Also
Overrides
Gets or sets the ILayoutStage that constrains the layout process to a subgraph of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated.
Remarks
Default Value
false.The stage that constrains the input graph to a subgraph is deactivated.
See Also
Defined in
Methods
Appends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Calculates a layout for the given graph and applies it directly to the graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Arranges the given graph as a tree graph in a balloon-like fashion.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Throws
- Exception({ name: 'InvalidGraphStructureError' })
- if the given graph is not a tree
Implements
Calculates the wedge angle that has to be reserved for the subtree rooted at the given node scaling the distance with the given scale factor.
Remarks
Given some distance the upper angle and lower angle of the wedge belonging to the subtree rooted at root will be calculated and stored in the BalloonLayoutNodeInfo instance associated with root.
This method may be overridden to perform a custom wedge angle assignment scheme. The method is called when arranging child nodes. Large edge labels on the incoming edge to root need to be considered, if integrated edge labeling should still work properly.
Parameters
A map of options to pass to the method.
- root - YNode
- the node for which the wedge angles are calculated
- scaleFactor - number
- a factor to be applied to the distance of
root
Returns
- ↪number
- the sum of the upper and lower wedge angle of the subtree rooted at the given root node
See Also
root.Calculates a child node arrangement for a given root node of the tree.
Remarks
During the arrangement, child nodes of root will be sorted. Furthermore, distances of the child nodes will be chosen such that the wedge of the subtree of root fits into the preferred wedge angle, which is either defined via preferredRootWedge or preferredChildWedge. Calculated distances are stored in dist.
The angle values - upper and lower wedge angle - may also be updated during this process and stored in upperAngle and lowerAngle, respectively. To compute the angles of wedges, method calculateAngles is used.
This method may be overridden to perform a custom child node arrangement. If support for available features like interleaving should be maintained, then these features need to be carefully considered during the arrangement.
Parameters
A map of options to pass to the method.
- root - YNode
- the node for whose children to compute an arrangement
Checks the sizes of the nodes to be non-zero.
Parameters
A map of options to pass to the method.
- g - LayoutGraph
- The graph to check.
Defined in
Determines the root node of graph according to the chosen root node policy.
Remarks
Returns
See Also
Deactivates all predefined ILayoutStages so that upon applyLayout only the layout algorithm will be executed.
See Also
Defined in
Returns the BalloonLayoutNodeInfo object associated with the given node while the layout algorithm is active.
Remarks
The returned object contains detailed information describing the placement of a node in the layout being computed, e.g., a node's distance to its parent or the wedge angle of the subtree rooted at a node.
Subclasses may want to override this method to realize another node information setup. This method is called throughout the algorithm, each time some information associated with a node needs to be retrieved or stored.
Parameters
A map of options to pass to the method.
- node - YNode
- the node whose information object should be retrieved
Returns
- ↪BalloonLayoutNodeInfo
- the BalloonLayoutNodeInfo instance associated to the given node
See Also
Returns the preferred radial amount (wedge) in degrees that child nodes may in total occupy around the given node.
Remarks
The wedge angle controls the degree to which the child nodes may radiate from the center of layout. A value close to 360 means that the child nodes may radiate in (almost) any direction from their parent node, edge lengths can in consequence stay rather small. On the other hand, a small value means that children are restricted to a small angle; thus, edges lengths (and drawings) may become large.
This method returns the preferred root wedge if node root was selected as global root node (rootNodePolicy). Otherwise, it either returns preferredChildWedge or if the given node has an outdegree equal to 2, it returns the minimum of preferredChildWedge and 180.
This method may be overridden to provide a custom child wedge function.
Parameters
A map of options to pass to the method.
- root - YNode
- the node to get the preferred wedge angle for
Returns
- ↪number
- the preferred wedge angle for
rootin degrees
See Also
Prepends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Removes the given ILayoutStage from the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- a ILayoutStage to be removed from the layout pipeline
See Also
Defined in
Sorts the child nodes (successors) of the given node.
Remarks
This implementation uses the original node coordinates if From Sketch mode is enabled. Otherwise it uses the specified comparator to sort the outgoing edges and thus the children of root. If there is no such comparator, then the sorting depends on whether or not the child nodes are placed in an interleaved fashion:
- Normal: Children are sorted according to the chosen child ordering policy.
- Interleaved: Children are sorted such that the resulting interleaved node placement is compact, while children inducing larger subgraphs are placed next to smaller ones.
This method may be overridden to realize a custom child node ordering. It gets called in method calculateChildArrangement before coordinates are assigned and just after the wedge sizes for all subtrees rooted at root are determined.
Parameters
A map of options to pass to the method.
- root - YNode
- the node whose child nodes will be sorted
Fields
The layout graph being acted upon.
Constants
A data provider key for marking nodes whose child nodes should be placed in an interleaved fashion.
Remarks
| Domain | YNode | |
| Values | boolean | true if the node's children should be placed in an interleaved fashion, false or null otherwise |
See Also
A data provider key for marking the node that will be used as root node of the tree.
| Domain | YNode | |
| Values | boolean | true if the node should be considered as the root node of the tree, false otherwise |