Partial Layout

Related to incremental graph layout, the yFiles library also provides support for partial graph layout, implemented by class PartialLayout. This approach provides an alternative for incremental layout scenarios. It arranges newly added graph elements to seamlessly integrate them into an existing diagram without altering the existing layout.

Partial layout arranges specific parts of a diagram, called partial elements. First, the partial elements are combined into subgraph components. Then, these components are arranged and positioned without affecting the rest of the diagram, which consists of fixed elements.

Positioning a subgraph component involves finding a suitable location that meets proximity criteria and provides enough space.

Samples of partial layout; partial nodes are emphasized and have label 'P'

In the examples above, the subgraph component assignment strategy CONNECTED was used. In these cases, this results in a single subgraph component being placed by PartialLayout.

Compared to incremental layout, partial layout can handle diagrams of any origin and layout style, leaving the existing layout of the fixed diagram parts completely unchanged. However, the layout applied to the subgraph components is not aware of the fixed elements, and the components can only be placed as a whole. This can cause visual discontinuities in the layout style between components or between components and fixed elements, even if they share the same layout style.

Relevant Classes

Class PartialLayout enables the layout of specific, user-defined parts of a diagram. It does this without changing the existing layout of the rest of the diagram. It can be used with flat graphs and grouped graphs.

Class PartialLayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> allows you to provide item-specific data as input. The most important part is property scope, which specifies the subset of graph elements to process (the partial elements). Note that any edge connected to a partial node is automatically treated as a partial element.

Subgraph Components

The componentAssignmentStrategy property controls which strategy is used to form subgraph components from the set of partial nodes in the graph. For each subgraph component, a layout is calculated using the core layout algorithm. Then, it is placed according to the specified Subgraph Component Placement. Available options are:

SINGLE: Default. Each partial node forms its own subgraph component. Note that the core layout has no effect in this case! Instead, the node is simply placed according to the specified subgraph placement.
CLUSTERING: 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: All partial nodes of a connected component are assigned to the same subgraph component.

Carefully note that regardless of the applied strategy, borders of groups and layout grid cells always split up the components. More precisely, two nodes assigned to different groups or LayoutGrid cells are always assigned to different subgraph components.

In addition, it is possible to specify custom componentIds for the nodes using the layout data to define a custom assignment of nodes to subgraph components. In this case, the selected component assignment strategy has no effect. Note that a subgraph component cannot contain partial nodes that are in different group nodes or different LayoutGrid cells.

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.

Core Layout
coreLayout: Determines the actual layout algorithm used for each subgraph component.

The core layout has no effect when using the ComponentAssignmentStrategy value SINGLE, which is the default.

Subgraph Component Placement

subgraphPlacement

Determines how to place each subgraph component. 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.

BARYCENTER A subgraph component is placed as near as possible to its fixed neighbor nodes, or to other already placed subgraph components. This yields short edges between the subgraph component and the fixed remainder of the diagram.
FROM_SKETCH 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.

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 or 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.

Using an identity core layout algorithm, that is, 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.

Consider Node Alignment
considerNodeAlignment: Specifies whether 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 the following figure.

Basic Options

Minimum Node Distance
minimumNodeDistance: Determines the minimum distance between subgraph components and between a subgraph component and any of its fixed neighbors.

Stop Duration
stopDuration: Sets the duration after which the layout process should begin to terminate. By default, the algorithm runs without a time restriction. Decreasing this value gives you better control over the runtime, at the cost of layout quality. Note that the algorithm may exceed the duration, because the termination process, even while sacrificing layout quality, still has to arrive at a consistent layout state.

Edge Routing Options

The edge routing style used for routing partial edges and edges between different subgraph components (called inter-edges) can be specified using the edgeRoutingStyle property. The available options are:

STRAIGHT_LINE: Each edge path will be routed as a straight line connecting the start node and end node.
ORGANIC: Each edge path will be routed as a straight line or a curved line. Uses the class OrganicEdgeRouter.
ORTHOGONAL: Each edge path will be routed in an orthogonal style. Only vertical and horizontal line segments will be used. Uses the class EdgeRouter.
OCTILINEAR: Each edge path will be routed using an octilinear routing style. Line segments where the slope is a multiple of 45 degrees will be used. Uses the class EdgeRouter.
AUTOMATIC: 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, they will be straight-line.

Grouped Graphs

PartialLayout supports the layout of partial elements in grouped graphs. Conceptually, if a group node is in the set of fixed elements, then any child nodes that are partial nodes require the group node’s geometry to be large enough to accommodate the resulting layout of the subgraph components.

Support for partial layout within a group node shows the result of a partial layout within a group node that is a fixed element. This means that the group node’s geometry will not be altered; neither its size nor its position can change. The quality of a partial layout in this situation depends greatly on the available space within the group node.

Orthogonal Layout Radial Layout