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 made 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	MONOTONIC_BOTH Constant that specifies monotonic path restrictions for edges.
static byte	MONOTONIC_HORIZONTAL Constant that specifies monotonic path restrictions for edges.
static byte	MONOTONIC_NONE Constant that specifies monotonic path restrictions for edges.
static byte	MONOTONIC_VERTICAL Constant that specifies monotonic path restrictions for edges.
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_BALANCED 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.
protected void	checkGroupNodeSize(GraphLayout layout, Object node) This method throws an IllegalArgumentException if the width/height of the given group node object is zero.
protected void	checkNodeSize(GraphLayout layout, Object node) This method throws an IllegalArgumentException if the width/height of the given node object is zero.
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 that is used 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	getMonotonicPathRestriction() Returns the specified kind of monotonic path restrictions.
byte	getRoutingStyle() Returns the currently set routing style.
Object	getSelectedEdgesDpKey() Returns the DataProvider key to mark edges as selected.
Object	getSelectedNodesDpKey() Returns the DataProvider key to mark nodes as selected.
byte	getSphereOfAction() Returns the currently set sphere of action specifier.
boolean	isConsiderNodeLabelsEnabled() Returns whether or not node labels are taken into account when calculating edge paths (thereby preventing possible edge/node label overlaps).
boolean	isEnforceMonotonicPathRestrictions() Returns whether monotonic path restrictions (set with setMonotonicPathRestriction(byte)) should be enforced.
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() Returns 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	setConsiderNodeLabelsEnabled(boolean enabled) Specifies whether or not to consider node labels when calculating edge paths (thereby preventing possible edge/node label overlaps).
void	setCoupledDistances(boolean coupled) Specifies whether or not the minimum distances should be coupled.
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) Specifies whether or not a custom value for the capacity of the routing border around the graph's bounding box should be applied.
void	setEnforceMonotonicPathRestrictions(boolean enforceMonotonicPathRestrictions) Whether or not monotonic path restrictions (set with setMonotonicPathRestriction(byte)) should be enforced.
void	setGridOrigin(int x, int y) Sets a grid point coordinate used when grid routing is enabled.
void	setGridRoutingEnabled(boolean enabled) Specifies whether or not to route edge segments on grid lines.
void	setGridSpacing(int spacing) Sets the grid spacing that is used when grid routing is enabled.
void	setInnerPortsEnabled(boolean value) Specifies 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) Specifies 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.
void	setMonotonicPathRestriction(byte monotonicPathRestriction) Specifies which kind of monotonic path restrictions should be applied.
void	setReroutingEnabled(boolean enabled) Specifies 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	setSelectedEdgesDpKey(Object key) Specifies the DataProvider key to mark edges as selected.
void	setSelectedNodesDpKey(Object key) Specifies the DataProvider key to mark nodes as selected.
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

MONOTONIC_NONE

public static final byte MONOTONIC_NONE

Constant that specifies monotonic path restrictions for edges. This constant specifies that there are no restrictions.

See Also:

setMonotonicPathRestriction(byte), Constant Field Values

MONOTONIC_VERTICAL

public static final byte MONOTONIC_VERTICAL

Constant that specifies monotonic path restrictions for edges. This constant specifies restrictions for the vertical direction, i.e., each vertical edge segment is directed from the source to the target. Furthermore, each edge path starts and ends with a vertical segment.

See Also:

setMonotonicPathRestriction(byte), Constant Field Values

MONOTONIC_HORIZONTAL

public static final byte MONOTONIC_HORIZONTAL

Constant that specifies monotonic path restrictions for edges. This constant specifies restrictions for the horizontal direction, i.e., each horizontal edge segment is directed from the source to the target. Furthermore, each edge path starts and ends with a horizontal segment.

See Also:

setMonotonicPathRestriction(byte), Constant Field Values

MONOTONIC_BOTH

public static final byte MONOTONIC_BOTH

Constant that specifies monotonic path restrictions for edges. This constant specifies restrictions for the horizontal and vertical direction, i.e., each horizontal as well as each vertical edge segment is directed from the source to the target.

See Also:

setMonotonicPathRestriction(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

STYLE_BALANCED

public static final byte STYLE_BALANCED

Routing style specifier. Similar to STYLE_PREFERMIDDLE for the two end segments and segments between bends of different directions. Segments between bends of the same direction (u-shaped turns) are drawn the short way. This style achieves a well-balanced routing and is used by default.

See Also:

setRoutingStyle(byte), Constant Field Values

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 getSelectedEdgesDpKey().

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 getSelectedNodesDpKey().

See Also:

Graph.addDataProvider(Object,DataProvider), setSphereOfAction(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

getSelectedNodesDpKey

public Object getSelectedNodesDpKey()

Returns the DataProvider key to mark nodes as selected.

By default, Layouter.SELECTED_NODES is used.

Returns:

the DataProvider key to mark nodes as selected.

See Also:

setSelectedNodesDpKey(Object)

setSelectedNodesDpKey

public void setSelectedNodesDpKey(Object key)

Specifies the DataProvider key to mark nodes as selected.

By default, Layouter.SELECTED_NODES is used.

Throws:

IllegalArgumentException - if the specified key is null.

Parameters:

key - the DataProvider key.

See Also:

getSelectedNodesDpKey()

getSelectedEdgesDpKey

public Object getSelectedEdgesDpKey()

Returns the DataProvider key to mark edges as selected.

By default, Layouter.SELECTED_EDGES is used.

Returns:

the DataProvider key to mark edges as selected.

See Also:

setSelectedEdgesDpKey(Object)

setSelectedEdgesDpKey

public void setSelectedEdgesDpKey(Object key)

Specifies the DataProvider key to mark edges as selected.

By default, Layouter.SELECTED_EDGES is used.

Throws:

IllegalArgumentException - if the specified key is null.

Parameters:

key - the DataProvider key.

See Also:

getSelectedEdgesDpKey()

setConsiderNodeLabelsEnabled

public void setConsiderNodeLabelsEnabled(boolean enabled)

Specifies whether or not to consider node labels when calculating edge paths (thereby preventing possible edge/node label overlaps).
The default is false.

Parameters:

enabled - whether to enable this feature

isConsiderNodeLabelsEnabled

public boolean isConsiderNodeLabelsEnabled()

Returns whether or not node labels are taken into account when calculating edge paths (thereby preventing possible edge/node label overlaps).
The default is false.

Returns:

whether this feature is enabled.

getMonotonicPathRestriction

public byte getMonotonicPathRestriction()

Returns the specified kind of monotonic path restrictions.

See Also:

setMonotonicPathRestriction(byte)

setMonotonicPathRestriction

public void setMonotonicPathRestriction(byte monotonicPathRestriction)

Specifies which kind of monotonic path restrictions should be applied. Possible values are MONOTONIC_NONE, MONOTONIC_VERTICAL, MONOTONIC_HORIZONTAL and MONOTONIC_BOTH.

Parameters:

monotonicPathRestriction - the monotonic path restriction.

isEnforceMonotonicPathRestrictions

public boolean isEnforceMonotonicPathRestrictions()

Returns whether monotonic path restrictions (set with setMonotonicPathRestriction(byte)) should be enforced.

See Also:

setEnforceMonotonicPathRestrictions(boolean)

setEnforceMonotonicPathRestrictions

public void setEnforceMonotonicPathRestrictions(boolean enforceMonotonicPathRestrictions)

Whether or not monotonic path restrictions (set with setMonotonicPathRestriction(byte)) should be enforced. Enabling this option guarantees monotonic edge paths even if this results in additional overlaps between edges and nodes.

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.

checkNodeSize

protected void checkNodeSize(GraphLayout layout,
                             Object node)
                      throws IllegalArgumentException

This method throws an IllegalArgumentException if the width/height of the given node object is zero. It is called by the doLayout(LayoutGraph) method for each node object in the input graph.

Throws:

IllegalArgumentException - thrown if the width/height of the node object is zero.

Parameters:

layout - a graph layout object.

node - the node object to test.

See Also:

checkGroupNodeSize(GraphLayout,Object)

checkGroupNodeSize

protected void checkGroupNodeSize(GraphLayout layout,
                                  Object node)
                           throws IllegalArgumentException

This method throws an IllegalArgumentException if the width/height of the given group node object is zero. It is called by the doLayout(LayoutGraph) method for each group node object in the input graph.

Throws:

IllegalArgumentException - thrown if the width/height of the group node object is zero.

Parameters:

layout - a graph layout object.

node - the group node object to test.

See Also:

checkNodeSize(GraphLayout,Object)

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)

Specifies 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()

Returns 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:

getSelectedEdgesDpKey(), getSelectedNodesDpKey()

getSphereOfAction

public byte getSphereOfAction()

Returns the currently set sphere of action specifier.

See Also:

setSphereOfAction(byte)

setGridRoutingEnabled

public void setGridRoutingEnabled(boolean enabled)

Specifies 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 that is used 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 that is used 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 4 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)

Specifies 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)

Specifies 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_BALANCED.

Parameters:

style - One of STYLE_BALANCED, 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)

Specifies 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)

Specifies 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)