y.layout.router
Class ChannelEdgeRouter

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

All Implemented Interfaces:

Layouter, LayoutStage

public class ChannelEdgeRouter
extends AbstractLayoutStage

This edge routing algorithm generates orthogonal routes for the edges of the graph.

Compared to the routing algorithms implemented by classes EdgeRouter and OrthogonalEdgeRouter, this implementation is usually faster but supports less constraints and, by default, may produce node-edge overlaps.

Layout Style

Edges are routed in an orthogonal fashion, i.e., edge paths consist only of vertical and horizontal segments.

During the routing process, the positions of the nodes are considered to be fixed and the routing algorithm will not modify their locations or their sizes in any way.

The edge routing algorithm can be applied wherever it is required to route the edges as orthogonal segments, while keeping the positions of the nodes in the diagram fixed. Some potential applications include electric circuit design, floor planning, UML class diagrams/inheritance diagrams and navigation maps.

Sample output of the orthogonal edge routing algorithm with default settings

Concept

This edge routing algorithm combines two strategic steps of edge routing and executes them one after the other. The first strategy is called path finder strategy and will route the edges, potentially with edge overlaps. The second strategy will then split overlapping edge segments inside their channels and distribute them according to the specific distribution strategy.

The default path finding strategy is OrthogonalPatternEdgeRouter. Alternatively, you can use ChannelEdgeRouter.OrthogonalShortestPathPathFinder. The default edge distribution strategy is OrthogonalSegmentDistributionStage.

Features

This class itself has no special routing options except from specifying the path finding and edge distribution strategy. Most of the features like minimum element distances, grid spacing and path restrictions have to be set on the used instances for the two routing steps.

For incremental edge routing, DataProvider key AFFECTED_EDGES has to be registered with the graph to mark all edges that should be routed by the algorithm. The routes of the other edges remain unchanged. If there is no such key registered, the algorithm routes all edges.

When exchanging only one of the strategies, make sure, that their algorithms will use the same (sub)set of graph objects. The strategies bound to this routing algorithm, by default, will use key AFFECTED_EDGES to determine the affected edges.

Nested Class Summary

static class

ChannelEdgeRouter.OrthogonalShortestPathPathFinder This routing algorithm is a special version of class OrthogonalEdgeRouter that can be used as a path finding strategy for the ChannelEdgeRouter.

Field Summary

static java.lang.Object	AFFECTED_EDGES A DataProvider key for marking the edges that should be routed.
static byte	ROUTING_POLICY_ALWAYS A routing policy that indicates that a new route is calculated in any case.
static byte	ROUTING_POLICY_PATH_AS_NEEDED A routing policy that indicates that based on the current path it is automatically determined whether an edge is routed, and if so, the edge gets a whole new path.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

ChannelEdgeRouter()
Creates a new ChannelEdgeRouter instance with default settings.

Method Summary

boolean	canLayout(LayoutGraph graph) Checks whether or not the given graph can be handled by this edge routing algorithm.
protected void	checkGroupNodeSize(GraphLayout layout, java.lang.Object node) Checks the given group node for zero or negative width/height.
protected void	checkNodeSize(GraphLayout layout, java.lang.Object node) Checks the given node for zero or negative width/height.
void	doLayout(LayoutGraph graph) Performs the orthogonal routing of the edges of the input graph.
Layouter	getEdgeDistributionStrategy() Returns the strategy for the edge distribution step.
Layouter	getPathFinderStrategy() Returns the strategy for the path finding step.
byte	getRoutingPolicy() Returns the routing policy indicating if the edges are unconditionally routed or if the existing routes determines whether a new path is necessary.
void	setEdgeDistributionStrategy(Layouter edgeDistributionStrategy) Specifies the strategy for the edge distribution step.
void	setPathFinderStrategy(Layouter pathFinderStrategy) Specifies the strategy for the path finding step.
void	setRoutingPolicy(byte routingPolicy) Specifies the routing policy indicating if the edges are unconditionally routed or if the existing routes determines whether a new path is necessary.

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

AFFECTED_EDGES

public static final java.lang.Object AFFECTED_EDGES

A DataProvider key for marking the edges that should be routed.

If this key is not registered with the graph, the algorithm will route all edges.

ROUTING_POLICY_ALWAYS

public static final byte ROUTING_POLICY_ALWAYS

A routing policy that indicates that a new route is calculated in any case.

The existing path of an edge is ignored and the routing algorithm unconditionally generates a whole new path.

See Also:

Constant Field Values

Sample Graphs:

Initial graph

The edges got a new path, ignoring the existing one

ROUTING_POLICY_PATH_AS_NEEDED

public static final byte ROUTING_POLICY_PATH_AS_NEEDED

A routing policy that indicates that based on the current path it is automatically determined whether an edge is routed, and if so, the edge gets a whole new path.

The automatic selection examines the existing, given path of an edge. Based on various criteria it heuristically determines whether or not it needs to be routed. For example, intersections with other elements or a routing style violation are clear indicators. A further criterion is when the port constraints/candidates are not properly satisfied. Edges deemed to be 'good' are not changed.

This policy is convenient for cases where it is not clear which edges the algorithm should route. For example, after a user interaction (moving a node, inserting new elements etc.), routing of edges might become necessary but depending on the action it can not definitely be said which edges need to be corrected.

See Also:

Constant Field Values

Sample Graphs:

Initial graph

The three edges were selected for routing and they got a completely new path

Constructor Detail

ChannelEdgeRouter

public ChannelEdgeRouter()

Creates a new ChannelEdgeRouter instance with default settings.

Method Detail

canLayout

public boolean canLayout(LayoutGraph graph)

Checks whether or not the given graph can be handled by this edge routing algorithm. This is always true unless the user specifies a core layout algorithm that cannot handle this graph or if the width/height of a node is zero.

Parameters:

graph - the input graph

Returns:

true if the input graph can be handled by this edge routing algorithm, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

Performs the orthogonal routing of the edges of the input graph.

The given graph will not be copied during the edge routing process and the result will be immediately applied to the input graph.

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)

checkNodeSize

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

Checks the given node for zero or negative width/height.

This method is called before the invocation of the core layout algorithm for each normal node of the input graph. It may be overridden in order to obtain a custom implementation of node-size check or to remove it entirely.

Parameters:

layout - the GraphLayout instance

node - the node object

Throws:

java.lang.IllegalArgumentException - if the width/height of the node object is zero or negative

See Also:

checkGroupNodeSize(GraphLayout, Object), canLayout(LayoutGraph), doLayout(LayoutGraph)

checkGroupNodeSize

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

Checks the given group node for zero or negative width/height.

This method is called by doLayout(LayoutGraph) for each group node of the input graph. It may be overridden in order to obtain a custom implementation of group-node-size check or to remove it entirely.

Parameters:

layout - the GraphLayout instance

node - the group node object

Throws:

java.lang.IllegalArgumentException - if the width/height of the group node object is zero or negative

See Also:

checkNodeSize(GraphLayout,Object)

setPathFinderStrategy

public void setPathFinderStrategy(Layouter pathFinderStrategy)

Specifies the strategy for the path finding step.

This step routes the edges and may produce edge overlaps which are later resolved in the edge distribution step.

When exchanging only one of the strategies, make sure, that their algorithms will use the same (sub)set of graph objects. The strategies bound to this routing algorithm, by default, will use key AFFECTED_EDGES to determine the affected edges.

Default Value:

The default value is OrthogonalPatternEdgeRouter

Parameters:

pathFinderStrategy - the path finding strategy that should be set

setEdgeDistributionStrategy

public void setEdgeDistributionStrategy(Layouter edgeDistributionStrategy)

Specifies the strategy for the edge distribution step.

This step distributes overlapping edge segments in their channel. The channel in which the segments can be distributed is defined by the surrounding graph elements.

When exchanging only one of the strategies, make sure, that their algorithms will use the same (sub)set of graph objects. The strategies bound to this routing algorithm, by default, will use key AFFECTED_EDGES to determine the affected edges.

Default Value:

The default value is OrthogonalSegmentDistributionStage

Parameters:

edgeDistributionStrategy - the distribution strategy to be set

getPathFinderStrategy

public Layouter getPathFinderStrategy()

Returns the strategy for the path finding step.

This step routes the edges and may produce edge overlaps which are later resolved in the edge distribution step.

When exchanging only one of the strategies, make sure, that their algorithms will use the same (sub)set of graph objects. The strategies bound to this routing algorithm, by default, will use key AFFECTED_EDGES to determine the affected edges.

Returns:

the path finder strategy

See Also:

setPathFinderStrategy(Layouter)

getEdgeDistributionStrategy

public Layouter getEdgeDistributionStrategy()

Returns the strategy for the edge distribution step.

This step distributes overlapping edge segments in their channel. The channel in which the segments can be distributed is defined by the surrounding graph elements.

When exchanging only one of the strategies, make sure, that their algorithms will use the same (sub)set of graph objects. The strategies bound to this routing algorithm, by default, will use key AFFECTED_EDGES to determine the affected edges.

Returns:

the edge distribution strategy

See Also:

setEdgeDistributionStrategy(Layouter)

getRoutingPolicy

public byte getRoutingPolicy()

Returns the routing policy indicating if the edges are unconditionally routed or if the existing routes determines whether a new path is necessary.

This routing algorithm does only support policies ROUTING_POLICY_ALWAYS and ROUTING_POLICY_PATH_AS_NEEDED. Only routing specific segments as needed is not supported.

Returns:

one of the two predefined routing policies

See Also:

setRoutingPolicy(byte)

setRoutingPolicy

public void setRoutingPolicy(byte routingPolicy)

Specifies the routing policy indicating if the edges are unconditionally routed or if the existing routes determines whether a new path is necessary.

This routing algorithm does only support policies ROUTING_POLICY_ALWAYS and ROUTING_POLICY_PATH_AS_NEEDED. Only routing specific segments as needed is not supported.

Default Value:

The default value is ROUTING_POLICY_ALWAYS. The edges are routed, ignoring the existing sketch.

Parameters:

routingPolicy - one of the two predefined routing policies

Throws:

java.lang.IllegalArgumentException - if an unknown routing policy is given