OrthogonalEdgeRouter
is a
versatile and powerful layout algorithm for routing a diagram's edges using
vertical and horizontal line segments only.
The positions of the diagram's nodes will remain fixed.
Usually, the routed edges will not cut through any nodes or overlap any other
edges.
The possibilities offered by this router make it a perfect layouter for interactive or incremental scenarios where
- some edges should be re-drawn orthogonally, after the user moves some nodes, or
- subsequently added edges should be drawn to fit the existing diagram.
Figure 5.61. Common use-cases for OrthogonalEdgeRouter
 |
 |
| Graph with fixed node positions, before... | ...and after initial orthogonal edge routing. |
 |
 |
| Subsequently added edges... | ...nicely integrated into existing layout. |
Behind the scenes of orthogonal edge router works a sophisticated path-finding algorithm that can even find routes through a maze. Not only will it find a way but also one with fewest possible changes in direction.
Class OrthogonalEdgeRouter 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 5.33, “Data provider look-up keys” lists all look-up keys for OrthogonalEdgeRouter.
Binding supplemental layout data to a graph is described in the section called “Providing Supplemental Layout Data”.
Table 5.33. Data provider look-up keys
| Key | Element Type | Value Type | Description |
|---|---|---|---|
| SOURCE_PORT_CONSTRAINT_KEY |
Edge | PortConstraint | For each edge a PortConstraint object encoding its source end's port constraint. |
| TARGET_PORT_CONSTRAINT_KEY |
Edge | PortConstraint | For each edge a PortConstraint object encoding its target end's port constraint. |
| SOURCE_PCLIST_DPKEY |
Edge | Collection | For each edge a java.util.Collection of PortCandidate objects that encode the subset of desired anchor locations where the source port likes to connect to. |
| TARGET_PCLIST_DPKEY |
Edge | Collection | For each edge a java.util.Collection of PortCandidate objects that encode the subset of desired anchor locations where the target port likes to connect to. |
OrthogonalEdgeRouter provides a set of options that influence the routing behavior. This section highlights some of the configuration options available.
Scope
(see API)
Determines the set of edges that the router should process.
- All Edges
- Routes all edges in the graph.
- Selected Edges
- Routes only the selected edges in the graph.
- Edges at Selected Nodes
- Routes only the edges connected to selected nodes.
Minimum Edge Distance
(see API)
Determines the distance between any two edge segments. The edge router adheres to the set value as possible, but reduces the distance value selectively, i.e., only for a currently processed edge, when there is too little space to find a path with the proper value.
Use Custom Minimum Distance to Nodes
(see API)
If set, then a custom value for minimum distance between any edge segment and any node side will be used. Otherwise, this distance will automatically be derived from the minimum distance between any two edge segments. Since this option can increase computation time, it is disabled by default.
Custom Minimum Distance to Nodes
(see API)
Determines the distance between any edge segment and any node side. The edge router strictly adheres to the set value. Note that this value normally is being automatically derived unless "Use Custom Minimum Distance Edge to Node" is set.
Route on Grid
(see API)
If set, then all edge paths will be routed on grid lines from a predefined grid. If not set, then "free" routing will be applied to the edge paths.
Grid Spacing
(see API)
Determines the spacing of the grid lines where all edge paths will be routed upon. Grid spacing plays the same role for routing on grid lines as minimum distance between any two edge segments does for "free" routing. The edge router adheres to the set value as possible, but reduces the spacing value selectively, i.e., only for a currently processed edge, when there is too little space to find a path with the proper value.
Space Driven Versus Center Driven Search
(see API)
Determines the ratio between two complementary weighting strategies when looking for an edge path, namely "center driven" and "space driven" weighting. The ratio is expressed with a value between 0.0 and 1.0. Values closer to 0.0 lead to edge paths that are more distributed over the available space. Values closer to 1.0 give more emphasis to paths near the "barycenter" of the given edge.
Local Crossing Minimization
(see API)
If not set, the number of crossings seen at a node's side can increase a lot. Since this option has a positive effect on diagram "readability," it is enabled by default.
Crossing Cost
(see API)
Determines a "penalty" for edge crossings. Basically, a penalty value of n means that an edge rather changes direction n times than cross an already routed edge path. In contrast to "Local Crossing Minimization" this optimization works globally, i.e., on an entire edge path. Good values for a crossing penalty lie in the range from 1.0 to 3.0. By default this value is set to 0.0, i.e., there is no penalty.
Reroute Crossing Edges
(see API)
If set, then edges with many crossings will be rerouted. This optimization makes only sense in combination with values greater than 0.0 for "Crossing Cost." By default, rerouting edges is disabled.
Orthogonal edge router obeys both types of port constraints, weak and strong.
The port constraints are retrieved from data providers that are bound to the
graph using the look-up keys
SOURCE_PORT_CONSTRAINT_KEY
and
TARGET_PORT_CONSTRAINT_KEY,
respectively.
In addition to the support provided for port constraints, orthogonal edge
router also supports the concept of port candidates.
The port candidates for the edges of a graph are retrieved from data providers
that are bound to the graph using the look-up keys
SOURCE_PCLIST_DPKEY
and
TARGET_PCLIST_DPKEY,
respectively.
See the section called “Port Candidates” for a detailed description of this concept.
OrthogonalEdgeRouter supports incremental routing through the "Scope" feature. See the above description.
Table 5.34, “Layout Stages” lists a number of so-called layout stages that can be used to enhance the routing process of class OrthogonalEdgeRouter. Class OrthogonalEdgeRouterModule.java demonstrates how to set up and use these layout stages in conjunction with OrthogonalEdgeRouter.
Table 5.34. Layout Stages
| Classname | Description |
|---|---|
| EdgeGroupRouterStage |
Adds support for edge/port grouping, i.e., bus-style edge routing. |
| GroupNodeRouterStage |
Adds support for routing so-called inter-edges, i.e., edges that cross group node boundaries in a hierarchically organized graph. |
| PatchRouterStage |
Increases routing performance by decomposing the graph. |
| ReducedSphereOfActionStage |
Increases routing performance when only a subset of the graph's edge set should be routed. |
The following yFiles source code demo programs demonstrate how to use OrthogonalEdgeRouter within an application.
Additionally, in UMLClassDiagramLayouterDemo.java enhancing OrthogonalEdgeRouter with edge/port grouping by means of layout stage EdgeGroupRouterStage can be seen.