Partial Layout

This section presents the partial layout concept.

About the Concept

Related to incremental graph layout, the yFiles library also provides support for partial graph layout. This concept is a perfect fit for incremental scenarios where subsequently added parts should be arranged so that they fit best possible into a given diagram without applying any changes to the already existing layout.

Partial layout supports arranging user-specified parts of a diagram, the so-called partial elements. In a first step, partial elements are combined to form subgraph components. Subsequently, these are arranged and afterwards placed so that the remainder of the diagram, which consists of the so-called fixed elements, is not affected.

Placing a subgraph component predominantly means finding a good position that both meets certain proximity criteria and offers enough space to accommodate the subgraph component.

Figure 10.74. Sample results of partial layout

Sample results of partial layout
Sample results of partial layout
Original circular layout plus partial nodes (emphasized). Partial nodes placed as a single subgraph component.
Sample results of partial layout
Sample results of partial layout
Original hierarchical layout (left-to-right orientation) plus partial nodes (emphasized). Partial nodes placed as a single subgraph component integrate well into the diagram.

Compared to incremental layout, the main advantage of partial layout is that it can deal with diagrams of arbitrary origin and layout style, and that the existing layout of the fixed parts of a diagram is left completely unaltered.

Class PartialLayouter

Class PartialLayouter enables layout of user-specified, distinct parts of a diagram without altering the existing layout of the remainder of the diagram. It can be used with flat graphs as well as grouped graphs.

The subset of graph elements that shall be processed (the partial elements) can be specified using the data provider keys PartialNodesDpKey and PartialEdgesDpKey. Note that any edge that is incident to a partial node will implicitly be treated as a partial element, too.

Subgraph Components

The ComponentAssignmentStrategy property controls which strategy is used to form the subgraph components from the set of partial nodes in the graph. For each of the subgraph components a layout is calculated (using the core layout algorithm) and it is then placed according to the specified Subgraph Component Placement. Available options are

Clustering
Description A natural clustering algorithm is used to form the subgraph components. Partial nodes of the same cluster are assigned to the same subgraph component.
Connected
Description All partial nodes of a connected component are assigned to the same subgraph component.
Single
Description Each partial node forms a subgraph component of its own. Note that there is no core layout algorithm applied to a single node subgraph component.
PartialCustomComponents
Description

The mapping from partial nodes to subgraph components will be given by the user. To specify the mapping, a data provider holding such supplemental layout data must be bound to the graph. The data provider is expected to be registered with the graph using key ComponentAssignmentDpKey.

Note that subgraph components cannot be assigned partial nodes that are in different group nodes or different partition cells.

Figure 10.75, “Effects of component assignment strategies” shows the outcome of partial layout calculation using different assignment strategies to form the subgraph component(s) from a set of partial nodes.

Figure 10.75. Effects of component assignment strategies

Effects of component assignment strategies
Effects of component assignment strategies
One subgraph component formed using Connected. Each partial node becomes a subgraph component of its own when using Single.
Core Layout
API
ILayouter CoreLayouter { get; set; }
Description Determines the actual layout algorithm that is used for each single subgraph component.

The core layout algorithm can also be set at creation time:

// Setting the core layout algorithm right away.
PartialLayouter pl = new PartialLayouter(new CircularLayouter());
Subgraph Component Placement
API
PositioningStrategy PositioningStrategy { get; set; }
Description

Determines how to place each subgraph component after layout calculation. Subgraph components are placed in a way that they do not overlap with each other or with the fixed remainder of the diagram. When Consider Node Alignment is enabled, the resulting placement is further refined.

  • SubgraphPositioningStrategy A subgraph component is placed as near as possible to its fixed neighbor nodes, respectively already placed other subgraph components. This yields short edges between the subgraph component and the fixed remainder of the diagram.
  • SubgraphPositioningStrategy A subgraph component is placed as near as possible to its initial position. If space permits, this allows in-place re-arranging of subgraph components, for example.

Figure 10.76, “Different placement for subgraph components” shows how a set of partial nodes (emphasized nodes to the left) is placed as a single subgraph component close to its original position, respectively close to its neighbors. The original circular layout of the diagram (the fixed elements) is left unaltered. Note that subgraph component is laid out using circular layout, too.

Figure 10.76. Different placement for subgraph components

Different placement for subgraph components
Different placement for subgraph components
Different placement for subgraph components
Original circular layout plus additional nodes (emphasized). Partial nodes placed (as a single subgraph component) close to initial position... ...close to their neighbors.
Consider Node Alignment
API
bool ConsiderNodeAlignment { get; set; }
Description Specifies whether or not nodes should be aligned. If set to true, the algorithm tries to center-align nodes from subgraph components with nodes from the fixed remainder of the graph.

Partial layout with and without node alignment enabled is illustrated in Figure 10.77, “Node alignment”.

Figure 10.77. Node alignment

Node alignment
Node alignment
Partial nodes placed close to initial position without node alignment enabled... ...and with node alignment enabled.

Edge Routing

The edge routing style that is used for routing partial edges as well as edges between different subgraph components (so-called inter-edges) can be specified using the EdgeRoutingStrategy property. Available options are

Organic
Description Each edge path will be routed as a straight line or a curved line. Uses class OrganicEdgeRouter.
Orthogonal
Description Each edge path will be routed in an orthogonal style, i.e. only vertical and horizontal line segments will be used. Uses class EdgeRouter.
Octilinear
Description Each edge path will be routed using octilinear routing style, i.e. line segments where the slope is a multiple of 45 degree will be used. Uses class EdgeRouter.
Straightline
Description Each edge path will be routed as a straight line connecting the start node and end node.
Automatic
Description Tries to determine whether the edge routing style in the fixed remainder of the graph is orthogonal or not. If so, edge paths will be routed orthogonally, otherwise straight-line.

Drawing Style Options

Minimal Node Distance
API
int MinimalNodeDistance { get; set; }
Description Determines the minimal distance between subgraph components as well as between a subgraph component and any of its fixed neighbors.

Algorithm Execution Options

Maximal Duration
API
long MaximalDuration { get; set; }
Description Sets the preferred maximum duration of the layout process in milliseconds. By default, the algorithm runs without time restriction. Decreasing this value gives better control over the runtime at the cost of layout quality.

Support for Grouped Graphs

PartialLayouter supports layout of partial elements in grouped graphs. Conceptually, though, if a group node belongs to the set of fixed elements, then any children that are partial nodes require the geometry of the group node to be spacious enough to accommodate the resulting layout of the subgraph components.

Figure 10.78, “Support for partial layout within a group node” shows the result of a partial layout within a group node that itself belongs to the set of fixed elements. In particular, this means that the group node's geometry will not be altered, i.e., neither its size nor its position is allowed to change. The quality of a partial layout in such a situation depends to a great extent on the available space within the group node.

Figure 10.78. Support for partial layout within a group node

Support for partial layout within a group node
Support for partial layout within a group node
Partial nodes inside a group node (that is fixed, i.e., its geometry is not allowed to change). Situation after partial layout.

Configuration Hints

Consider Node Alignment

An existing layout where some nodes lack proper alignment can be improved by marking the nodes as partial, setting property Subgraph Component Assignment Strategy to Single, and enabling Consider Node Alignment.

Subgraph Component Placement

Using an identity core layout algorithm, i.e., an implementation that does not alter the positions of nodes or edges, partial layout can be used to find new optimal positions for entire subgraph components.

Tutorial Demo Code

The layout module class PartialLayoutModule.cs from the LayoutModulesWindow demo application shows configuration aspects of PartialLayouter and can also be used to interactively explore the effects of different settings.

The PartialLayoutDemo tutorial demo application shows different setups of PartialLayouter, each specific to a certain layout style to achieve layout results that simulate the respective style best.

Supplemental Layout Data

Class PartialLayouter knows a number of data provider keys which are used to retrieve supplemental layout data for a graph's elements. The data is bound to the graph by means of a data provider which is registered using a given look-up key. Table 10.63, “Data provider look-up keys” lists all look-up keys that PartialLayouter tests during the layout process in order to query supplemental data.

Binding supplemental layout data to a graph is described in the section called “Providing Supplemental Layout Data”.

Table 10.63. Data provider look-up keys

Key Element Type Value Type Description
PartialNodesDpKey node bool For each node a boolean value indicating whether it is a so-called partial node or not. Note that the set of partial nodes also induces partial edges: an edge that is incident to a partial node is implicitly treated as a partial edge.
PartialEdgesDpKey edge bool For each edge a boolean value indicating whether it is a so-called partial edge or not. Note that an edge that is incident to a partial node is implicitly treated as a partial edge, too.
ComponentAssignmentDpKey node object For each node an arbitrary object indicating the subgraph component it is affiliated with.