Incremental mode with HL

> > > > >

In some circumstances you, might need to use a sequence of layouts on the same graph. For example:

You work with graphs that have become out-of-date and you need to extend the graph. If you perform a layout on the extended graph, you probably want to identify the parts that were already laid out in the original graph. The layout should not change very much when compared with the layout of the original graph.
The first layout results in a drawing with minor deficiencies. You want to solve these deficiencies manually and perform a second layout to clean up the drawing. The second layout probably should not greatly change the parts of the graph that were already acceptable after the first layout.

The Hierarchical Layout normally works non-incrementally. It performs a layout from scratch and moves all nodes to new positions and reroutes all links. The previous positions of nodes have no influence on the result of the layout. Hence, even a small change can cause a large effect on the next layout.

But the Hierarchical Layout also supports incremental sequences of layout that “do not change very much.” It can place the nodes close to their previous positions, so that you can more easily identify the parts that had already been laid out in the original graph. Incremental mode takes the previous positions of the nodes into account. In this mode, the algorithm preserves the relative order of the levels and the nodes within the levels in the subsequent layout. It does not preserve the absolute positions of the nodes, but it tries to detect the structure of the previous layout by examining the node coordinates. For instance, if two nodes are in the same level, then they stay in the same level after an incremental layout. If a node is in a higher level than another node, it stays in the higher level.

The following figure illustrates the difference between an incremental and nonincremental layout.

Picture
of hierarchical layouts illustrating the effect of the incremental
mode

Incremental and nonincremental layouts

Incremental mode is disabled by default.

To enable incremental mode:

In CSS

Add to the GraphLayout section:

incrementalMode: "true";

In Java™

layout.setIncrementalMode(true);

Important

Be aware of the difference between the incremental mode of the Hierarchical Layout and the incremental layout flag of the SDM Graph Layout Renderer.

The CSS statement incrementalMode: "true";

controls the incremental mode of Hierarchical Layout and specifies that all layouts are performed incrementally.

This feature of the Hierarchical Layout is described in the subsequent sections.

Conversely, the CSS statement

incrementalLayout: "true";s

controls the Node Layout Renderer and means that the Node Layout Renderer switches between incremental mode and nonincremental mode depending on whether an object is selected or not.

This advanced feature of the Node Layout Renderer is explained in The GraphLayout renderer in Developing with the JViews Diagrammer SDK.

Phases of the incremental mode

The layout algorithm analyzes the drawing in incremental mode in the following way:

First, it determines from the node coordinates which nodes must belong to the same level. For instance, if the flow direction is towards the bottom, it tries to detect horizontal reference lines at those vertical positions where many nodes are placed along a line. The specified vertical node offset helps to detect these lines because the horizontal reference lines must be approximately the vertical node offset apart. See the following figure.
All nodes that touch the same reference line are assigned to the same level.
It determines the order of the nodes within each level by analyzing where the node touches the reference line. For instance, if the flow direction is towards the bottom, it determines from the x coordinate of the nodes how they are ordered within the levels.
If long links span several levels, the algorithm can preserve the shape of a long link. It determines the point where a link crosses the level reference line. It creates a bend point for the long link inside the level. It tries to preserve the order of the bend points in each level. For instance, if in a flow direction towards the bottom, a long link bypasses another node on the right side, then the incremental layout tries to find a similar shape of the link that bypasses the node on the right side. See the following figure.
Finally, the layout tries to calculate the absolute positions of the nodes that respect the levels and the ordering within the levels. It tries to balance the node positions. However, it also tries to place each node close to its previous position. Both criteria often compete with each other, because to get a perfect balance, nodes must sometimes move far from their original position. The Hierarchical Layout contains a parametrized heuristic to satisfy both criteria.

The following figure shows the result of the incremental phases.

Picture
illustrating the layout phases in incremental mode

Incremental layout phases

Expert parameters of the incremental mode

Each phase of the incremental mode can be parameterized. These layout parameters are effective only if incremental mode is enabled.

Minimizing long link crossings

The incremental layout tries to preserve the shape of long links that cross several levels. It implies that link crossings between long links are not resolved. If crossings of long links are not wanted, it might be better to reroute long links from scratch. The following figure shows four hierarchy trees, with the original layout at the upper left. The lower right shows the result if long links are rerouted, and the upper right shows the result if the shape of long links is preserved.

Picture
of hierarchical layouts illustrating the effect of the incremental
mode with long link crossing reduction

Crossing reduction during incremental layouts

To reroute long links from scratch, you must enable the crossing reduction mechanism for long links:

In CSS

longLinkCrossingReductionDuringIncremental: "true";

In Java

layout.setLongLinkCrossingReductionDuringIncremental(true);

The crossing reduction of long links determines only the shape of the links. It does not influence the order of the other nodes within the levels.

Minimizing all link crossings

Optionally, you can apply a crossing reduction to all nodes within each level. In this case, the incremental layout determines from the node coordinates which nodes belong to the same level, but it might reorder the nodes within the levels completely to avoid link crossings. It also reorders the long links in this case. The previous figure, lower left shows the result. Notice that the order of the nodes “F,” “G,” and “H” have changed to resolve the link crossings.

To enable the crossing reduction for all nodes:

In CSS

crossingReductionDuringIncremental: "true";

In Java

layout.setCrossingReductionDuringIncremental(true);

Setting absolute level positioning

The incremental layout tries to place the nodes in absolute positions that are close to the previous positions. It tries to avoid nodes moving a long distance, because even if the relative order of the nodes within the levels does not change, long distances can be confusing for users. It is much easier to keep a mental map of the diagram if the nodes remain close to the previous positions.

The following figure illustrates node repositioning with and without taking the previous positions into account. The incremental layout of the original graph (upper left) results in the graph at the upper right, which is easier to recognize as being the same graph than is the graph at the bottom.

The absolute level positioning feature is enabled by default, but it can be disabled.

To disable the absolute level positioning feature:

In CSS

Write the statement:

incrementalAbsoluteLevelPositioning: "false";

In Java

Call

layout.setIncrementalAbsoluteLevelPositioning(false);

With this statement, the layout does not try to place the nodes close to the previous positions. It places the nodes such that the layout is balanced. However, to create a perfect balance, the layout might need to move a few nodes so far apart that you no longer recognize the diagram (see the following figure, bottom).

Picture
of hierarchical layouts illustrating the effect of the incremental
mode with absolute level positioning

Absolute positioning during incremental layouts

Setting absolute level position range and tendency

If absolute level positioning is enabled, it competes with the aesthetic criteria to create a balanced layout. Because nodes must stay close to their previous positions, the diagram after incremental layout might be unbalanced and unsymmetrical. The Hierarchical Layout algorithm uses a heuristic that you can influence by two parameters, the absolute level position range and tendency.

The absolute level positioning feature is enabled by default, but it can be disabled.

To disable the absolute level positioning feature:

In CSS

Add in the GraphLayout section:

incrementalAbsoluteLevelPositioning: "100";

In Java

Call:

layout.setIncrementalAbsoluteLevelPositionRange(100);

This statement specifies that within the range of 100 coordinate units from the old position of the node, the balance is the only criteria for the placement. This means that a node whose optimal position is less than 100 coordinate units away from its previous position is placed exactly at its optimal position. Nodes whose optimal position is farther away are placed at a position that is a compromise between previous position and optimal position. See the following figure, right.

To set the absolute level position tendency:

In CSS

Add in the GraphLayout section:

incrementalAbsoluteLevelPositionTendency: "70";

In Java

Call:

layout.setIncrementalAbsoluteLevelPositionTendency(70);

This statement specifies that when the optimal position of a node is far away from its previous position, its position is 70% influenced by its previous position and 30% influenced by its optimal position. Imagine a rubber band that tries to pull a node to its previous position, and another rubber band that tries to pull the same node to its optimally balanced position. The level position tendency 70 means that one rubber band pulls with 70% of the force towards the previous position, and the other rubber band pulls with 30% towards the optimal position. Increasing the tendency means that the node stays closer to its old position, decreasing it means that the node moves closer to its optimal position. If you set the tendency to 0%, it has the same effect as disabling the incremental absolute level positioning (see the following figure).

Picture
of hierarchical layouts illustrating the effect of the incremental
mode with absolute level position tendency

Absolute positioning during incremental layouts

Marking nodes for incremental layout

Incremental layout normally treats all nodes and links of the drawing in the same way. However, you might have added nodes and links to the drawing programmatically, and the new nodes and links do not have meaningful coordinates yet. Perhaps you have placed them all at the origin (0,0), or at random coordinates. In this case, you need an incremental layout that takes into account the coordinates of all nodes that were previously laid out while ignoring the coordinates of the new nodes.

The incremental mode of the Hierarchical Layout allows you to specify in Java which nodes cannot be laid out incrementally by calling the method:

layout.markForIncremental(nodeOrLink);

If you call this statement, the node or link is marked such that its coordinates are ignored during the next incremental layout. The positions of marked nodes and links are calculated from scratch. The mark is valid only until the next layout and is automatically cleared afterward.

Current section

Hierarchical Layout (HL)