AlignmentStage places the nodes of the given layout on automatically determined horizontal and/or vertical lines.
Remarks
The AlignmentStage arranges the nodes on vertical and horizontal lines that are derived from the given layout. It can be used to automatically snap nodes to the same x- or y-coordinates to obtain a grid-like structure. When rearranging the layout, the stage moves the nodes as little as possible.
Concept
The nodes are aligned on heuristically determined lines in two phases.
In the first phase, the nodes are assigned to lines such that the following criteria are taken into account:
- The nodes maintain their order along the x- and y-axis, if possible.
- Nodes that are assigned to the same grid line have similar coordinates in the initial layout.
- The number of lines is minimized.
In the second phase, the positions of these lines and consequently their assigned nodes are determined. The positions are chosen such that the overall movement of the nodes is minimized.
Features
Alignment policy
AlignmentStage supports the alignment of the nodes in horizontal direction, vertical direction or in both directions. The mode is determined by the alignment policy. If a single direction, i.e., SNAP_X or SNAP_Y is selected, the nodes do not move in the orthogonal direction.Snap Distance
The snap distance can be used to balance the trade-off between maintaining the initial graph layout and the grid-like structure produced by the stage. More specifically, the snap distance describes the maximum distance between two nodes that may still be snapped to the same grid line. Therefore, large snap distances produce a more emphasized grid structure, while giving up more of the initial layout compared to smaller snap distances.Minimum Node Distance
The minimum node distance determines the compactness of the result. The distance is enforced in the same direction as the nodes are snapped to (horizontal, vertical, both). It prevents any two nodes on different grid lines from being placed closer to one another.Stripe Separation
If stripe separation is enabled, the nodes of two consecutive grid lines are strictly separated by a line L that has the same orientation as the two grid lines, i.e., the nodes of the two grid lines lie on opposite sides of L. For example, when aligning nodes horizontally with stripe separation, the nodes of two consecutive grid lines are separated by a horizontal line H such that the nodes of one grid line lie above H and the others lie below H. Further, if stripe separation is enabled, the minimum node distance is enforced such that any two nodes of different grid lines are separated by at least the given distance.Node Halos and Node Labels
The automatic alignment stage supports node halos as well as considering node labels when calculating the distances between nodes.Node Overlaps
In case that nodes mutually overlap, applying the stage will resolve these overlaps resulting in a layout without overlaps. However, no guarantees are given how the nodes are rearranged such that it may lead to undesired artifacts. Generally, it is recommended that the initial layout should be free of node overlaps and adhere to the specified minimum node distance as much as possible. To that end, an overlap removal stage can be applied to the layout before this stage.Default Values of Properties
alignmentPolicy | SNAP_X_Y
| Nodes are aligned horizontally and vertically. |
considerNodeLabels | true | Node labels are considered for resolving overlaps when determining the alignment of the nodes. |
gridSpacing | 0.0 | Nodes are aligned on an irregular grid. |
minimumNodeDistance | 15.0 | |
separateStripes | false | Rows and Columns are not strictly separated and may overlap. |
snapDistance | 50.0 |
Type Details
- yfiles module
- layout-core
- yfiles-umd modules
- All layout modules, view-layout-bridge
- Legacy UMD name
- yfiles.layout.AlignmentStage
See Also
Partition Grid
The automatic alignment stage supports the use of a partition grid. It is required that the nodes do not span multiple cells. In particular, it is required that the child nodes of a group node are assigned to the same cell as the group node. In case that the alignment stage is applied only to one dimension, the partition grid is only changed in that dimension, while the other dimension remains unchanged.Constructors
Creates a new AlignmentStage with the given algorithm as core layout algorithm or null
if no core layout should be applied prior to the alignment stage.
Parameters
A map of options to pass to the method.
- coreLayout - ILayoutAlgorithm
- the core layout algorithm
- gridSpacing - number
The distance between two adjacent grid lines to which the nodes can be snapped or zero if nodes are aligned on an irregular grid. This option sets the gridSpacing property on the created object.
- separateStripes - boolean
Whether nodes are placed in strictly separated rows and strictly separated columns. This option sets the separateStripes property on the created object.
- considerNodeLabels - boolean
Whether node labels are taken into account for snapping nodes on common lines. This option sets the considerNodeLabels property on the created object.
- minimumNodeDistance - number
The minimum horizontal and vertical distance between two nodes. This option sets the minimumNodeDistance property on the created object.
- alignmentPolicy - AlignmentStageAlignmentPolicy
The axis, parallel to which the nodes are aligned by the algorithm. This option sets the alignmentPolicy property on the created object.
- snapDistance - number
The maximum distance between two nodes that can be aligned on the same line. This option sets the snapDistance property on the created object.
Properties
Gets or sets the axis, parallel to which the nodes are aligned by the algorithm.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if an unknown alignment policy is given
See Also
Sample Graphs
Gets or sets whether node labels are taken into account for snapping nodes on common lines.
Remarks
Default Value
true
.Node labels are considered for resolving overlaps when determining the alignment of the nodes.
Gets or sets the core layout algorithm that is wrapped by this stage.
Gets or sets the distance between two adjacent grid lines to which the nodes can be snapped or zero if nodes are aligned on an irregular grid.
Remarks
Default Value
0.0
.Nodes are aligned on an irregular grid.
Throws
- Exception({ name: 'ArgumentError' })
- if a negative value is specified
See Also
0.0
, the nodes are aligned on an irregular grid.Gets or sets the minimum horizontal and vertical distance between two nodes.
Remarks
The horizontal distance is enforced if using the SNAP_Y or the SNAP_X_Y alignment policy. The vertical distance is enforced if using the SNAP_Y or the SNAP_X_Y alignment policy.
If alignment separation is enabled, the vertical and horizontal distances are enforced such that any two nodes of different grid lines are separated by at least the given distance in horizontal and vertical direction, respectively.
Default Value
15.0
.Throws
- Exception({ name: 'ArgumentError' })
- if the given value is negative
Sample Graphs
Gets or sets whether nodes are placed in strictly separated rows and strictly separated columns.
Default Value
false
.Rows and Columns are not strictly separated and may overlap.
See Also
Sample Graphs
Gets or sets the maximum distance between two nodes that can be aligned on the same line.
Remarks
Default Value
50.0
.Throws
- Exception({ name: 'ArgumentError' })
- if the given value is negative
See Also
Methods
Aligns the nodes of the graph into a grid-like structure.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Invokes the layout process of the core layout algorithm.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Defined in
Constants
A data provider key for specifying the points of the nodes that are aligned.
Remarks
Domain | YNode | the nodes of the input graph |
Values | YPoint | the position of the snap point relative to the center of the node |