y.layout.router.polyline
Class BusDescriptor

java.lang.Object
  y.layout.router.polyline.BusDescriptor

public class BusDescriptor
extends java.lang.Object

A BusDescriptor defines settings for edges routed on a common bus by EdgeRouter.

Edges (except self-loops) mapped to the same BusDescriptor instance form a bus. The mapping is retrieved from a DataProvider registered with the input graph with key EdgeRouter.BUS_DESCRIPTOR_DPKEY. A bus consists of a set of backbone segments shared by multiple edges to which shorter segments that connect to the actual nodes are attached. This descriptor allows to specify settings about the bus, for example, the location of the bus may be user-specified - see setBusPoints(YPointPath).

With buses, the routing algorithm tries to produce routes where the edges share as much of their paths as possible. It yields long line segments (so-called backbone segments) where ideally all but the first and last segments of all edge paths are drawn on top of each other (forming the bus), with short connections branching off to the nodes (bus connections).

Edges that are fixed (i.e. are not marked for routing) may also belong to a bus. Then, the bus segments will be derived using the existing path of the fixed edges. This way, buses can be incrementally updated, e.g., when a new edge should be added to an existing bus structure. Carefully note that fixed edges must have a correct orthogonal path for this feature to work properly.

Routing result containing three different bus structures

Routing result with a user-specified bus assigned to all edges (single vertical segment on the left-hand side)

Self-loops (i.e., edges that start and end at the same node) are never included into a bus.

Intermediate routing points are not supported for edges associated with a bus using this descriptor.

See Also:

EdgeRouter.BUS_DESCRIPTOR_DPKEY

Constructor Summary

BusDescriptor()

Method Summary

YPointPath	getBusPoints() Returns the user-specified bus path that represents the backbone for edges associated with this bus.
YPointPath	getComputedBusPoints() Returns the point path that describes the bus computed by the EdgeRouter.
double	getMinimumBackboneSegmentLength() Returns the preferred minimum length of backbone segments.
boolean	isAutomaticEdgeGroupingEnabled() Returns whether or not bus edges ending at the same node are automatically grouped such that they share a common bus connection.
boolean	isMultipleBackboneSegmentsAllowed() Returns whether or not the algorithm may create buses that consist of multiple backbone segments.
void	setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGrouping) Specifies whether or not bus edges ending at the same node are automatically grouped such that they share a common bus connection.
void	setBusPoints(YPointPath busPoints) Specifies the user-specified bus path that represents the backbone for edges associated with this bus.
void	setMinimumBackboneSegmentLength(double minimumBackboneSegmentLength) Specifies the preferred minimum length of backbone segments.
void	setMultipleBackboneSegmentsAllowed(boolean multipleBackboneSegmentsAllowed) Specifies whether or not the algorithm may create buses that consist of multiple backbone segments.

Methods inherited from class java.lang.Object

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

Constructor Detail

BusDescriptor

public BusDescriptor()

Method Detail

getBusPoints

public YPointPath getBusPoints()

Returns the user-specified bus path that represents the backbone for edges associated with this bus.

If the user does not specify the bus path, the algorithm automatically detects a suitable bus path. Similar to an edge path, a bus path is specified by an instance of YPointPath.

The user-specified path has to be orthogonal.

Returns:

the user-specified bus path or null if the path is determined automatically

See Also:

setBusPoints(YPointPath)

setBusPoints

public void setBusPoints(YPointPath busPoints)

Specifies the user-specified bus path that represents the backbone for edges associated with this bus.

If the user does not specify the bus path, the algorithm automatically detects a suitable bus path. Similar to an edge path, a bus path is specified by an instance of YPointPath.

The user-specified path has to be orthogonal.

Default Value:

The default value is null. The algorithm automatically detects a suitable bus.

Parameters:

busPoints - the user-specified bus path or null if the path should be determined automatically

getComputedBusPoints

public YPointPath getComputedBusPoints()

Returns the point path that describes the bus computed by the EdgeRouter.

The computed path of a bus is always orthogonal and connected. The bus path represents the backbone of the edges associated with the bus and the edges use parts of the bus path in their own path.

Querying the computed bus points can be useful if the bus backbone should be explicitly visualized.

If the bus path was user-specified, the returned point path is equal to that returned by method getBusPoints().

Returns:

the point path that describes the computed bus

See Also:

setBusPoints(YPointPath)

getMinimumBackboneSegmentLength

public double getMinimumBackboneSegmentLength()

Returns the preferred minimum length of backbone segments.

This number defines the minimum length of backbone segments which are computed during the selection of backbone segments. Final backbone segments might actually be shorter because not the full segment is used by bus connections; such dead-ends are not drawn.

The minimum length is defined to be a value greater than or equal to 1.0.

The minimum length should be at least as large as the typical distance between nodes to avoid small backbone segments. It is reasonable to set this according to the dimension of the bounding box of the whole graph.

Returns:

the preferred minimum length of a backbone segment

See Also:

setMinimumBackboneSegmentLength(double)

setMinimumBackboneSegmentLength

public void setMinimumBackboneSegmentLength(double minimumBackboneSegmentLength)

Specifies the preferred minimum length of backbone segments.

This number defines the minimum length of backbone segments which are computed during the selection of backbone segments. Final backbone segments might actually be shorter because not the full segment is used by bus connections; such dead-ends are not drawn.

The minimum length is defined to be a value greater than or equal to 1.0.

The minimum length should be at least as large as the typical distance between nodes to avoid small backbone segments. It is reasonable to set this according to the dimension of the bounding box of the whole graph.

Default Value:

The default value is 100.0.

Parameters:

minimumBackboneSegmentLength - the preferred minimum length of a backbone segment

Throws:

java.lang.IllegalArgumentException - if the given minimum length is smaller than 1.0

Sample Graphs:

100.0 - a backbone segment fits in the middle

300.0 - no backbone segment fits in the middle as it must be at least have width 300.0

isMultipleBackboneSegmentsAllowed

public boolean isMultipleBackboneSegmentsAllowed()

Returns whether or not the algorithm may create buses that consist of multiple backbone segments.

For edges routed on a bus, a preferred outcome is that the part of the edge that is not on the bus is short and has few bends. Of course, for buses that may consist of multiple backbone segments (instead of just a single backbone) this is usually easier to achieve. Hence, if this option is enabled, the algorithm automatically may decide to use multiple backbone segments in order to produce more suitable results.

This option is only considered if the user does not specify a custom bus path.

Returns:

true if the algorithm may create buses that consist of multiple backbone segments, false otherwise

See Also:

setMultipleBackboneSegmentsAllowed(boolean), setBusPoints(YPointPath), setMinimumBackboneSegmentLength(double)

setMultipleBackboneSegmentsAllowed

public void setMultipleBackboneSegmentsAllowed(boolean multipleBackboneSegmentsAllowed)

Specifies whether or not the algorithm may create buses that consist of multiple backbone segments.

For edges routed on a bus, a preferred outcome is that the part of the edge that is not on the bus is short and has few bends. Of course, for buses that may consist of multiple backbone segments (instead of just a single backbone) this is usually easier to achieve. Hence, if this option is enabled, the algorithm automatically may decide to use multiple backbone segments in order to produce more suitable results.

This option is only considered if the user does not specify a custom bus path.

Default Value:

The default value is true. The algorithm may create buses that consist of multiple backbone segments.

Parameters:

multipleBackboneSegmentsAllowed - true if the algorithm may create buses that consist of multiple backbone segments, false otherwise

See Also:

setBusPoints(YPointPath), setMinimumBackboneSegmentLength(double)

Sample Graphs:

true - the bus consist of multiple backbone segments

false - the bus consist of a single backbone segment

isAutomaticEdgeGroupingEnabled

public boolean isAutomaticEdgeGroupingEnabled()

Returns whether or not bus edges ending at the same node are automatically grouped such that they share a common bus connection.

This setting affects the bus connections of edges that belong to the same bus and end/start at the same node. Manually defined edge groups are considered, too. See PortConstraintKeys.SOURCE_GROUPID_KEY and PortConstraintKeys.TARGET_GROUPID_KEY. There are generally three scenarios:

1. All edges share the same bus connections. Simply enable this property and define no other edge groupings.
2. Each edge is routed individually between the bus and the end node. Disable this property and define no other edge groupings.
3. A mixture of the first two scenarios. Define the desired edge groupings and they will be considered. For edges that have no grouping information, the value of this property is considered. This way multiple edges may share a bus connections while others use their individual routes.

Manual edge grouping definitions are always stronger than this setting.

Returns:

true if bus edges ending at the same node are automatically grouped, false otherwise

See Also:

setAutomaticEdgeGroupingEnabled(boolean), PortConstraintKeys.SOURCE_GROUPID_KEY, PortConstraintKeys.TARGET_GROUPID_KEY

setAutomaticEdgeGroupingEnabled

public void setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGrouping)

Specifies whether or not bus edges ending at the same node are automatically grouped such that they share a common bus connection.

This setting affects the bus connections of edges that belong to the same bus and end/start at the same node. Manually defined edge groups are considered, too. See PortConstraintKeys.SOURCE_GROUPID_KEY and PortConstraintKeys.TARGET_GROUPID_KEY. There are generally three scenarios:

1. All edges share the same bus connections. Simply enable this property and define no other edge groupings.
2. Each edge is routed individually between the bus and the end node. Disable this property and define no other edge groupings.
3. A mixture of the first two scenarios. Define the desired edge groupings and they will be considered. For edges that have no grouping information, the value of this property is considered. This way multiple edges may share a bus connections while others use their individual routes.

Manual edge grouping definitions are always stronger than this setting.

Default Value:

The default value is true. Edges ending at the same node are automatically grouped.

Parameters:

automaticEdgeGrouping - true if bus edges ending at the same node should automatically be grouped, false otherwise

See Also:

PortConstraintKeys.SOURCE_GROUPID_KEY, PortConstraintKeys.TARGET_GROUPID_KEY

Sample Graphs:

true - edges to the same node use the same bus connection

false and no other edge groupings - edges to the same node use individual bus connections