HierarchicalLayout

Layout Style

The nodes are distributed into layers so that most of the edges point to the main layout direction. The order of the nodes within the layers ensures that the number of edge crossings is as small as possible. There are different edge routing styles available. Edges can be orthogonal, polyline, octilinear, or curved (see RoutingStyleDescriptor for details).

Hierarchical diagrams are commonly used for the visualization of hierarchical data, since they facilitate the identification of dependencies and relationships among the nodes of the graph. Possible application domains are the following: workflow visualization, call graph visualization, entity-relationship diagrams, biochemical pathways, and network management.

Hierarchical Layout obtained with default settings

Concept

The layout algorithm runs in three main phases:

• Layering – The nodes are distributed into layers by means of fromScratchLayerAssigner or fixedElementsLayerAssigner, respectively. If the layout orientation is top-to-bottom, the nodes in each layer are arranged horizontally while the layers are ordered vertically top-to-bottom.
• Sequencing – The order of the nodes in each layer is determined such that the number of edge crossings is as small as possible. To specify the sequencing algorithm, use fromScratchSequencer or fixedElementsSequencer.
• Drawing – The layout algorithm assigns the final coordinates to all nodes and routes the edges.

Features

This layout algorithm is able to create hierarchical layouts from scratch or add new elements to the existing sketch drawing incrementally. In order to add elements incrementally to the current sketch or let the algorithm optimize certain elements in the current sketch, set fromSketchMode to true. Then associate the IncrementalNodeHints with the elements to be added incrementally via the layout data property incrementalNodes and/or define a collection of edges that should be sequenced incrementally via property incrementalEdges.

HierarchicalLayoutNodeDescriptor and HierarchicalLayoutEdgeDescriptor instances can be used for specifying individual information (e.g. distances or routing styles) for each node and edge in the graph. The descriptors are bound to the graph using properties nodeDescriptors or edgeDescriptors. If there is no descriptor assigned to some nodes/edges, a default descriptor will be used. To set default descriptors use defaultNodeDescriptor and defaultEdgeDescriptor.

HierarchicalLayout supports connecting edges to a node on a specific side or even an exact location by assigning LayoutPortCandidates to the edges or NodePortCandidatess to the nodes. If an edge with registered LayoutPortCandidates connects to nodes with NodePortCandidatess, the algorithm will try to match both collections to find an appropriate port. In case there is no matching port candidate, a LayoutPortCandidate specified for the edge is preferred. For the matching to work properly, the candidates in both collections need to be the same instances. Furthermore, LayoutPortCandidates with multiple sides (e.g. LEFT or] RIGHT) are not supported. To model that an edge should connect at one of several sides, define multiple candidates instead, where each candidate has a single side.

The edge grouping feature of this layout algorithm is restricted to normal, hierarchical edges. Edges with recursiveEdgePolicy DIRECTED or UNDIRECTED will not be grouped. They are also not grouped when enabling automaticEdgeGrouping.

The port grouping feature (see sourcePortGroupIds and targetPortGroupIds in ports) allows to specify edges that share the same port location at their source/target. However, unlike as for edge grouping, edges with port groups will be routed independently without sharing segments. Port grouping has similar restrictions as the edge grouping feature. In addition, port grouping is not considered for self-loops.

The port alignment feature (see sourcePortAlignmentIds and targetPortAlignmentIds) allow to specify edges that either share the same port location or be placed exactly opposite provided. The alignment is not considered when deciding on which node sides to place the ports. To ensure that the edges are aligned in the presence of EdgePortCandidates or NodePortCandidates, it is recommended to assign consistent candidates to all aligned edges. Alignment works both for edges in the layoutOrientation (for example edges with ports on the TOP or BOTTOM sides if the layout orientation is top-to-bottom) and edges that are orthogonal to it. However, the quality of the resulting layouts is typically higher when aligning edges in the layout orientation. Port alignment is not supported at group nodes, for self-loops, and for edges that are part of a grid component at the root of the grid component.

The HierarchicalLayout also supports nodeTypes as a subordinate criterion during the sequencing of nodes within their layer. More precisely, the sequencing algorithm prefers to place nodes of the same type next to each other if this does not induce additional crossings or conflicts with other constraints (like node groups, swimlanes, or sequenceConstraints ). The algorithm uses an additional local optimization heuristic to improve the placement with respect to node types and, thus, does not guarantee optimal results. Furthermore, this additional step may increase the required runtime. Note that node types do not affect the layer assignment.

HierarchicalLayout allows restricting the duration which may be a suitable option to reduce the runtime required for large graphs. Note that restricting the maximum duration can result in a lower layout quality. Furthermore, the actual runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

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:

• SubgraphLayoutStage: Filters the graph to include only specific nodes and edges from a subgraph while preserving the positions of excluded elements. Note: This stage is disabled by default.
• ComponentLayout: Arranges graph components with customizable styles. Note: This stage is disabled by default.
• GenericLabeling: Efficiently places node and edge labels. The property fillEmptyScope is set to false and stopDuration is set to ZERO.
• OrientationStage: Changes the layout orientation in four possible directions, with or without mirroring on the x or y-axis. The property edgeLabelPlacement is set to IGNORE to allow for proper handling of edge labels in the hierarchical layout.

With these layoutStages the layout algorithm is configured well, so they usually don't need to be changed.

Performance

Specifying a stopDuration can reduce the time the HierarchicalLayout takes to produce a result. The acceleration is achieved by switching to faster heuristics for some features and skipping some optional optimization steps. This can impact the quality of the layout result and is usually most noticeable in the calculated edge routes. It should be noted that the stopDuration is not a guarantee for the maximum time spent, as the algorithm still has to produce a valid result.

The coordinateAssigner uses a comparably expensive SymmetryOptimizationStrategy by default, which improves the symmetry of the calculated layout result. This optimization can be disabled to speed up the layout calculation, or the faster WEAK strategy can be applied as a compromise between speed and quality.