y.layout.router
Class OrthogonalEdgeRouter

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.router.OrthogonalEdgeRouter

All Implemented Interfaces:

Layouter, LayoutStage

Direct Known Subclasses:

ChannelEdgeRouter.OrthogonalShortestPathPathFinder

public class OrthogonalEdgeRouter
extends AbstractLayoutStage

This class represents an orthogonal edge router. An orthogonal edge router is a layout algorithm that changes the coordinates of the edge paths in a way that the resulting layout of the edges is me up of vertical and horizontal segments only. The router does not change the location or the size of the nodes in a diagram in any way.

Several LayoutStages can be used to enhance performance and/or functionality of this class, e.g. EdgeGroupRouterStage, GroupNodeRouterStage, ReducedSphereOfActionStage or PatchRouterStage.

This edge router will obey strong and weak port constraints. It expects the port constraints to be bound to the input graph by the data provider keys PortConstraintKeys.SOURCE_PORT_CONSTRAINT_KEY and PortConstraintKeys.TARGET_PORT_CONSTRAINT_KEY. Furthermore, this class supports the more advanced port constraint concept of PortCandidates. It expects collections of port candidates to be bound to the input graph by the data provider keys PortCandidate.SOURCE_PCLIST_DPKEY and PortCandidate.TARGET_PCLIST_DPKEY.

The router often finds ideal routes in difficult situations like the one depicted below.

Field Summary

static byte	ROUTE_ALL_EDGES Sphere of action specifier.
static byte	ROUTE_EDGES_AT_SELECTED_NODES Sphere of action specifier.
static byte	ROUTE_SELECTED_EDGES Sphere of action specifier.
static byte	STYLE_ADHOC Routing style specifier.
static byte	STYLE_PREFERMIDDLE Routing style specifier.
static byte	STYLE_SHORTPATH Routing style specifier.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

OrthogonalEdgeRouter()
Creates a new instance of the Orthogonal Edge Router.

OrthogonalEdgeRouter(Layouter core)
Convenience constructor to simultaneously set a core layout algorithm which will run before the orthogonal edge router.

Method Summary

boolean	canLayout(LayoutGraph graph) Returns true if the specified core layouter does, and also when there is no core layouter.
void	doLayout(LayoutGraph graph) Main entrance to orthogonal edge routing.
boolean	getBadOrthogonal() Returns whether bad edges should be drawn in an orthogonal fashion.
double	getCenterToSpaceRatio() Returns the currently set ratio between the two complementary weighting strategies center driven and space driven.
boolean	getCoupledDistances() Returns whether the minimum distances are coupled.
double	getCrossingCost() Returns the cost for each edge crossing of a routed path.
int	getCustomBorderCapacity() Returns the currently set custom value for the capacity of the routing border around the graph's bounding box.
boolean	getCustomBorderCapacityEnabled() Returns whether a custom value for the capacity of the routing border is used.
YPoint	getGridOrigin() Returns a grid point coordinate used when grid routing is enabled.
int	getGridSpacing() Returns the grid spacing to be assumed when grid routing is enabled.
int	getMinimumDistance() Returns the minimum distance between edge segments.
int	getMinimumDistanceToNode() Returns the minimum distance between edge segments and nodes.
byte	getRoutingStyle() Returns the currently set routing style.
byte	getSphereOfAction() Returns the currently set sphere of action specifier.
boolean	isGridRoutingEnabled() Returns whether or not to route edge segments on grid lines.
boolean	isInnerPortsEnabled() Returns whether edge ports (that do not have a strong port constraint set) should lie inside the node's bounding box or on the node's border.
boolean	isLocalCrossingMinimizationEnabled() Returns whether the local crossing minimization strategy is enabled.
boolean	isReroutingEnabled() Whether rerouting bad edges is enabled.
void	setBadOrthogonal(boolean value) Determines the way that edges which cannot be routed should be drawn.
void	setCenterToSpaceRatio(double csr) Determines the ratio between two complementary weighting strategies, namely center driven and space driven weighting, when looking for an edge path.
void	setCoupledDistances(boolean coupled) Whether or not the minimum distances should be coupled, i.e., whether half the value set for the minimum distance between edge segments should automatically be used as the minimum distance between edge segments and nodes, or a custom value should be used instead.
void	setCrossingCost(double cost) Sets the cost for each edge crossing of a routed path.
void	setCustomBorderCapacity(int value) Determines the custom value for the capacity of the routing border around the graph's bounding box.
void	setCustomBorderCapacityEnabled(boolean value) Whether or not a custom value for the capacity of the routing border around the graph's bounding box should be applied.
void	setGridOrigin(int x, int y) Sets a grid point coordinate used when grid routing is enabled.
void	setGridRoutingEnabled(boolean enabled) Whether or not to route edge segments on grid lines.
void	setGridSpacing(int spacing) Sets the grid spacing to be assumed when grid routing is enabled.
void	setInnerPortsEnabled(boolean value) Whether edge ports (that do not have a strong port constraint set) should lie inside the node's bounding box or on the node's border.
void	setLocalCrossingMinimizationEnabled(boolean enabled) Whether or not a local crossing minimization strategy should be applied.
void	setMinimumDistance(int dist) Sets the minimum distance between edge segments.
void	setMinimumDistanceToNode(int dist) Sets the minimum distance between edge segments and nodes.
boolean	setProperty(String key, Object value) For internal use only.
void	setReroutingEnabled(boolean enabled) Whether or not to enable a further crossing minimization optimization based on rerouting edges that cross many edges.
void	setRoutingStyle(byte style) Sets the preferred routing style for the edges to be routed.
void	setSphereOfAction(byte sphere) Sets the edge (sub-)set to be routed.

Methods inherited from class y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore, getCoreLayouter, setCoreLayouter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROUTE_ALL_EDGES

public static final byte ROUTE_ALL_EDGES

Sphere of action specifier. Route all edges of the input graph.

See Also:

setSphereOfAction(byte), Constant Field Values

ROUTE_SELECTED_EDGES

public static final byte ROUTE_SELECTED_EDGES

Sphere of action specifier. Route only selected edges of the input graph. The selection state of an edge is determined by a boolean value returned by the data provider associated with the data provider key Layouter.SELECTED_EDGES.

See Also:

Graph.addDataProvider(Object,DataProvider), setSphereOfAction(byte), Constant Field Values

ROUTE_EDGES_AT_SELECTED_NODES

public static final byte ROUTE_EDGES_AT_SELECTED_NODES

Sphere of action specifier. Route only edges connected to selected nodes. The selection state of a node is determined by a boolean value returned by the data provider associated with the data provider key Layouter.SELECTED_NODES.

See Also:

Graph.addDataProvider(Object,DataProvider), setSphereOfAction(byte), Constant Field Values

STYLE_ADHOC

public static final byte STYLE_ADHOC

Routing style specifier. Edge segments are drawn ad hoc, i.e., rather crude.

See Also:

setRoutingStyle(byte), Constant Field Values

STYLE_SHORTPATH

public static final byte STYLE_SHORTPATH

Routing style specifier. Edge segments are drawn the short way, i.e., with the global way of the edge in mind.

See Also:

setRoutingStyle(byte), Constant Field Values

STYLE_PREFERMIDDLE

public static final byte STYLE_PREFERMIDDLE

Routing style specifier. Edge segments are drawn with the most distance to already known obstacles such as nodes or other edge segments.

See Also:

setRoutingStyle(byte), Constant Field Values

Constructor Detail

OrthogonalEdgeRouter

public OrthogonalEdgeRouter()

Creates a new instance of the Orthogonal Edge Router. The initial settings (the default values) make up an instance that:

• processes all edges,
• applies "free" routing with a minimum distance between edge segments of 4 [pixel],
• uses an automatically derived minimum distance between edge segments and nodes of 2 [pixel],
• obeys port constraints (if previously set),
• uses an edge routing style, where edge segments are drawn with the most distance to already known obstacles (i.e., nodes and other edge segments),
• draws edges, which cannot be routed, in an orthogonal fashion, and
• places edge ports along the node's bounding box.

See Also:

setSphereOfAction(byte), setGridRoutingEnabled(boolean), setRoutingStyle(byte), setBadOrthogonal(boolean)

OrthogonalEdgeRouter

public OrthogonalEdgeRouter(Layouter core)

Convenience constructor to simultaneously set a core layout algorithm which will run before the orthogonal edge router.

See Also:

OrthogonalEdgeRouter()

Method Detail

canLayout

public boolean canLayout(LayoutGraph graph)

Returns true if the specified core layouter does, and also when there is no core layouter.

doLayout

public void doLayout(LayoutGraph graph)

Main entrance to orthogonal edge routing. Routes the edges of the given graph.

setProperty

public boolean setProperty(String key,
                           Object value)

For internal use only.

setCrossingCost

public void setCrossingCost(double cost)

Sets the cost for each edge crossing of a routed path. A cost of n means that a path rather changes direction n times than crossing the path of an edge. By default the cost is set to 0 and therefore no global crossing optimization is performed. Setting a higher value will activate global crossing minimization. A good trade-off between the number of direction changes and few crossings of a path is achieved by values between 1 and 3.

getCrossingCost

public double getCrossingCost()

Returns the cost for each edge crossing of a routed path.

See Also:

setCrossingCost(double)

setReroutingEnabled

public void setReroutingEnabled(boolean enabled)

Whether or not to enable a further crossing minimization optimization based on rerouting edges that cross many edges. By default this feature is not enabled. Activating this feature only makes sense if the global crossing cost is set to a value greater an 0.

See Also:

setCrossingCost(double)

isReroutingEnabled

public boolean isReroutingEnabled()

Whether rerouting bad edges is enabled.

See Also:

setReroutingEnabled(boolean)

setSphereOfAction

public void setSphereOfAction(byte sphere)

Sets the edge (sub-)set to be routed. Default setting is ROUTE_ALL_EDGES.

Parameters:

sphere - One of ROUTE_SELECTED_EDGES, ROUTE_EDGES_AT_SELECTED_NODES, and ROUTE_ALL_EDGES.

See Also:

Layouter.SELECTED_EDGES, Layouter.SELECTED_NODES

getSphereOfAction

public byte getSphereOfAction()

Returns the currently set sphere of action specifier.

See Also:

setSphereOfAction(byte)

setGridRoutingEnabled

public void setGridRoutingEnabled(boolean enabled)

Whether or not to route edge segments on grid lines. By default this feature is disabled, i.e., "free" routing is enabled.

See Also:

setGridOrigin(int,int), setGridSpacing(int)

isGridRoutingEnabled

public boolean isGridRoutingEnabled()

Returns whether or not to route edge segments on grid lines.

See Also:

setGridRoutingEnabled(boolean)

setGridOrigin

public void setGridOrigin(int x,
                          int y)

Sets a grid point coordinate used when grid routing is enabled. By default (0, 0) is set.

See Also:

setGridRoutingEnabled(boolean)

getGridOrigin

public YPoint getGridOrigin()

Returns a grid point coordinate used when grid routing is enabled.

See Also:

setGridOrigin(int,int)

setGridSpacing

public void setGridSpacing(int spacing)

Sets the grid spacing to be assumed when grid routing is enabled. By default a spacing of 2 is set, which is also the minimum allowed spacing.

Parameters:

spacing - Integral value that determines the desired grid spacing. Positive values less than 2 are ignored, negative values are mapped to their absolute.

See Also:

setGridRoutingEnabled(boolean)

getGridSpacing

public int getGridSpacing()

Returns the grid spacing to be assumed when grid routing is enabled.

See Also:

setGridSpacing(int)

setMinimumDistance

public void setMinimumDistance(int dist)

Sets the minimum distance between edge segments. By default a distance of 2 is set, which is also the minimum allowed distance.

Parameters:

dist - Integral value that determines the desired distance. Positive values less than 4 are ignored, negative values are mapped to their absolute.

Note: If the minimum distances are coupled (as is the default), half the value as set here is automatically used as the minimum distance between edge segments and nodes.

See Also:

setCoupledDistances(boolean), setMinimumDistanceToNode(int)

getMinimumDistance

public int getMinimumDistance()

Returns the minimum distance between edge segments.

See Also:

setMinimumDistance(int)

setCoupledDistances

public void setCoupledDistances(boolean coupled)

Whether or not the minimum distances should be coupled, i.e., whether half the value set for the minimum distance between edge segments should automatically be used as the minimum distance between edge segments and nodes, or a custom value should be used instead.

By default the minimum distances are coupled.

See Also:

setMinimumDistance(int), setMinimumDistanceToNode(int)

getCoupledDistances

public boolean getCoupledDistances()

Returns whether the minimum distances are coupled.

See Also:

setCoupledDistances(boolean)

setMinimumDistanceToNode

public void setMinimumDistanceToNode(int dist)

Sets the minimum distance between edge segments and nodes.

Parameters:

dist - Integral value that determines the desired distance. Positive values less than 2 are ignored, negative values are mapped to their absolute.

Note: If the minimum distances are coupled (as is the default), half the value as set for the minimum distance between edge segments is automatically used here.

See Also:

setCoupledDistances(boolean), setMinimumDistance(int)

getMinimumDistanceToNode

public int getMinimumDistanceToNode()

Returns the minimum distance between edge segments and nodes.

See Also:

setMinimumDistanceToNode(int)

setLocalCrossingMinimizationEnabled

public void setLocalCrossingMinimizationEnabled(boolean enabled)

Whether or not a local crossing minimization strategy should be applied. By default this feature is enabled.

isLocalCrossingMinimizationEnabled

public boolean isLocalCrossingMinimizationEnabled()

Returns whether the local crossing minimization strategy is enabled.

See Also:

setLocalCrossingMinimizationEnabled(boolean)

setCenterToSpaceRatio

public void setCenterToSpaceRatio(double csr)

Determines the ratio between two complementary weighting strategies, namely center driven and space driven weighting, when looking for an edge path.

• Center driven means that those edge paths should be preferred that are closer to the edge's center. (Where the edge's center is an equidistant point between source node and target node.)
• Space driven means that those edge paths should be preferred that are evenly distributed over the available space.

Parameters:

csr - Ranges from 0.0 to 1.0; higher values give more emphasis to edge paths closer to an edge's center. The default is an equal weighting of center driven and space driven strategy, i.e., csr equals 0.5.

getCenterToSpaceRatio

public double getCenterToSpaceRatio()

Returns the currently set ratio between the two complementary weighting strategies center driven and space driven.

See Also:

setCenterToSpaceRatio(double)

setRoutingStyle

public void setRoutingStyle(byte style)

Sets the preferred routing style for the edges to be routed. The default setting is STYLE_PREFERMIDDLE.

Parameters:

style - One of STYLE_ADHOC, STYLE_SHORTPATH, and STYLE_PREFERMIDDLE.

getRoutingStyle

public byte getRoutingStyle()

Returns the currently set routing style.

See Also:

setRoutingStyle(byte)

setBadOrthogonal

public void setBadOrthogonal(boolean value)

Determines the way that edges which cannot be routed should be drawn. If set, edge paths are drawn in an orthogonal fashion. Otherwise the edge path is drawn as a straight line.

Default setting is true.

getBadOrthogonal

public boolean getBadOrthogonal()

Returns whether bad edges should be drawn in an orthogonal fashion.

See Also:

setBadOrthogonal(boolean)

setCustomBorderCapacityEnabled

public void setCustomBorderCapacityEnabled(boolean value)

Whether or not a custom value for the capacity of the routing border around the graph's bounding box should be applied.

Default setting is false.

See Also:

setCustomBorderCapacity(int)

getCustomBorderCapacityEnabled

public boolean getCustomBorderCapacityEnabled()

Returns whether a custom value for the capacity of the routing border is used.

See Also:

setCustomBorderCapacityEnabled(boolean), setCustomBorderCapacity(int)

setCustomBorderCapacity

public void setCustomBorderCapacity(int value)

Determines the custom value for the capacity of the routing border around the graph's bounding box. The routing border means the space left of the leftmost node, right of the rightmost node, above the topmost node, and below the bottommost node. By default this value is set to 5, i.e., the routing border accommodates up to 5 parallel edge paths left of the leftmost node, right of the rightmost node, etc.

getCustomBorderCapacity

public int getCustomBorderCapacity()

Returns the currently set custom value for the capacity of the routing border around the graph's bounding box.

See Also:

setCustomBorderCapacity(int)

setInnerPortsEnabled

public void setInnerPortsEnabled(boolean value)

Whether edge ports (that do not have a strong port constraint set) should lie inside the node's bounding box or on the node's border. More specifically, "inside" means on the node's meridian for edges connecting to the left and right, and on the node's equator for edges connecting to the upper and lower side.

Default setting is false.

isInnerPortsEnabled

public boolean isInnerPortsEnabled()

Returns whether edge ports (that do not have a strong port constraint set) should lie inside the node's bounding box or on the node's border.

See Also:

setInnerPortsEnabled(boolean)