documentationfor yFiles for HTML 2.6

Tree Layouts

The yFiles tree layout algorithm family specializes in the layout of tree-structured graphs. The need to visualize directed or undirected trees arises in many application areas, e.g.,

  • Dataflow analysis
  • Software engineering
  • Network management
  • Bioinformatics

The tree layouts are provided in a number of different styles:

Sample layouts produced with the tree layouts algorithms
Using TreeLayout.
Using ClassicTreeLayout.
Using BalloonLayout.

General

Sorting Child Nodes

The tree layout algorithms support sorting the child nodes in a subtree using a NodeOrderComparer in conjunction with a data provider that is registered with the graph using the look-up key NODE_ORDER_COMPARABLE_DP_KEY. The following property registers custom IComparer<T> implementations with a tree layout algorithm. Except TreeLayout, this property is available in all tree layout algorithms.

comparer
Comparer registration.

Class NodeOrderComparer, when given the outgoing edges of a (sub)tree’s root node, uses the target nodes of the edges for querying the data provider. The IComparable objects, which the comparer expects in return, are then used to determine the order of the child nodes.

Enhancing the Layout Process of a Tree Layout

Layout Stages lists the layout stages that can be used with all tree layout algorithms to enhance the layout process.

Layout Stages
Class Name Description
TreeReductionStageAdds support for tree-like graphs.

Class TreeReductionStage is a layout stage that transforms graphs into proper trees. It automatically removes all non-tree edges prior to an algorithm’s run and re-inserts them thereafter. When the edges are re-inserted, different routing styles can be applied.

Edge Bundling

One of the routing styles that is supported by TreeReductionStage is edge bundling. With this routing style, the paths of the non-tree edges in a diagram are bundled so that they follow similar routes.

Tree layout with edge bundling of non-tree edges
Edge bundling of non-tree edges in a directed tree layout…​
... and in a balloon tree layout.

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 TreeReductionStage is supported for the non-tree edges of a diagram.

The actual setup and edge bundling configuration is the responsibility of the EdgeBundling class. TreeReductionStage 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 a data provider that is bound to the graph.

Classes EdgeBundling and EdgeBundleDescriptor provide the means to configure drawing options related to the edge bundling support in TreeReductionStage. 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 a data provider that is bound to the graph. The data provider is expected to be registered with the graph using key EDGE_BUNDLE_DESCRIPTOR_DP_KEY. In the absence of an individual descriptor for an edge, the default EdgeBundleDescriptor instance that is registered with EdgeBundling will be used.

Tutorial Demo Code

Tutorial demo application Collapsible Trees presents the setup of many tree layout algorithms in an application context.

Classic Tree Layout

Class ClassicTreeLayout is a layout algorithm mainly used for directed trees that have a unique root element. Starting with the root node the nodes are arranged either from top to bottom, left to right, right to left, or bottom to top. The edges of a graph can either be routed as straight lines or in an orthogonal bus-like fashion.

Basic Options

These options configure class ClassicTreeLayout in detail.

Minimal Layer Distance
minimumLayerDistance
Determines the minimal distance between parent and child nodes.
Minimal Node Distance
minimumNodeDistance
Determines the minimal distance between the siblings of a node.

Layout Orientation
layoutOrientation
Determines the main layout orientation, i.e., the overall orientation for the edges in a layout. This property is inherited from MultiStageLayout, the direct superclass of ClassicTreeLayout. The layout algorithm tries to arrange nodes in such a way that all edges point in the main layout direction. By default, the overall orientation for the edges will be from top to bottom. The other three layout directions can be set using the constants from the LayoutOrientation enum type. Setting the layout orientation shows how to set the layout direction.

The documentation for the other layout options assumes that this default orientation is being used.

Setting the layout orientation
const tl = new ClassicTreeLayout()
// Use left-to-right main layout direction.
tl.layoutOrientation = LayoutOrientation.LEFT_TO_RIGHT

portStyle
Determines the port assignment policy to be used. Ports can be placed
  • at the center of the corresponding nodes,
  • in the middle of the border, or
  • distributed along the border of the corresponding nodes.
Policies can be set using the constants from the PortStyle enum type.
Edge Routing Style
edgeRoutingStyle
If set, all edges will be routed orthogonally in a bus-like fashion. If not set, the edges will be routed as straight-line segments.

Bus Alignment
busAlignment
Determines vertical bus alignment within the space between two layers for edges from a given (root) node to its children that are routed in an orthogonal bus-like fashion.

Vertical Alignment
verticalAlignment
Specifies vertical alignment of nodes that are in the same layer. The value for the vertical alignment is interpreted relative to a layer’s height, which is determined by the maximum of the node heights. A value of 0.0 means top alignment, 1.0 means bottom alignment. The default value is 0.5, which means center alignment of all nodes in the same layer.

Child Placement Policy
leafPlacement
Determines the placement of child nodes in a given tree. Depending on the actual child placement policy, an optimal area utilization can be achieved. The following policies are supported:
  • SIBLINGS_ON_SAME_LAYER Configures the algorithm to place leaf nodes that have the same parent node in the same layer. This option is useful in order to make a graph vertically more compact.
  • ALL_LEAVES_ON_SAME_LAYER This setting results in a Dendrogram-like style and places all leaf nodes of the tree in the bottommost layer of the layout.
  • LEAVES_STACKED_LEFT Configures the algorithm for a stacked style of leaf nodes consisting of a single "stack."
  • LEAVES_STACKED_RIGHT Configures the algorithm for a stacked style of leaf nodes consisting of a single "stack."
  • LEAVES_STACKED_LEFT_AND_RIGHT Configures the algorithm for a stacked style of leaf nodes consisting of two "stacks."
  • LEAVES_STACKED Configures the algorithm for a stacked style of leaf nodes that aims to balance "stack" heights. For each subtree, the algorithm decides about the actual policy depending on the number of leaf nodes: either child placement policy LEAVES_STACKED_RIGHT or LEAVES_STACKED_LEFT_AND_RIGHT is used.
In the above context, "stacked" means that leaf nodes at the same parent node are placed non-overlapping below their parent node in a row that extends downwards. This allows to make a graph horizontally more compact. "Left" and "right" indicate where, relative to the center of the parent node, the row is placed. Note that the "stacked" policies only have an effect on subtrees where all children are leaf nodes.

Global Layering
enforceGlobalLayering
If set, the algorithm ensures that large nodes never span more than their layer. Otherwise, a more compact layout can be achieved when large nodes span two or more layers. This setting is useful, if the hierarchical structure of the tree should be more emphasized. Note that when disabled, the value set for the Vertical Alignment of nodes within their layer is ignored.

To obtain compact results, please also look at the recommendations at the end of section Improving the Compactness of Layout Results.

Labeling

Besides the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms, ClassicTreeLayout additionally features integrated labeling.

Integrated labeling is available for node labels and edge labels. They are taken into consideration when determining the positions for the nodes of the tree. 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 properties:

integratedEdgeLabeling
considerNodeLabels
Determines whether integrated labeling is enabled.

See also Integrated Labeling.

Optimal label placement with integrated labeling can be achieved using FreeEdgeLabelModel as the label model for the edges. As explained in Label Models, this edge label model is ideally suited in combination with integrated labeling and yields the best match for a label location that is computed by ClassicTreeLayout.

Incremental Layout

Class ClassicTreeLayout supports incremental layout by means of a IComparer<T> implementation that provides dynamic rearrangement of all child nodes in a given subtree according to their relative coordinates. Based on this scheme, the default comparer is able to incrementally insert new child nodes at optimal positions with respect to already arranged child nodes.

The following property registers custom Comparer implementations that act globally on the entire tree:

comparer
Comparer registration.

Alternatively, class NodeOrderComparer can be used to sort the child nodes of a subtree, too. See also Sorting Child Nodes.

Node Halos

ClassicTreeLayout by default supports node halos as soon as they are declared using the data provider key NODE_HALO_DP_KEY. During layout calculation, it takes any specified additional padding around nodes into consideration and keeps the areas clear of other graph elements. The labels of a node and its adjacent edge segments are not affected and can still be placed inside or cross the node’s halo.

Layout Data

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

NODE_ORDER_COMPARABLE_DP_KEY
For each subtree’s root the order of its child nodes.
Data Provider Key: NODE_ORDER_COMPARABLE_DP_KEY
Maps from node to Comparable
NODE_HALO_DP_KEY
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
TreeReductionStageData.edgeBundleDescriptors
For each edge an EdgeBundleDescriptor object that configures edge bundling options.
Maps from edge to EdgeBundleDescriptor

Tree Layout

Class TreeLayout defines a generic basis for tree layout that supports a multitude of different styles and arrangements. Major aspects of layout calculation can be customized for an invocation both globally for the entire tree, but also individually per subtree. This powerful scheme allows entirely different layout styles to be applied to the subtrees of a given tree.

Basic Options

TreeLayout delegates major aspects of layout calculation to implementations for interfaces INodePlacer and IPortAssignment:

  • INodePlacer is responsible for recursively arranging a subtree’s root node together with its children (starting at the leaf nodes of a tree),
  • IPortAssignment encapsulates edge port assignment for a node’s edges.

Classes DefaultNodePlacer and DefaultPortAssignment are used as the default implementations for INodePlacer and IPortAssignment, respectively.

Both INodePlacer as well as IPortAssignment implementations can be registered with TreeLayout to handle all nodes, i.e., act globally on the entire tree, or to handle only a specific root node, i.e., act locally on a subtree. The node placer or port assignment can be specified for each subtree individually by means of layout data.

Note that in the absence of an individual node placer or port assignment implementation the respective default implementation will be used for a given node. The following properties can be used to register default node placer and port assignment implementations:

defaultNodePlacer
Determines the globally used node placer implementation.
defaultPortAssignment
Determines the globally used port assignment implementation.

Predefined Node Placers

In addition to class DefaultNodePlacer, there are further predefined node placer implementations that provide a variety of subtree arrangement schemes. Their common superclass, abstract class RotatableNodePlacerBase, enables these node placers to transparently deal with child nodes that are actually rotated subtrees. Node placer hierarchy depicts the node placer class hierarchy.

Node placer hierarchy

Node placer implementations lists the predefined node placer implementations that extend abstract class AbstractNodePlacer.

Node placer implementations
Class Name Description
AspectRatioNodePlacerAll subtrees are placed such that a given aspect ratio for the entire tree is obeyed.
CompactNodePlacerUses a dynamic optimization approach that chooses a placement strategy of the children such that the overall result is compact with respect to a specified aspect ratio.
DefaultNodePlacerChild nodes are placed horizontally aligned below their root node. The bus-like routing for all edges to the child nodes extends horizontally.

Node placer implementations that support rotation lists predefined node placer implementations that support rotated subtrees. Note that the given descriptions assume a "canonic subtree orientation," where child nodes are placed (more or less) below their root node.

Node placer implementations that support rotation
Class Name Description
AssistantNodePlacerApplies a composite placement scheme where two kinds of nodes are differentiated; see below for a more detailed description.
BusNodePlacerChild nodes are placed evenly distributed to the left and right of their root node and also in a second line below the root node. The nodes within each line are horizontally aligned. The bus-like routing for all edges to the child nodes extends horizontally.
DelegatingNodePlacerApplies a composite placement scheme where two node placers are used to each arrange one half of the child nodes.
DoubleLineNodePlacerChild nodes are placed staggered in two lines below their root node, each line containing one half of the nodes. The nodes within each line are horizontally aligned. The bus-like routing for all edges to the child nodes extends horizontally.
FreeNodePlacerChild nodes can be placed anywhere, their coordinates are not modified. The bus-like routing for all edges to the child nodes extends horizontally.
LayeredNodePlacerSubtrees can be placed such that child nodes from the same layer (i.e., nodes having the same BFS distance to the tree’s root node) are aligned.
LeftRightNodePlacerChild nodes are placed below their root node to the left and right of the downward extending bus-like routing for all edges to the child nodes.
SimpleNodePlacerChild nodes are placed horizontally aligned below their root node. The bus-like routing for all edges to the child nodes extends horizontally.
GridNodePlacerChild nodes are placed in multiple rows below their root node. The bus-like routing for all edges to the child nodes can be configured using the enumeration BusPlacement. Child nodes are either assigned manually to the rows using property gridNodePlacerRowIndices or automatically if automaticRowAssignment is enabled.

RotatableNodePlacerBase provides support for eight different subtree orientation schemes which are expressed using suitable modification matrices of type RotatableNodePlacerMatrix. Supported subtree orientations shows all orientations beginning with the so-called "canonic subtree orientation." Note that the rotations provided by nested class RotatableNodePlacerBase.Matrix are using mathematical rotation sense, i.e., they are counter-clockwise.

Supported subtree orientations
Default orientation (a.k.a. canonic subtree orientation): DEFAULT
90 degree: ROT90
90 degree, mirrored vertically: MIR_VERT_ROT90
Mirrored vertically: MIR_VERT
Mirrored horizontally: MIR_HOR
90 degree, mirrored horizontally: MIR_HOR_ROT90
270 degree: ROT270
180 degree: ROT180

A concrete subclass of RotatableNodePlacerBase is given the modification matrix that describes the desired subtree orientation at initialization time. Predefined Node Placers lists the properties/constructors that provide matrix-related configuration support.

RotatableNodePlacerBase
Constructor of RotatableNodePlacerBase. (To be overridden in concrete subclasses.)
modificationMatrix
Gets the current modification matrix.

Subtree arrangement with NodePlacer implementations shows arrangements of an example (sub)tree (in canonic subtree orientation) using different node placer implementations. Note the (sub)tree’s emphasized root node.

Subtree arrangement with NodePlacer implementations
SimpleNodePlacer
LeftRightPlacer
FreePlacer
DoubleLinePlacer
BusPlacer

Class AssistantPlacer uses layout data to determine whether a node is a so-called "assistant" or not. Assistants are placed using LeftRightPlacer, non-assistants are placed using another node placer which can be configured using a property. Subtree arrangement provided by AssistentPlacer depicts the supported arrangements for the so-called non-assistant nodes.

Subtree arrangement provided by AssistentPlacer
Using SimpleNodePlacer for non-assistants.
Using DoubleLinePlacer for non-assistants.

Labeling

Besides the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms, generic tree layout additionally features integrated labeling.

Integrated labeling is available for node labels and edge labels. They are taken into consideration when determining the shape of a subtree. With this strategy it is guaranteed that no label will overlap other objects in the diagram. The following properties can be used to enable integrated labeling:

integratedEdgeLabeling
considerNodeLabels
Enables/disables integrated edge labeling and node labeling, respectively.

See also Integrated Labeling.

Optimal label placement with integrated labeling can be achieved using FreeEdgeLabelModel as the label model for the edges. As explained in Label Models, this edge label model is ideally suited in combination with integrated labeling and yields the best match for a label location that is computed by TreeLayout.

Grouped Graphs

By default, TreeLayout supports layout of tree structures where entire subtrees are contained in group nodes. Both position and dimension of group nodes will be calculated by the algorithm. The setGroupingSupported property can be used to control this functionality.

Incremental Layout

TreeLayout can be used in combination with a IComparer<T> implementation that allows to dynamically determine the sequence of child nodes in a subtree. Supplied with a root node’s outgoing tree edges, the comparer decides on their precedence. Based on this scheme, the comparer that is conveniently returned by class DefaultNodePlacer provides support for incrementally inserting new child nodes at optimal positions with respect to already arranged child nodes.

Comparers can be registered both to handle all nodes, i.e., act globally on the entire tree, or to handle only a specific root node, i.e., act locally on a subtree. The following property can be used to configure the default comparer for an entire tree:

defaultOutEdgeComparer
Sets the default IComparer<T> implementation for a tree.

Comparers individually for each subtree can be specified by means of layout data.

Class DefaultNodePlacer provides a suitable default comparer that can conveniently be used to support incremental tree layout scenarios with subtrees. The comparer enables dynamic rearrangement of all child nodes in a given subtree according to their relative coordinates. Setup for incremental layout with TreeLayout demonstrates the setup of TreeLayout using the default node placer and port assignment implementations, and additionally registering the default comparer from class DefaultNodePlacer.

Setup for incremental layout with TreeLayout
// Create a TreeLayout object that uses default node placer and
// port assignment implementations, i.e., classes DefaultNodePlacer and
// DefaultPortAssignment, respectively.
const tl = new TreeLayout()
// Register the comparer returned by class DefaultNodePlacer to take care of
// the sequences of child nodes in each subtree.
tl.defaultOutEdgeComparer = tl.defaultNodePlacer.createComparer()
// Create a TreeLayout object that uses default node placer and
// port assignment implementations, i.e., classes DefaultNodePlacer and
// DefaultPortAssignment, respectively.
const tl = new TreeLayout()
// Register the comparer returned by class DefaultNodePlacer to take care of
// the sequences of child nodes in each subtree.
tl.defaultOutEdgeComparer = (tl.defaultNodePlacer as DefaultNodePlacer).createComparer()

Port Constraints

Obeying port constraints for edges is part of the responsibilities of a node placer implementation. A node placer determines:

  • the source ports of all edges that connect a subtree’s root node to its child nodes
  • the target port of the edge that connects to the subtree’s root node

The predefined node placer implementations that implement INodePlacer obey both types of port constraints, weak and strong. The port constraints can be specified for the source as well as for the target node for each edge by means of layout data.

By means of interface IPortAssignment the ports of all edges adjacent to a given tree node can be assigned. To this end, method assignPorts is called immediately before a subtree’s node placer is invoked. Obviously, assigning edge ports at a tree node is confined to the target port of the incoming edge from the parent node, and the source ports of all outgoing edges to child nodes.

Node Halos

TreeLayout by default supports node halos as soon as they are declared via layout data. During layout calculation, it takes any specified additional padding around nodes into consideration and keeps the areas clear of other graph elements. The labels of a node and its adjacent edge segments are not affected and can still be placed inside or cross the node’s halo.

Multi-parent Structures

TreeLayout provides special support for so-called multi-parent structures, where multiple nodes share both the same direct predecessor node(s) as well as the same direct successor node(s). Multi-parent structures that are contained in group nodes are also supported. It is important, however, that all nodes belonging to the same multi-parent structure are contained in the same group node.

Technically, such a structure does not fit the very definition of a tree graph. Nevertheless, it can be handled within the context of tree graphs very well. However, to properly detect and handle these structures, the special support needs to be explicitly enabled using the following property:

multiParentAllowed
Enables TreeLayout’s special support for multi-parent structures.

The following figure shows a graph containing multi-parent structures (note the emphasis on the nodes). All nodes belonging to such a structure are placed side by side. By default, the edges incident to these nodes are routed using bus-style edge routing.

Note that the two nodes at the root of the graph also constitute a multi-parent structure: they share an "imaginary" direct predecessor.

Graph with multi-parent structures
#

To configure layout and drawing options of a multi-parent structure, class MultiParentDescriptor can be used. For example, the following options can be set:

  • relative alignment of nodes within their layer
  • preferred minimum distances
  • different routing styles for edges

A MultiParentDescriptor instance can be specified for the nodes of a multi-parent structure by means of layout data. It is important that all nodes belonging to the same multi-parent structure yield the same descriptor instance.

These options are available:

Minimum Node Distance
minimumNodeDistance
Determines the minimum distance between the nodes of a multi-parent structure.
Minimum Bus Distance
minimumBusDistance
Determines the minimum distance between the nodes of a multi-parent structure and their incident edges that are routed bus-style.

Vertical Alignment
verticalAlignment
Determines the vertical alignment of the nodes of a multi-parent structure within their layer. Values can be set from 0.0 (top) to 1.0 (bottom). See also Vertical alignment of the nodes of a multi-parent structure.

Vertical alignment of the nodes of a multi-parent structure
Aligned at the top with Vertical Alignment = 0.0
... in the middle with Vertical Alignment = 0.5
... at the bottom with Vertical Alignment = 1.0

The routing style of the edges incident to nodes of the multi-parent structure can be configured through the following property:

edgeStyle
Configures the routing style for edges incident to the nodes of a multi-parent structure.

The following figure shows the different edge routing styles side by side:

Edge routing styles determined by the MultiParentDescriptor
Orthogonal edge routing (with rounded bends).
Polyline edge routing.
Straight-line edge routing.

It is important to note that the routes of edges incident to the nodes of multi-parent structures are only half-way determined by the routing style configured in the MultiParentDescriptor. The other half is under the control of the actual NodePlacer implementation that is used by TreeLayout.

With regard to edge routing, NodePlacer implementation DefaultNodePlacer yields the best results in conjunction with multi-parent structures. Multi-parent support also harmonizes well with BusNodePlacer, LeftRightNodePlacer, and DendrogramNodePlacer. However, the following options of DefaultNodePlacer are not supported in conjunction with multi-parent structures:

  • routing style option ForkAtRoot
  • root alignment options LeadingOnBus and TrailingOnBus

Also with regard to edge routing, if port assignment implementations are registered for the nodes of a multi-parent structure, certain aspects of port constraint configuration of the incident edges will be ignored in order to prevent situations where this would lead to confusing (or even conflicting) edge routes in the resulting layout. In particular, this applies to the direction specified by a port constraint of an incident edge: the edge is instead always routed in flow direction. Note that all nodes of a multi-parent structure should yield the same port assignment, if any.

Improving the Compactness of Layout Results

Besides the chosen NodePlacers, the compactness may also heavily depend on the selected distances/spacing values. The following figure shows the possible impact of such properties.

Compact and less compact drawing of the same graph structure
Applying the DefaultNodePlacer with default settings.
Applying the DefaultNodePlacer with a slightly decreased minimum first segment length.

Note that in the less compact figure, placing the nodes of the second layer closer together would violate the specified vertical distance, more precisely the vertical distance between the left/rightmost node and the horizontal bus-like edge segments of the subtree of the middle node. Recall that this distance is used between nodes and between nodes and other subtree elements like edges and labels.

Suitable choice of spacing values gives some hints on how to choose the distances/spacing values such that the results are more compact.

The suggested hints only apply to the orthogonal routing style.

Suitable choice of spacing values
NodePlacer Value
DefaultNodePlacerThe value of property minimumFirstSegmentLength should be at least verticalDistance.
CompactNodePlacerThe value of property minimumFirstSegmentLength should be at least verticalDistance.
LayeredNodePlacerThe value of the product of layerSpacing multiplied by busAlignment should be at least spacing.

In addition, to obtain compact results with the ClassicTreeLayout consider the following: If property enforceGlobalLayering is enabled, the product of minimumLayerDistance multiplied by busAlignment should be at least minimumNodeDistance. Otherwise, the value of property minimumFirstSegmentLength should be at least minimumLayerDistance.

Layout Data

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

GROUP_DP_KEY
For each node a boolean value indicating whether it is a group node or not.
Data Provider Key: GROUP_DP_KEY
Maps from node to boolean
NODE_ID_DP_KEY
For each node an Object that serves as a unique ID.
Data Provider Key: NODE_ID_DP_KEY
Maps from node to Object
PARENT_NODE_ID_DP_KEY
For each node an Object indicating the group node it belongs to. The Object matches the unique ID of a group node that is in the same graph.
Data Provider Key: PARENT_NODE_ID_DP_KEY
Maps from node to Object
GROUP_NODE_INSETS_DP_KEY
For each group node an Insets object that encodes the group node’s insets.
Data Provider Key: GROUP_NODE_INSETS_DP_KEY
Maps from Node to Insets
MINIMUM_NODE_SIZE_DP_KEY
For each group node a YDimension object that specifies the group node’s minimum size constraint.
Data Provider Key: MINIMUM_NODE_SIZE_DP_KEY
Maps from node to YDimension
outEdgeComparers
For each node a IComparer<T> that is used to sort the outgoing edges.
Data Provider Key: OUT_EDGE_COMPARER_DP_KEY
Maps from node to Comparer
EDGE_LABEL_LAYOUT_DP_KEY
For each edge an array of LabelLayoutData objects that encode size and preferred placement for all labels of the edge.
Data Provider Key: EDGE_LABEL_LAYOUT_DP_KEY
Maps from edge to LabelLayoutData[]
NODE_LABEL_LAYOUT_DP_KEY
For each node an array of LabelLayoutData objects that encode size and preferred placement for all labels of the node.
Data Provider Key: NODE_LABEL_LAYOUT_DP_KEY
Maps from node to LabelLayoutData[]
nodePlacers
For each node a INodePlacer implementation that places the node itself and its subtree.
Data Provider Key: NODE_PLACER_DP_KEY
Maps from node to INodePlacer
portAssignments
For each node a IPortAssignment implementation that assigns ports to the edges of a node.
Data Provider Key: PORT_ASSIGNMENT_DP_KEY
Maps from node to IPortAssignment
CRITICAL_EDGE_DP_KEY
For each edge of a critical path a positive, non-zero integral value that indicates the priority of the edge/the critical path.
Data Provider Key: CRITICAL_EDGE_DP_KEY
Maps from edge to int
sourcePortConstraints
For each edge a PortConstraint object encoding its source end’s port constraint.
Maps from edge to PortConstraint
targetPortConstraints
For each edge a PortConstraint object encoding its target end’s port constraint.
Maps from edge to PortConstraint
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
MULTI_PARENT_DESCRIPTOR_DP_KEY
For each node of a multi-parent structure a MultiParentDescriptor object that configures a number of options.
Maps from node to MultiParentDescriptor
TreeReductionStageData.edgeBundleDescriptors
For each edge an EdgeBundleDescriptor object that configures edge bundling options.
Maps from edge to EdgeBundleDescriptor
treeRoot
A boolean value for marking the node that will be used as root node of the tree.
Data Provider Key: SELECTED_ROOT_DP_KEY
Maps from node to boolean
assistantNodes
A boolean value for marking the nodes that will be placed as assistants.
Data Provider Key: ASSISTANT_NODE_DP_KEY
Maps from node to boolean
delegatingNodePlacerPrimaryNodes
Nodes marked with true are placed left of the root and the remaining nodes are placed right of the root.
Data Provider Key: PRIMARY_NODES_DP_KEY
Maps from node to boolean
leftRightNodePlacerLeftNodes
Nodes marked with true are placed left of the bus and the remaining nodes are placed right of the bus.
Data Provider Key: LEFT_RIGHT_DP_KEY
Maps from node to boolean
gridNodePlacerRowIndices
The index of the row the node should be placed in.
Data Provider Key: ROW_INDEX_DP_KEY
Maps from node to integer
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
NODE_ORDER_COMPARABLE_DP_KEY
For each subtree’s root the order of its child nodes.
Data Provider Key: NODE_ORDER_COMPARABLE_DP_KEY
Maps from node to Comparable
criticalEdgePriorities
The priority of critical edges. The layout tries to align each node pair that is connected by a critical edge (integer value > 0).
Data Provider Key: CRITICAL_EDGE_DP_KEY
Maps from edge to integer
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

Tutorial Demo Code

Tutorial demo application Collapsible Trees uses the default setup of TreeLayout with the default node placer and port assignment implementations.

Balloon Tree Layout

Class BalloonLayout is a tree layout algorithm that positions the subtrees rooted at a node in a radial fashion around that node. It is ideally suited for huge trees (say, 10,000 nodes) since it computes fast layouts that are quite compact.

Sample layout of a tree that contains 10,000 nodes
balloon layout 2a

Basic Options

These options configure class BalloonLayout in detail.

rootNodePolicy
Determines which node should be used as root of the tree. Available options are:
  • DIRECTED_ROOT Chooses a node with indegree zero, if present. A good choice for directed rooted trees.
  • CENTER_ROOT Chooses the root such that the depth of the resulting tree gets minimized.
  • WEIGHTED_CENTER_ROOT Chooses the root such that the number of paths between any two nodes that traverse the root is maximal. This seems to be a natural root for undirected trees.
preferredRootWedge
This setting determines the angular range of the sector that will be reserved around the root node of the graph to accommodate the attached subtrees.
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 more 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.
minimumEdgeLength
Determines the minimal length of an edge. The smaller the chosen value the more compact the resulting layout.
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.
interleavedMode
Child nodes at the same parent tree node can be placed in an interleaving fashion. Especially if some tree node has many child nodes and if they have similar sizes, the diagram can become more compact. Available options are:
  • OFF Disables interleaved child node placement for all tree nodes. This is the default setting.
  • ALL_NODES At each tree node child nodes will be placed interleaved.
  • MARKED_NODES Enables interleaved child node placement for a custom selection of tree nodes that is given by the user. These nodes can be specified by means of layout data, otherwise a simple heuristic is used to decide for which tree node the child nodes should be placed interleaved.

Effects of interleaved child node placement
Tree layout by BalloonLayout …​
…​ with interleaved child node placement enabled.

If there is enough space to place the child nodes of a tree node without interleaving, they will be placed normally, even when "Interleaved Child Node Placement" is enabled.

childAlignmentPolicy
Determines the policy for aligning the child nodes at a tree node. Available options are:
  • PLAIN Child nodes at the same parent tree node are aligned such that each child node has the same border-to-border distance to the parent node. When interleaved child node placement is active, two different distances will be realized.
  • SAME_CENTER Child nodes at the same parent tree node are aligned such that each child node has the same center-to-center distance to the parent node. Therefore all nodes will be placed on one common radius around their root. When interleaved child node placement is active, two different radii will be realized.
  • COMPACT Child nodes at the same parent tree node are aligned such that the resulting drawing will be as compact as possible, not considering any symmetric constraints. This is the default setting.
  • SMART Child nodes at the same parent tree node are aligned using a heuristic for a well-balanced and symmetric layout. When interleaved child node placement is active, plain alignment will be used instead of the heuristic.

Child node alignment policies
Child node aligment plain…​
...same center…​
...compact.

chainStraighteningMode
If activated, all nodes in a chain will be placed on a straight line. This may lead to smoother and more symmetric layouts. By default, this feature is turned off.
allowOverlaps
If activated, this option further increases compactness of the resulting layout, but potentially introduces slight node overlaps.
considerNodeLabels
Enables node label-aware layout calculation.

Labeling

Besides the generic labeling support as described in Generic Labeling, which is available with all yFiles layout algorithms, BalloonLayout additionally features integrated labeling.

Integrated labeling is available for node labels and edge labels. They are taken into consideration when determining the positions for the nodes of the tree. 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 properties:

integratedEdgeLabeling
integratedNodeLabeling
Determines whether integrated labeling is enabled.

See also Integrated Labeling.

Enabling the integrated node labeling support of class BalloonLayout means that each node label will be placed and arranged by BalloonLayout such that there are no overlaps of node labels with each other or with graph elements (other than their respective node).

BalloonLayout 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 leaf nodes and node labels of nodes having exactly one successor (thus possibly forming a chain) will be oriented ray-like, i.e. with the same orientation as their node’s incoming edge. Additionally, the node labels of leaf nodes will be placed outside of their node. Multiple, ray-like oriented node labels will be left aligned. Node labels of nodes having more than one successor 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
Node labels of leaf nodes will be oriented ray-like, i.e. with the same orientation as their node’s incoming edge. Additionally, these node labels will be placed outside of their node. 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.

Results with different Node Labeling policies
NODE_LABELING_RAYLIKE
NODE_LABELING_HORIZONTAL

Enabling the integrated edge labeling support of class BalloonLayout instructs the algorithm to find optimal placements for edge labels such that there are no overlaps of edge labels with each other or with graph elements. In addition, the edge labels are also oriented and arranged by BalloonLayout.

Edge labeling
Edge label placement where labels are configured with preferred placement atthe target node and on the right side of the edge.

Note that edge label placement configurations by means of the PreferredPlacementDescriptor are currently only partially supported by the integrated edge labeling of BalloonLayout. Placement of the edge label at a specified preferred side of the edge can be guaranteed. Preferred placement of the edge label at the source node or target node, however, cannot be guaranteed entirely.

Optimal label placement with integrated edge labeling can be achieved using FreeEdgeLabelModel as the label model for the edge labels. As explained in Label Models, this edge label model is ideally suited in combination with integrated edge labeling and yields the best match for a label location that is computed by BalloonLayout.

Incremental Layout

BalloonLayout can be set to "layout from sketch" mode to provide support for incremental layout. In this mode, a diagram’s current drawing is taken into account when calculating a new layout. The following property enables "layout from sketch" mode:

fromSketchMode
Enables "layout from sketch" mode.

Node Halos

BalloonLayout by default supports node halos as soon as they are declared using layout data. 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 option "Allow Overlaps" is activated.

Layout Data

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

interleavedNodes
For each node a boolean value indicating whether interleaved child node placement should be enabled.
Data Provider Key: INTERLEAVED_NODES_DP_KEY
Maps from node to boolean
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
treeRoot
A boolean value for marking the node that will be used as root node of the tree.
Data Provider Key: SELECTED_ROOT_DP_KEY
Maps from node to boolean
TreeReductionStageData.edgeBundleDescriptors
For each edge an EdgeBundleDescriptor object that configures edge bundling options.
Maps 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_KEY
Maps from graph to AbortHandler
NODE_ORDER_COMPARABLE_DP_KEY
For each subtree’s root the order of its child nodes.
Data Provider Key: NODE_ORDER_COMPARABLE_DP_KEY
Maps from node to Comparable
outEdgeComparer
For each subtree’s root the order of its outgoing edges. (Overrides comparer])
Data Provider Key: -
Maps from edge to comparison function
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

Aspect Ratio Tree Layout

Class AspectRatioTreeLayout generates compact orthogonal tree drawings. As a layout constraint a preferred aspect ratio (relation of width to height) can be given. This is especially useful when the graph should fit perfectly on a page of given size.

Sample layouts of the same tree using different preferred aspect ratio settings
Using aspect ratio 2.0
Using aspect ratio 1.0
Using aspect ratio 0.5

Basic Options

These options configure class AspectRatioTreeLayout in detail.

Horizontal Space
horizontalDistance
The minimal horizontal distance between adjacent nodes.
Vertical Space
verticalDistance
The minimal vertical distance between adjacent nodes.
Bend Distance
bendDistance
Determines the preferred minimal distance between each two bends of an edge and between the first and last edges and the corresponding ports.
Preferred Aspect Ratio
aspectRatio
Determines the preferred aspect ratio (width by height) of the resulting layout. This option allows for creating layouts which, e.g., fit perfectly onto the page of a book.

Layout Data

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

subtreeAspectRatios
For each root node a Number object encapsulating a double value that indicates the subtree’s aspect ratio.
Data Provider Key: SUBTREE_ASPECT_RATIO_DP_KEY
Maps from node to Number
rootPlacements
For each root node one of TOP, CORNER, CORNER_SIDE, or CORNER_TOP to indicate the root node’s placement.
Data Provider Key: ROOT_PLACEMENT_DP_KEY
Maps from node to Object
subtreeRoutingPolicies
For each root node either HORIZONTAL or VERTICAL to indicate horizontal or vertical edge routing.
Maps from node to Object
TreeReductionStageData.edgeBundleDescriptors
For each edge an EdgeBundleDescriptor object that configures edge bundling options.
Maps from edge to EdgeBundleDescriptor
NODE_ORDER_COMPARABLE_DP_KEY
For each subtree’s root the order of its child nodes.
Data Provider Key: NODE_ORDER_COMPARABLE_DP_KEY
Maps from node to Comparable