C

FillAreaLayout

Show Usages
This layout algorithm tries to fill a specified area with graph elements by moving nearby elements towards it, with the goal to make the existing layout more compact and not changing it too much.
ImplementsInheritance Hierarchy

Remarks

Layout Style

The algorithm can make an existing layout more compact in the region of the defined area. It moves nearby graph elements, while keeping the given layout style as much as possible. Ideally, only local changes around the marked area are made such that the mental map for the user is preserved. The best applications are those where it shall be avoided to calculate a completely new layout after local changes have been made to an already existing and good layout. Also note that the results for this application are much better when the edge paths are already good orthogonal, polyline or octilinear paths. For straight-line edge routes, the shape and overall mental map of the layout can not be preserved that well and the changes may be more global.

An example application is the use case that nodes were removed from the graph. The region where the nodes have been removed can then be defined as the area so that the algorithm can try to fill/use this free space and make the layout more compact. This way it can be avoided to compute a completely new layout for such cases. Another use case would be when a group node is collapsed and converted to a smaller folder node. In that case the folder node should be marked as fixed. Note that it isn't guaranteed that the area is filled with elements after calling the algorithm.

Sample input graph where the gray area should be filled with elements.

Result layout after applying this algorithm - the drawing was made much more compact and the free area is used.

Concept

The area (see area) defines a region in the given graph which should be filled with elements, with the goal to make the overall layout more compact. To do so, graph elements must be moved. This includes nodes, edges and their labels. Whether node labels and edge labels should be considered can be controlled via settings nodeLabelPlacement and edgeLabelPlacement.

Keep in mind that the goal is to make the layout more compact. Therefore, if the area is located such that it brings no advantage to move elements towards it, the algorithm may also do nothing - based on a heuristic decision. This means that it does not fill the specified area in any case.

Features

The algorithm is able to consider a specified LayoutGrid as long as there are no group nodes that span multiple grid cells. For this feature to work properly it is required that the values of the properties position, position, width and height are correctly specified. This is usually automatically the case when executing the FillAreaLayout as a standalone algorithm via layout execution convenience methods (e.g. the values are taken from the table visualization of the grid). However, if the FillAreaLayout is applied as part of a more complex layout pipeline it may be necessary to specify the values manually. For example, if another algorithm previously computed the grid position values and stored them in the respective 'computed' properties (e.g. position), and afterwards FillAreaLayout should be applied, then the 'computed' values of the first algorithm should be written to the 'original' values prior to the run of the FillAreaLayout.

Layout Stages

This class provides a configurable pipeline that contains various ILayoutStages. Each ILayoutStage can incorporate preprocessing or postprocessing steps into the layout calculation to streamline the input graph and enhance the resulting layout. Additionally, custom ILayoutStages can be added and executed either before or after the predefined ones.

The following default ILayoutStages are included:

With these layoutStages the layout algorithm is configured well, so they usually don't need to be changed.

Default Values of Properties

NameDefaultDescription
areanull
There is no area to be filled.
componentAssignmentStrategyComponentAssignmentStrategy.SINGLE
Each node is a separate component.
edgeLabelPlacementFillAreaLayoutEdgeLabelPlacement.CONSIDER
Edge labels are considered.
gridSpacing0
No grid is considered.
layoutOrientationPartialLayoutOrientation.NONE
The layout is considered to have no specific orientation.
nodeLabelPlacementNodeLabelPlacement.CONSIDER
Node labels are considered.
spacing10
stopDurationTimeSpan.MAX_VALUE

See Also

Developer's Guide

Members

Show:

Constructors

FillAreaLayout

()
Creates a new instance of FillAreaLayout with default settings.

Parameters

Properties

area

: Rect
Gets or sets the rectangular area that should be filled.
The specified area may already contain some elements. In order to fill the area, the algorithm may move elements while it still tries to preserve the mental map of the initial layout. Note that after applying this algorithm it is not guaranteed that there are any elements in the specified area.
If the area is set to null (default) or if it is specified and contains all elements of the graph, the algorithm terminates without changing anything.
conversionfinal

Property Value

the rectangular area that should be filled

Default Value

The default value is: null
There is no area to be filled.

See Also

Developer's Guide

componentAssignmentStrategy

: ComponentAssignmentStrategy
Gets or sets the strategy that assigns nodes to components whose elements should preferably not be separated.

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

While the algorithm may move a whole component, it tries to not move only a subset of its elements, thus, all elements of a component are not moved at all or moved by the same offset.

  • CONNECTED components are defined by the connected components of the graph.
  • CLUSTERING: components are defined by edge betweenness clustering.
  • SINGLE: each node is a separate component which basically means that there are no components that should explicitly be kept together.
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 node is a separate component.

See Also

API
componentIds

edgeLabelPlacement

: FillAreaLayoutEdgeLabelPlacement
Gets or sets how the layout handles the position of edge labels.
conversionfinal

Property Value

CONSIDER if the layout algorithm considers edge labels when moving elements such that overlaps with them are not allowed. Furthermore, they are correctly moved along with an edge if an edge is moved. IGNORE if the positions should be ignored, and GENERIC if the edge labels are placed by an independent labeling algorithm subsequently.

Default Value

Edge labels are considered.

genericLabeling

: GenericLabeling
readonly
Gets the GenericLabeling helper class from the layoutStages of this instance.
If you need to replace the instance, modify the layoutStages stack using replace. If you want to remove a stage, consider disabling it instead.
readonlyfinal

Throws

Exception ({ name: 'InvalidOperationError' })
If there is no instance of the respective type in the layoutStages

gridSpacing

: number
Gets or sets the current grid spacing.

Elements are moved by multiples of this value, thus, keeping their offset to the grid. That way, components or parts of them that were placed on a grid before, will stay on their original grid.

The grid spacing needs to be a non-negative value. If it is set to 0, no grid is considered.

For edges that need to be rerouted, it is not guaranteed that the bends are placed on grid points.
final

Property Value

the grid spacing

Throws

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

Default Value

The default value is: 0
No grid is considered.

layoutOrientation

: PartialLayoutOrientation
Gets or sets the layout orientation that is considered during the compaction process.

The orientation affects the direction that the algorithm prefers when moving elements. For the vertical orientations TOP_TO_BOTTOM and BOTTOM_TO_TOP, moving elements horizontally (i.e. to the left and to the right) is preferred. For the horizontal orientations LEFT_TO_RIGHT and RIGHT_TO_LEFT, the vertical moving direction is preferred. This is mainly useful for layouts that have a clear direction and nodes are divided into layers with respect to this direction, like e.g., hierarchical layouts.

If this behavior is undesired, the orientation can be ignored by specifying NONE. No specific moving direction will be preferred in that case. The orientation can also be automatically detected based on the flow direction of the edges when choosing AUTO_DETECT.

conversionfinal

Property Value

one of the predefined layout orientations

Default Value

The default value is: PartialLayoutOrientation.NONE
The layout is considered to have no specific orientation.

nodeLabelPlacement

: NodeLabelPlacement
Gets or sets how the layout handles the position of node labels.
conversionfinal

Property Value

CONSIDER if the layout algorithm takes the position and sizes of the node labels into account, IGNORE if the node labels are ignored by the layout algorithm, and GENERIC if the node labels are placed by an independent labeling algorithm subsequently.

Default Value

The default value is: NodeLabelPlacement.CONSIDER
Node labels are considered.

spacing

: number
Gets or sets the spacing that is considered between elements when they are moved.

This spacing only affects the moving of elements towards the desired area. Elements keep the specified distance to other elements and among each other. Carefully observe that if the distance between two elements is already smaller, then they may not be moved apart.

The spacing is considered for all graph elements, including nodes, edges, node labels, and edge labels when they are encountered during the movement process.

final

Property Value

the non-negative spacing between elements

Throws

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

Default Value

The default value is: 10

Sample Graphs

ShownSetting: Spacing set to 10 (the gray region was compacted).

stopDuration

: TimeSpan
Gets or sets the time limit for the layout algorithm.
Values have to be greater than or equal to ZERO.
Restricting the stop duration may result in a lower layout quality. Furthermore, the real runtime may exceed the stop duration since the layout algorithm still has to find a valid solution.
conversionfinal

Property Value

the non-negative value that specifies the time limit

Throws

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

Default Value

The default value is: TimeSpan.MAX_VALUE

Methods

applyLayout

(graph: LayoutGraph)
Tries to fill the specified area in the given graph with elements, such that the resulting layout is more compact.
In contrast to applyLayoutCore, graph and layouter are prepared for an independent layout run.
The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.

Parameters

graph: LayoutGraph
the input graph

applyLayoutCore

(graph: LayoutGraph)
protected
Tries to fill the specified area in the given graph with elements, such that the resulting layout is more compact.
protectedfinal

Parameters

graph: LayoutGraph
The input graph

configureAreaOutline

(items: IEnumerable<IModelItem>)
Creates and sets the value of the property area of the layout determined from the items.
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

items: IEnumerable<IModelItem>
The IModelItems from which the rectangular area is determined.

createLayoutData

(graph: LayoutGraph): FillAreaLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the FillAreaLayout.
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

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

createLayoutData

(graph?: IGraph): FillAreaLayoutData<INode, IEdge, ILabel, ILabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the FillAreaLayout.
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

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

See Also

Developer's Guide

Constants

All constants are filtered. Go to Filters.