C

PartialLayout

Show Usages
This class represents a partial layout algorithm which changes the coordinates for a given set of graph elements (called partial elements) only.

Remarks

The location and size of the remaining elements (called fixed elements) is not allowed to be changed.

Layout Style

This partial layout algorithm offers a kind of generic partial layout support for other existing layout algorithms. Hence, its layout style heavily depends on the selected coreLayout as well as the specified edgeRouter or edgeRoutingStyle.

The partial layout is suitable for applications where users may incrementally add new elements to an existing drawing. The added elements should be arranged so that they fit best possible into the given diagram without making any changes to the already existing layout. Hence, the so-called mental map of the existing drawing is preserved.

The input graph where marked nodes denote the partial elements that were incrementally added to the existing diagram.

The result of a partial layout run with componentAssignmentStrategy set to SINGLE and with node alignment enabled.

Features

Similar to the layout style, the supported feature set mainly depends on the features supported by the specified coreLayout as well as the specified edgeRouter or edgeRoutingStyle. The internal step that places the components can handle group nodes and is able to consider minimum distance constraints and node labels.

Furthermore, the algorithm tries to place a subgraph component within the associated cell of the LayoutGrid. For this feature to work properly it is required that the values of the properties position, position, width and height are correctly specified. Note that the algorithm does not guarantee that the calculated subgraph layout fits into the grid cell.

Concept

The layout algorithm tries to place the partial elements such that the resulting drawing (including the fixed elements) has a good quality with respect to common graph drawing aesthetics.

The layout algorithm handles each selected graph element as partial element. Selected graph elements can be defined using properties scope. Partial node elements can be assigned to the so-called subgraph components. During the layout process each subgraph induced by the nodes of a component is first laid out using the specified coreLayout. Then, the different components are placed one-by-one onto the drawing area such that the number of overlaps among graph elements is small. The user can specify different objectives for finding 'good' positions for subgraph components (see subgraphPlacement), e.g., BARYCENTER specifies that the component should be placed close to the barycenter of its graph neighbors and FROM_SKETCH specifies that the component should be placed close to its original position.

Method componentAssignmentStrategy allows to specify the strategy that assigns partial nodes to subgraph components. Possible values are CLUSTERING, CONNECTED, and SINGLE. Note that nodes of a component cannot be assigned to different group nodes.

Furthermore, the user can specify the edge routing style (see edgeRoutingStyle) that is used for routing partial edges and edges between different subgraph components (so-called inter-edges). Possible values are ORGANIC, ORTHOGONAL, STRAIGHT_LINE, OCTILINEAR and AUTOMATIC.

Default Values of Properties

NameDefaultDescription
allowMirroringfalse
Mirroring is disabled.
allowMovingFixedElementsfalse
The algorithm doesn't move fixed elements.
componentAssignmentStrategyComponentAssignmentStrategy.SINGLE
Each partial node is assigned to a separate subgraph component.
componentCompactiontrue
Subgraph component may be placed within another subgraph component.
considerNodeAlignmentfalse
Nodes are not aligned.
coreLayoutnull
edgeRouterStraightLineEdgeRouter
edgeRoutingStylePartialLayoutRoutingStyle.STRAIGHT_LINE
layoutOrientationPartialLayoutOrientation.NONE
The layout orientation is completely ignored.
minimumNodeDistance10
optimizeOrientationtrue
This postprocessing step is enabled.
resizeFixedGroupsfalse
Fixed group nodes may not be resized.
routeInterEdgesImmediatelyfalse
Edges are not routed immediately.
stopDurationTimeSpan.MAX_VALUE
The time is not limited.
subgraphPlacementSubgraphPlacement.BARYCENTER
Each subgraph component is placed close to the barycenter of its graph neighbors.

See Also

Developer's Guide

Members

Show:

Constructors

PartialLayout

(coreLayout?: ILayoutAlgorithm)
Creates a new instance of PartialLayout which uses the specified ILayoutAlgorithm instance as the core layout algorithm.
This instance is applied to each subgraph component, see componentAssignmentStrategy.

Parameters

coreLayout?: ILayoutAlgorithm
the layout algorithm that is applied to the subgraph components

See Also

API
componentAssignmentStrategy

Properties

allowMirroring

: boolean
Gets or sets whether subgraph components may be mirrored to improve the layout quality.
If enabled, the algorithm checks for each component which of the four possible mirrorings minimizes the edge length.
final

Property Value

true if subgraph components are mirrored, false otherwise

Default Value

The default value is: false
Mirroring is disabled.

Sample Graphs

ShownSetting: The input graph where node 1 and 2 are fixed while the remaining nodes are partial. The partial layout is applied to this graph with partitionDescriptor. style set to CYCLE and the componentAssignmentStrategy set to CONNECTED.

allowMovingFixedElements

: boolean
Gets or sets whether or not the algorithm may move fixed elements.
Even though the main objective of the partial layout is to keep non-partial elements fixed, it may sometimes be advantageous to allow them to move in order to obtain more suitable placements of the partial components. Especially if the partial components are quite large, it is very difficult to find a good place without moving fixed elements.
Enabling this option is only recommended if the routing style of the edges (including the current routing style of the non-partial edges) is either orthogonal or octilinear.
final

Property Value

true if the algorithm may move fixed elements, false otherwise.

Default Value

The default value is: false
The algorithm doesn't move fixed elements.

componentAssignmentStrategy

: ComponentAssignmentStrategy
Gets or sets the strategy that assigns partial nodes to subgraph components.

To define custom components instead of using the predefined strategies, use componentIds. In this case, the value of componentAssignmentStrategy will be ignored.

The specified coreLayout independently calculates the layout for each subgraph component.

  • SINGLE: each partial node is a separate subgraph component. The specified core layout doesn't have any effect because it is applied to each single node separately.
  • CONNECTED: components are defined by the connected components of the graph induced by the partial elements.
  • CLUSTERING: components are defined by edge betweenness clustering.
Borders of groups and layout grid cells always split up the components, i.e., two nodes assigned to different groups or layout grid cells are always assigned to different subgraph components.
conversionfinal

Property Value

one of the predefined assignment strategies

Default Value

The default value is: ComponentAssignmentStrategy.SINGLE
Each partial node is assigned to a separate subgraph component.

Sample Graphs

ShownSetting: The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

See Also

Developer's Guide
API
componentIds, coreLayout

componentCompaction

: boolean
Gets or sets whether or not a subgraph component may be placed within another subgraph component.
Enabling this option leads to more compact layout results but requires more runtime.
final

Property Value

true if a subgraph component may be placed within another subgraph component, false otherwise

Default Value

The default value is: true
Subgraph component may be placed within another subgraph component.

considerNodeAlignment

: boolean
Gets or sets whether or not partial nodes should be aligned.
If this option is enabled, the algorithm tries to align the center of partial nodes with other nodes.
Since the specified coreLayout doesn't consider this option, the alignment works best if the component assignment is set to SINGLE.
final

Property Value

true if nodes are aligned, false otherwise

Default Value

The default value is: false
Nodes are not aligned.

Sample Graphs

ShownSetting: false - partial node 3 is not aligned with the other nodes.

See Also

Developer's Guide

coreLayout

: ILayoutAlgorithm
Gets or sets the core ILayoutAlgorithm that is wrapped by this stage.
final

Property Value

the core layout routine

Default Value

The default value is: null

edgeRouter

: ILayoutAlgorithm
Gets or sets the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).
Calling method edgeRoutingStyle automatically sets a new edge router instance according to the specified routing style.
final

Property Value

the custom edge router instance that is used for partial edges and edges between different subgraph components

Default Value

The default value is: StraightLineEdgeRouter

See Also

API
edgeRoutingStyle

edgeRoutingStyle

: PartialLayoutRoutingStyle
Gets or sets the routing style that is used for partial edges and inter-edges.
Inter-edges are edges between fixed and partial nodes as well as edges between different subgraph components. The available strategies are listed in the following.
  • STRAIGHT_LINE produces straight-line edge routes.
  • ORTHOGONAL produces orthogonal edge routes.
  • OCTILINEAR produces octilinear edge routes.
  • ORGANIC produces organic edge routes.
  • AUTOMATIC automatically chooses a suitable style for the partial edges inter-edges, based on the existing routes of the fixed edges.
Calling this method disables a previously set customized edge router, see edgeRouter.
Calling this method disables a previously set customized edge router, see edgeRouter.
conversionfinal

Property Value

one of the predefined edge routing styles

Default Value

Sample Graphs

ShownSetting: The input graph where node 2 is a partial node.

See Also

Developer's Guide
API
edgeRouter

enabled

: boolean
Gets or sets a value that determines whether this stage should do anything but execute the coreLayout.

By default, when constructed, stages should be enabled. Users may disable a stage's functionality by setting this property to false.

Stages that can guarantee that the graph will not change can choose to not even execute the coreLayout when disabled.

final

layoutOrientation

: PartialLayoutOrientation
Gets or sets the layout orientation that is considered during the placement of partial elements.
More precisely, the algorithm tries to place each subgraph component such that each predecessor of a component's node v is placed before v and each successor after v with respect to the layout orientation.
  • NONE: the layout orientation is completely ignored.
  • AUTO_DETECT: the layout orientation is automatically detected. The algorithm analyzes the flow direction of fixed edges in the current drawing. If there is no common flow direction, the results are the same as for NONE. Otherwise, the layout orientation is one of the four main orientations.
  • TOP_TO_BOTTOM: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed above v and each successor below v.
  • BOTTOM_TO_TOP: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed below v and each successor above v.
  • LEFT_TO_RIGHT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the left of v and each successor to the right of v.
  • RIGHT_TO_LEFT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the right of v and each successor to the left of v.
This only affects the placement of nodes of different subgraph components that are connected by oriented edges. For nodes of the same subgraph component the layout orientation depends on the chosen coreLayout.
conversionfinal

Property Value

one of the predefined layout orientations

Default Value

The default value is: PartialLayoutOrientation.NONE
The layout orientation is completely ignored.

Sample Graphs

ShownSetting: NONE: the partial node 3 is placed without considering the layout orientation.

See Also

API
edgeOrientation

minimumNodeDistance

: number
Gets or sets the minimum distance between two adjacent nodes.
The specified value has to be non-negative.
final

Property Value

the non-negative minimum distance

Throws

Exception ({ name: 'ArgumentError' })
if the distance is negative

Default Value

The default value is: 10

Sample Graphs

ShownSetting: 10 - the partial nodes (node 2 and 3) are placed such that the minimum distance between adjacent nodes is at least 10

See Also

Developer's Guide

optimizeOrientation

: boolean
Gets or sets whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.
final

Property Value

true if this postprocessing step is applied, false otherwise

Default Value

The default value is: true
This postprocessing step is enabled.

See Also

API
layoutOrientation, edgeOrientation

resizeFixedGroups

: boolean
Gets or sets whether or not fixed (non-partial) group nodes may be resized.
Enabling this option may lead to better results if there are fixed group nodes, since there is more space for the partial elements.
final

Property Value

true if fixed group nodes may be resized, false otherwise

Default Value

The default value is: false
Fixed group nodes may not be resized.

routeInterEdgesImmediately

: boolean
Gets or sets whether or not edges between different subgraph components should be routed immediately.
If this option is enabled, edges are routed during the placement of the subgraph components, i.e., immediately after a component is placed, its edges to other already placed components are routed. Otherwise, these edges are routed in a separate step after placing all subgraph components. Hence, while enabling this option usually leads to shorter edge routes, the placement of subgraph components is less compact.
final

Property Value

true if edges between different subgraph components are routed immediately, false otherwise.

Default Value

The default value is: false
Edges are not routed immediately.

See Also

API
routeInterEdges, placeSubgraphs

stopDuration

: TimeSpan
Gets or sets the preferred time limit for the layout algorithm.
The specified value has to be greater than or equal to ZERO. If the value is MAX_VALUE, the time is not limited.
Restricting the duration may result in a worse layout quality. Furthermore, the real runtime may exceed the stop duration since the layout algorithm still has to find a valid solution.
conversionfinal

Throws

Exception ({ name: 'ArgumentError' })
if the given duration is negative

Default Value

The default value is: TimeSpan.MAX_VALUE
The time is not limited.

See Also

Developer's Guide

subgraphPlacement

: SubgraphPlacement
Gets or sets the objective used for finding 'good' positions for subgraph components.
conversionfinal

Property Value

one of the predefined positioning strategies

Default Value

The default value is: SubgraphPlacement.BARYCENTER
Each subgraph component is placed close to the barycenter of its graph neighbors.

See Also

Developer's Guide

Methods

applyLayout

(graph: LayoutGraph)
Implementation of the ILayoutAlgorithm interface and main entry point for the layout calculation.
This implementation checks the enabled state and when it's not enabled, will delegate to the coreLayout, directly. When the stage is enabled, all the work will be delegated to applyLayoutImpl, instead.
final

Parameters

graph: LayoutGraph
The graph to apply the layout to.

applyLayoutImpl

(graph: LayoutGraph)
protected
This method calculates the partial layout.
It calls the following methods:
  1. routeEdgesBetweenFixedElements
  2. applyLayout on the coreLayout for each subgraph component
  3. placeSubgraphs
  4. routeInterEdges
The above methods are called after applying the OrientationStage. Hence, they always assume that the graph is drawn from top to bottom.
protected

Parameters

graph: LayoutGraph
the input graph

createLayoutData

(graph: LayoutGraph): PartialLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the PartialLayout.
The generic type arguments of the created layout data are compatible with instances of LayoutGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.

Parameters

graph: LayoutGraph
the graph that determines the generic type arguments of the created layout data

Return Value

PartialLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
an instance of layout data that can be used to perform item-specific configurations for the given PartialLayout.

createLayoutData

(graph?: IGraph): PartialLayoutData<INode, IEdge, ILabel, ILabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the PartialLayout.
The generic type arguments of the created layout data are compatible with instances of IGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.
This method is not available unless the module view-layout-bridge is loaded. Either load the module 'view-layout-bridge' explicitly or ensure that the LayoutExecutor type is available at runtime.

Parameters

graph?: IGraph
the graph that determines the generic type arguments of the created layout data

Return Value

PartialLayoutData<INode, IEdge, ILabel, ILabel>
an instance of layout data that can be used to perform item-specific configurations for the given PartialLayout.

Constants

All constants are filtered. Go to Filters.