com.yworks.yfiles.layout.router

Class OrthogonalPatternEdgeRouter

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.router.OrthogonalPatternEdgeRouter

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class OrthogonalPatternEdgeRouter
extends AbstractLayoutStage

OrthogonalPatternEdgeRouter routes edges orthogonally such that the resulting layout of the edges consists only of vertical and horizontal segments.

Note that the location and size of the nodes in a diagram remains unchanged.

The edge router will not try to find a perfect route from source to edge (unlike to what EdgeRouter does) but chooses the best path out of a set of fixed paths. The best path out of these possible paths is determined by its cost. The costs may be influenced by setting several cost factors. The distance that an edge will have from its source and target node is determined by MinimumDistance.

The edges whose paths have to be routed can be defined registering a IDataProvider with key DEFAULT_AFFECTED_EDGES_DPKEY.

Field Summary

Fields

Modifier and Type	Field and Description
static EdgeDpKey<Boolean>	DEFAULT_AFFECTED_EDGES_DPKEY A DataProvider key for determining which edges are routed.

Constructor Summary

Constructors

Constructor and Description
OrthogonalPatternEdgeRouter() Creates a new instance of OrthogonalPatternEdgeRouter with default settings.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Routes the edges of the given graph orthogonally.
protected double	calculateBendCost(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the costs for all bends of the given path.
protected double	calculateCost(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the edge cost of a possible edge path, in order to determine which path is the best, i.e., the cheapest.
protected double	calculateCrossingCosts(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the overall crossing costs of the given path, including edge crossings, edge overlaps and node crossings.
protected double	calculateEdgeLength(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the costs for the length of the given path.
protected double	calculatePortCandidateCost(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the costs for the chosen PortCandidates.
protected double	calculateSelfLoopSelfSidePenaltyCost(Edge edge, YList path, PortCandidate spc, PortCandidate tpc) Calculates the extra penalty that is added to the path's cost if the edge is a self-loop and source and target ports have the same direction.
protected void	checkNodeSize(LayoutGraph g) Checks the sizes of the nodes to be non-zero.
Object	getAffectedEdgesDpKey() Gets the key to register a IDataProvider which determines the edges that shall be routed by this algorithm.
double	getBendCost() Gets the costs for creating a bend on the edge's path.
double	getEdgeCrossingCost() Gets the costs for a crossing between two edges.
double	getEdgeOverlapCost() Gets the costs for overlapping edge paths.
YPoint	getGridOrigin() Gets the origin of the grid.
double	getGridSpacing() Gets the spacing of the grid on which edges are routed.
double	getMinimumDistance() Gets the minimum distance that an edge will maintain from its source and target node.
MonotonicPathRestriction	getMonotonicPathRestriction() Gets the monotonic path restriction that should be applied.
double	getNodeCrossingCost() Gets the costs for edges that cross nodes.
boolean	isGridRouting() Gets whether or not to route the edges on a grid.
void	setAffectedEdgesDpKey(Object value) Sets the key to register a IDataProvider which determines the edges that shall be routed by this algorithm.
void	setBendCost(double value) Sets the costs for creating a bend on the edge's path.
void	setEdgeCrossingCost(double value) Sets the costs for a crossing between two edges.
void	setEdgeOverlapCost(double value) Sets the costs for overlapping edge paths.
void	setGridOrigin(YPoint value) Sets the origin of the grid.
void	setGridRouting(boolean value) Sets whether or not to route the edges on a grid.
void	setGridSpacing(double value) Sets the spacing of the grid on which edges are routed.
void	setMinimumDistance(double value) Sets the minimum distance that an edge will maintain from its source and target node.
void	setMonotonicPathRestriction(MonotonicPathRestriction value) Sets the monotonic path restriction that should be applied.
void	setNodeCrossingCost(double value) Sets the costs for edges that cross nodes.

Methods inherited from class com.yworks.yfiles.layout.AbstractLayoutStage

applyLayoutCore, getCoreLayout, setCoreLayout

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_AFFECTED_EDGES_DPKEY

public static final EdgeDpKey<Boolean> DEFAULT_AFFECTED_EDGES_DPKEY

A DataProvider key for determining which edges are routed.

Constructor Detail

OrthogonalPatternEdgeRouter

public OrthogonalPatternEdgeRouter()

Creates a new instance of OrthogonalPatternEdgeRouter with default settings.

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Routes the edges of the given graph orthogonally.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Parameters:

graph - the input graph

calculateBendCost

protected double calculateBendCost(Edge edge,
                                   YList path,
                                   PortCandidate spc,
                                   PortCandidate tpc)

Calculates the costs for all bends of the given path.

This method is called by calculateCost(Edge, YList, PortCandidate, PortCandidate). The default implementation multiplies the number of bends with the according costs. It may be overridden to change the calculation of these costs.

Only bends are taken into account. The source and target ports, that are also part of the given path, are excluded.

Parameters:

edge - the edge for which the costs are calculated

path - the path of the given edge

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

the costs for the bends of this path

calculateCost

protected double calculateCost(Edge edge,
                               YList path,
                               PortCandidate spc,
                               PortCandidate tpc)

Calculates the edge cost of a possible edge path, in order to determine which path is the best, i.e., the cheapest.

This method is called by applyLayout(LayoutGraph) in order to decide which path is the best. The default implementation considers the edge length, the number of bends, edge crossings, PortCandidates and monotonic path restrictions. It may be overridden to apply a different set of costs or a different weighting.

Parameters:

edge - the edge whose costs to calculate

path - the edge's path

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

the sum of all costs for this edge's path

calculateCrossingCosts

protected double calculateCrossingCosts(Edge edge,
                                        YList path,
                                        PortCandidate spc,
                                        PortCandidate tpc)

Calculates the overall crossing costs of the given path, including edge crossings, edge overlaps and node crossings.

This method is called by calculateCost(Edge, YList, PortCandidate, PortCandidate). The default implementation will determine overlaps and crossings between edge segments and nodes and sum up the costs. It may be overridden to use a different combination of costs.

Parameters:

edge - the edge for which the costs are calculated

path - the path of the given edge

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

the overall crossing costs of the given path, including edge crossings, edge overlaps and node crossings

calculateEdgeLength

protected double calculateEdgeLength(Edge edge,
                                     YList path,
                                     PortCandidate spc,
                                     PortCandidate tpc)

Calculates the costs for the length of the given path.

This method is called by calculateCost(Edge, YList, PortCandidate, PortCandidate). The default implementation returns costs between 0 for short paths and 1 for long paths. Hence, it has relatively little impact on the overall costs. The method may be overridden to introduce a different weighting of the edge length.

Parameters:

edge - the edge for which the costs are calculated

path - the path of the given edge

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

the costs for the length of the given path

calculatePortCandidateCost

protected double calculatePortCandidateCost(Edge edge,
                                            YList path,
                                            PortCandidate spc,
                                            PortCandidate tpc)

Calculates the costs for the chosen PortCandidates.

This method is called by calculateCost(Edge, YList, PortCandidate, PortCandidate). The default implementation will return the candidates' costs. It may be overridden to change the calculation of these costs.

Parameters:

edge - the edge for which the costs are calculated

path - the path of the given edge

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

the costs for the PortCandidates

calculateSelfLoopSelfSidePenaltyCost

protected double calculateSelfLoopSelfSidePenaltyCost(Edge edge,
                                                      YList path,
                                                      PortCandidate spc,
                                                      PortCandidate tpc)

Calculates the extra penalty that is added to the path's cost if the edge is a self-loop and source and target ports have the same direction.

This method is called by calculateCost(Edge, YList, PortCandidate, PortCandidate). The default implementation adds costs for another bend if source and target ports share the same node side. In this manner, paths with different source and target directions are cheaper and thus preferred. The method may be overridden to change the calculation of this penalty.

Parameters:

edge - the edge for which the costs are calculated

path - the path of the given edge

spc - the source PortCandidate for this edge

tpc - the target PortCandidate for this edge

Returns:

an extra penalty for specific self-loop paths

checkNodeSize

protected void checkNodeSize(LayoutGraph g)

Checks the sizes of the nodes to be non-zero.

Parameters:

g - The graph to check.

getAffectedEdgesDpKey

public Object getAffectedEdgesDpKey()

Gets the key to register a IDataProvider which determines the edges that shall be routed by this algorithm.

Throws:

IllegalArgumentException - if the specified IDataProvider key is null

Default Value:

The default value is DEFAULT_AFFECTED_EDGES_DPKEY

Returns:

the key to register a IDataProvider which determines the edges to be routed

See Also:

setAffectedEdgesDpKey(Object)

getBendCost

public double getBendCost()

Gets the costs for creating a bend on the edge's path.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 1.

Returns:

the costs for edges crossing nodes

See Also:

setBendCost(double)

getEdgeCrossingCost

public double getEdgeCrossingCost()

Gets the costs for a crossing between two edges.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 5.

Returns:

the costs for an edge crossing

See Also:

setEdgeCrossingCost(double)

getEdgeOverlapCost

public double getEdgeOverlapCost()

Gets the costs for overlapping edge paths.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

In case this OrthogonalPatternEdgeRouter is used stand-alone, one can determine a higher cost to prevent edge overlaps.

By default this OrthogonalPatternEdgeRouter is used in conjunction with a OrthogonalSegmentDistributionStage. Hence, edge overlaps are desired and thus should not cause any costs.

Default Value:

The default value is 0.

Returns:

the costs for overlapping edge segments

See Also:

setEdgeOverlapCost(double)

getGridOrigin

public YPoint getGridOrigin()

Gets the origin of the grid.

Throws:

IllegalArgumentException - if the specified point is null

Grid routing has lower priority than the minimum distance. Thus, it is possible that edges are not routed on the grid if there is not enough space between two borders.

The spacing will only be considered if grid routing is enabled.

Default Value:

The default value is YPoint.ORIGIN

Returns:

the origin of the grid

See Also:

setGridRouting(boolean), setGridOrigin(YPoint)

getGridSpacing

public double getGridSpacing()

Gets the spacing of the grid on which edges are routed.

The spacing between two grid lines must be at least 2.

Throws:

IllegalArgumentException - if the specified grid spacing is less than 2

The spacing will only be considered if grid routing is enabled.

Default Value:

The default value is 10.0.

Returns:

the spacing between two grid lines

See Also:

setGridRouting(boolean), setGridSpacing(double)

getMinimumDistance

public double getMinimumDistance()

Gets the minimum distance that an edge will maintain from its source and target node.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.0.

Returns:

the minimum distance between the edge and its source and target node

See Also:

setMinimumDistance(double)

getMonotonicPathRestriction

public MonotonicPathRestriction getMonotonicPathRestriction()

Gets the monotonic path restriction that should be applied.

Throws:

IllegalArgumentException - if the specified path restriction is unknown

Default Value:

The default value is MonotonicPathRestriction.NONE

Returns:

one of the valid monotonic path restrictions

See Also:

setMonotonicPathRestriction(MonotonicPathRestriction)

getNodeCrossingCost

public double getNodeCrossingCost()

Gets the costs for edges that cross nodes.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 50.

Returns:

the costs for edges crossing nodes

See Also:

setNodeCrossingCost(double)

isGridRouting

public boolean isGridRouting()

Gets whether or not to route the edges on a grid.

The grid can be defined using methods GridOrigin and GridSpacing.

The edges' source and target ports are not reassigned if they have fixed coordinates. Therefore, the first and last segments of an edge might not be routed on the grid. Use weak PortConstraints or assign coordinates that already lie on the grid for these ports if grid routing is desired.

Default Value:

The default value is false. Edges are not routed on a grid.

Returns:

true if edges are routed on grid, false otherwise

See Also:

setGridOrigin(YPoint), setGridSpacing(double), setGridRouting(boolean)

setAffectedEdgesDpKey

public void setAffectedEdgesDpKey(Object value)

Sets the key to register a IDataProvider which determines the edges that shall be routed by this algorithm.

Throws:

IllegalArgumentException - if the specified IDataProvider key is null

Default Value:

The default value is DEFAULT_AFFECTED_EDGES_DPKEY

Parameters:

value - the key to register a IDataProvider which determines the edges to be routed

See Also:

getAffectedEdgesDpKey()

setBendCost

public void setBendCost(double value)

Sets the costs for creating a bend on the edge's path.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 1.

Parameters:

value - the costs for edges crossing nodes

See Also:

getBendCost()

setEdgeCrossingCost

public void setEdgeCrossingCost(double value)

Sets the costs for a crossing between two edges.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 5.

Parameters:

value - the costs for an edge crossing

See Also:

getEdgeCrossingCost()

setEdgeOverlapCost

public void setEdgeOverlapCost(double value)

Sets the costs for overlapping edge paths.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

In case this OrthogonalPatternEdgeRouter is used stand-alone, one can determine a higher cost to prevent edge overlaps.

By default this OrthogonalPatternEdgeRouter is used in conjunction with a OrthogonalSegmentDistributionStage. Hence, edge overlaps are desired and thus should not cause any costs.

Default Value:

The default value is 0.

Parameters:

value - the costs for overlapping edge segments

See Also:

getEdgeOverlapCost()

setGridOrigin

public void setGridOrigin(YPoint value)

Sets the origin of the grid.

Throws:

IllegalArgumentException - if the specified point is null

Grid routing has lower priority than the minimum distance. Thus, it is possible that edges are not routed on the grid if there is not enough space between two borders.

The spacing will only be considered if grid routing is enabled.

Default Value:

The default value is YPoint.ORIGIN

Parameters:

value - the origin of the grid

See Also:

setGridRouting(boolean), getGridOrigin()

setGridRouting

public void setGridRouting(boolean value)

Sets whether or not to route the edges on a grid.

The grid can be defined using methods GridOrigin and GridSpacing.

The edges' source and target ports are not reassigned if they have fixed coordinates. Therefore, the first and last segments of an edge might not be routed on the grid. Use weak PortConstraints or assign coordinates that already lie on the grid for these ports if grid routing is desired.

Default Value:

The default value is false. Edges are not routed on a grid.

Parameters:

value - true if edges are routed on grid, false otherwise

See Also:

setGridOrigin(YPoint), setGridSpacing(double), isGridRouting()

setGridSpacing

public void setGridSpacing(double value)

Sets the spacing of the grid on which edges are routed.

The spacing between two grid lines must be at least 2.

Throws:

IllegalArgumentException - if the specified grid spacing is less than 2

The spacing will only be considered if grid routing is enabled.

Default Value:

The default value is 10.0.

Parameters:

value - the spacing between two grid lines

See Also:

setGridRouting(boolean), getGridSpacing()

setMinimumDistance

public void setMinimumDistance(double value)

Sets the minimum distance that an edge will maintain from its source and target node.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.0.

Parameters:

value - the minimum distance between the edge and its source and target node

See Also:

getMinimumDistance()

setMonotonicPathRestriction

public void setMonotonicPathRestriction(MonotonicPathRestriction value)

Sets the monotonic path restriction that should be applied.

Throws:

IllegalArgumentException - if the specified path restriction is unknown

Default Value:

The default value is MonotonicPathRestriction.NONE

Parameters:

value - one of the valid monotonic path restrictions

See Also:

getMonotonicPathRestriction()

setNodeCrossingCost

public void setNodeCrossingCost(double value)

Sets the costs for edges that cross nodes.

These costs are used for finding the best path out of the predefined paths from which the router can choose.

The costs need to be non-negative.

Throws:

IllegalArgumentException - if the specified costs are negative

Default Value:

The default value is 50.

Parameters:

value - the costs for edges crossing nodes

See Also:

getNodeCrossingCost()