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.

Incremental and nonincremental layouts
Incremental mode is disabled by default.
To enable incremental mode:
Use the method setIncrementalMode. For example:
layout.setIncrementalMode(true);
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.

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.

Crossing reduction during incremental layouts
To reroute long links from scratch, you must enable the
crossing reduction mechanism for long links:
Use the method setLongLinkCrossingReductionDuringIncremental. For example:
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:
Use the method setCrossingReductionDuringIncremental:
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:
Use the method setIncrementalAbsoluteLevelPositioning. For example:
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).

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:
Use the method setIncrementalAbsoluteLevelPositionRange. For example:
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:
Use the method setIncrementalAbsoluteLevelPositionTendency. For example:
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). 
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 which nodes cannot be laid out incrementally using
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.