y.layout.orthogonal
Class DirectedOrthogonalLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.orthogonal.DirectedOrthogonalLayouter

All Implemented Interfaces:

Layouter

public class DirectedOrthogonalLayouter
extends CanonicMultiStageLayouter

This layout algorithm arranges directed graphs in an orthogonal fashion.

Layout Style

This layout algorithm arranges the elements of a given graph such that each edge is drawn as an alternating sequence of horizontal and vertical segments. Furthermore, all directed edges point to the main layout orientation. Edges that connect to the same node can also be routed in a bus-like structure.

The layout algorithm is well suited for small and medium-sized sparse graphs and produces drawings with no overlapping nodes, few crossings and few bends. Application domains of directed orthogonal drawings include, for example, software engineering, database schema and system management.

Sample output of DirectedOrthogonalLayouter with default settings. Marked edges are considered as directed and the layout orientation is top-to-bottom.

Sample output of DirectedOrthogonalLayouter with edge grouping. All edges are considered directed and the layout orientation is left-to-right.

Concept

The directed orthogonal layout algorithm is based on the topology-shape-metrics approach and runs in three phases:

Planarization phase

The graph is drawn on the plane without edge crossings by replacing edge crossings with dummy nodes, i.e. a planar embedding is computed.

Orthogonalization phase

The bends and the angles are computed.

Compaction phase

The coordinates for the nodes and edges are determined.

Each of the phases has to consider the edge direction.

Features

The layout algorithm is able to handle both directed and undirected edges. All directed edges are routed such that they point to the main layout orientation. They should be marked by means of a DataProvider registered with key DIRECTED_EDGE_DPKEY.

Edges can be grouped so that they share common segments at the beginning or end of their routes. Although a graph may contain source and target grouped edges, an edge can only be part of either a source or a target group. Edge groups are specified using DataProviders that provide the same ID object for all edges of the same group. Those DataProviders are registered with the graph with key PortConstraintKeys.SOURCE_GROUPID_KEY for source groups or key PortConstraintKeys.TARGET_GROUPID_KEY for target groups.

EdgeLayoutDescriptor instances can be used for specifying individual information (e.g. minimum lengths) for each edge in the graph. The descriptors are bound to the graph using a DataProvider registered with key EDGE_LAYOUT_DESCRIPTOR_DPKEY. If there is no descriptor assigned to some edges, the default descriptor will be used.

DirectedOrthogonalLayouter is able to consider edge label data when arranging a graph. This means that the layout algorithm will determine the positions of the nodes and edges such that the edge labels do not overlap with the other elements. Integrated edge labeling can be activated using method setIntegratedEdgeLabelingEnabled(boolean).

This layout algorithm is able to detect substructures in the input graph. If desired, it can handle and arrange them explicitly, making the structure easy to recognize. Supported substructures are trees, chains and cycles. See the corresponding style properties for details: setTreeStyle(byte), setChainStyle(byte) and setCycleStyle(byte). For the detection of substructures, it is optionally possible to consider node types, such that only nodes of the same user-defined type can form a substructure.

Field Summary

static byte	CHAIN_STYLE_NONE A chain layout style that defines that chains should not be handled specifically.
static byte	CHAIN_STYLE_STRAIGHT A chain layout style that defines that chains are arranged in a straight fashion.
static byte	CHAIN_STYLE_WRAPPED_WITH_BENDS_AT_TURNS A chain layout style that defines that chains are line/column wrapped such that bends of the chain edges form the turns/corners of the chain arrangement.
static byte	CHAIN_STYLE_WRAPPED_WITH_NODES_AT_TURNS A chain layout style that defines that chains are line/column-wrapped such that nodes form the turns/corners of the chain arrangement.
static byte	CYCLE_STYLE_CIRCULAR_WITH_BENDS_AT_CORNERS A cycle layout style that defines that cycle structures are arranged in a circular fashion such that bends of cycle edges form the corners of the circular layout.
static byte	CYCLE_STYLE_CIRCULAR_WITH_NODES_AT_CORNERS A cycle layout style that defines that cycle structures are arranged in a circular fashion such that nodes form the corners of the circular layout.
static byte	CYCLE_STYLE_NONE A cycle layout style that defines that cycles should not be handled specifically.
static java.lang.Object	DIRECTED_EDGE_DPKEY A DataProvider key for marking edges which should be routed such that they point to the main layout orientation The main layout orientation can be set using method CanonicMultiStageLayouter.setLayoutOrientation(byte).
static java.lang.Object	EDGE_BEND_COST_DPKEY A DataProvider key for providing bend costs for each edge The layout algorithm considers the specified costs during the bend minimization phase.
static java.lang.Object	EDGE_CROSSING_COST_DPKEY A DataProvider key for providing crossing costs for each edge The layout algorithm considers the specified costs during the crossing minimization phase.
static java.lang.Object	EDGE_DIRECTEDNESS_DPKEY A DataProvider key for specifying the directedness of edges for the detection of substructures The edge directedness is considered for the detection of substructures in the input graph i.e., trees, chains and cycles.
static java.lang.Object	EDGE_LAYOUT_DESCRIPTOR_DPKEY A DataProvider key for providing layout information for each edge If no edge layout descriptor is mapped to an edge, the default edge layout descriptor will be used.
static byte	ORIENTATION_AUTO_DETECTION Orientation specifier that defines that the layout orientation of substructures is chosen automatically.
static byte	ORIENTATION_BOTTOM_TO_TOP Orientation specifier that defines that the layout orientation of substructures is bottom to top.
static byte	ORIENTATION_LEFT_TO_RIGHT Orientation specifier that defines that the layout orientation of substructures is left to right.
static byte	ORIENTATION_RIGHT_TO_LEFT Orientation specifier that defines that the layout orientation of substructures is right to left.
static byte	ORIENTATION_TOP_TO_BOTTOM Orientation specifier that defines that the layout orientation of substructures is top to bottom.
static byte	TREE_STYLE_ASPECT_RATIO_TREE A tree layout style that yields tree layouts with an aspect ratio close to 1:1 that are generated by ARNodePlacer.
static byte	TREE_STYLE_COMPACT A tree layout style that aims to create maximally compact layouts for the subtrees by using the CompactNodePlacer for the tree layout algorithm.
static byte	TREE_STYLE_DEFAULT A tree layout style that arranges subtrees in a layered tree fashion with grouped edge routes, generated by a DefaultNodePlacer with routing style DefaultNodePlacer.ROUTING_FORK and alignment setting DefaultNodePlacer.ALIGNMENT_CENTER.
static byte	TREE_STYLE_INTEGRATED A tree layout style that arranges subtrees in a layered tree fashion with grouped edge routes and integrates the tree elements into the orthogonal layout framework.
static byte	TREE_STYLE_NONE A tree layout style that defines that subtrees should not be handled specifically.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

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

Method Summary

protected boolean	canLayoutCore(LayoutGraph graph) Accepts general graphs without exceptions.
protected EdgeLayoutDescriptor	createEdgeLayoutDescriptor() Returns a new EdgeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the edges of the graph.
void	doLayout(LayoutGraph graph) Calculates a directed orthogonal layout for the given graph taking the specified layout orientation into consideration.
protected void	doLayoutCore(LayoutGraph graph) Calculates a directed orthogonal layout for the given graph.
int	getChainSize() Returns the minimum size (number of nodes) a chain needs to have to be detected and handled as a chain substructure.
byte	getChainStyle() Returns the chain layout style that defines how chain substructures are arranged.
int	getCycleSize() Returns the minimum size (number of nodes) a cycle needs to have to be detected and explicitly handled as a cycle substructure.
byte	getCycleStyle() Returns the cycle layout style that defines how cycle substructures are arranged.
EdgeLayoutDescriptor	getEdgeLayoutDescriptor() Returns the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.
int	getGrid() Returns the equidistant spacing between the horizontal and vertical grid lines.
long	getMaximumDuration() Returns the preferred time limit in milliseconds.
byte	getTreeOrientation() Returns the desired orientation for subtree layouts.
int	getTreeSize() Returns the minimum size (number of nodes) a subtree needs to have to be detected and explicitly handled as a tree substructure.
byte	getTreeStyle() Returns the tree layout style that defines the basic arrangement style for subtrees.
boolean	getUseSketchDrawing() Returns whether or not the existing drawing should be used as a sketch for the resulting orthogonal layout.
boolean	isAlignDegreeOneNodesEnabled() Returns whether or not degree-one nodes that have the same neighbor should be aligned.
boolean	isConsiderNodeLabelsEnabled() Returns whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.
boolean	isIntegratedEdgeLabelingEnabled() Returns whether or not the layout algorithm preserves space and places edge labels.
boolean	isParallelRoutesPreferenceEnabled() Returns whether or not parallel routes for parallel edges (multi-edges) are preferred over independent routes.
boolean	isPerceivedBendsOptimizationEnabled() Returns whether or not the number of perceived bends will be minimized.
boolean	isUsePostprocessing() Returns whether or not an additional postprocessing step that improves compactness and reduces the number of bends should be applied.
void	setAlignDegreeOneNodesEnabled(boolean alignDegreeOneNodesEnabled) Specifies whether or not degree-one nodes that have the same neighbor should be aligned.
void	setChainSize(int chainSize) Specifies the minimum size (number of nodes) a chain needs to have to be detected and handled as a chain substructure.
void	setChainStyle(byte chainStyle) Specifies the chain layout style that defines how chain substructures are arranged.
void	setComponentLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.
void	setConsiderNodeLabelsEnabled(boolean enabled) Specifies whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.
void	setCycleSize(int cycleSize) Specifies the minimum size (number of nodes) a cycle needs to have to be detected and explicitly handled as a cycle substructure.
void	setCycleStyle(byte cycleStyle) Specifies the cycle layout style that defines how cycle substructures are arranged.
void	setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor) Specifies the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.
void	setGrid(int grid) Specifies the equidistant spacing between the horizontal and vertical grid lines.
void	setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled) Specifies whether or not the LayoutStage used for hiding group nodes is activated.
void	setIntegratedEdgeLabelingEnabled(boolean enabled) Specifies whether or not the layout algorithm preserves space and places edge labels.
void	setMaximumDuration(long maximumDuration) Specifies the preferred time limit in milliseconds.
void	setParallelRoutesPreferenceEnabled(boolean parallelRoutesPreferenceEnabled) Specifies whether or not parallel routes for parallel edges (multi-edges) are preferred over independent routes.
void	setPerceivedBendsOptimizationEnabled(boolean perceivedBendsOptimizationEnabled) Specifies whether or not the number of perceived bends will be minimized.
void	setTreeOrientation(byte treeOrientation) Specifies the desired orientation for subtree layouts.
void	setTreeSize(int treeSize) Specifies the minimum size (number of nodes) a subtree needs to have to be detected and explicitly handled as a tree substructure.
void	setTreeStyle(byte treeStyle) Specifies the tree layout style that defines the basic arrangement style for subtrees.
void	setUsePostprocessing(boolean usePostprocessing) Specifies whether or not an additional postprocessing step that improves compactness and reduces the number of bends should be applied.
void	setUseSketchDrawing(boolean value) Specifies whether or not the existing drawing should be used as a sketch for the resulting orthogonal layout.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setGroupNodeHider, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setOrientationLayouterEnabled, setParallelEdgeLayouter, setParallelEdgeLayouterEnabled, setSelfLoopLayouter, setSelfLoopLayouterEnabled, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Field Detail

EDGE_LAYOUT_DESCRIPTOR_DPKEY

public static final java.lang.Object EDGE_LAYOUT_DESCRIPTOR_DPKEY

A DataProvider key for providing layout information for each edge

If no edge layout descriptor is mapped to an edge, the default edge layout descriptor will be used.

Different settings will affect the routing of the edges during the layout.

EDGE_DIRECTEDNESS_DPKEY

public static final java.lang.Object EDGE_DIRECTEDNESS_DPKEY

A DataProvider key for specifying the directedness of edges for the detection of substructures

The edge directedness is considered for the detection of substructures in the input graph i.e., trees, chains and cycles. A substructure is only identified as such if all edges are either undirected or consistently directed with respect to the specified directedness.

• A directedness value of 1 indicates that the edge is considered to be directed from source to target.
• A directedness value of -1 indicates that the edge is considered to be directed from target to source.
• A directedness value of 0 indicates that the edge is considered to be undirected.

If no DataProvider is registered with this key, all edges are treated as undirected.

This key should not be confused with DIRECTED_EDGE_DPKEY. The latter one marks edges that are directed orthogonal and shall point in the specified layout orientation. On the other hand, this key is only responsible for the specification of the directedness with respect to the substructure detection.

EDGE_CROSSING_COST_DPKEY

public static final java.lang.Object EDGE_CROSSING_COST_DPKEY

A DataProvider key for providing crossing costs for each edge

The layout algorithm considers the specified costs during the crossing minimization phase. Edges with lower costs are more likely to have crossings. If no individual costs are defined, each crossing has a cost of 1.

The algorithm uses a heuristic approach for crossing minimization and, thus, doesn't guarantee an optimal solution.

Avoid using very large cost values. Due to the fact that costs need to be multiplied and summed up, this might lead to overflows and undesired results.

EDGE_BEND_COST_DPKEY

public static final java.lang.Object EDGE_BEND_COST_DPKEY

A DataProvider key for providing bend costs for each edge

The layout algorithm considers the specified costs during the bend minimization phase. Edges with lower costs are more likely to have bends. If no individual costs are defined, each bend has a cost of 1.

The algorithm uses a heuristic approach for bend minimization and, thus, doesn't guarantee an optimal solution.

Avoid using very large cost values. Due to the fact that costs need to be multiplied and summed up, this might lead to overflows and undesired results.

DIRECTED_EDGE_DPKEY

public static final java.lang.Object DIRECTED_EDGE_DPKEY

A DataProvider key for marking edges which should be routed such that they point to the main layout orientation

The main layout orientation can be set using method CanonicMultiStageLayouter.setLayoutOrientation(byte).

TREE_STYLE_NONE

public static final byte TREE_STYLE_NONE

A tree layout style that defines that subtrees should not be handled specifically.

Subtrees are not detected and will be arranged without specific emphasis of the tree structure.

See Also:

setTreeStyle(byte), Constant Field Values

Sample Graph:

Tree style TREE_STYLE_NONE

TREE_STYLE_DEFAULT

public static final byte TREE_STYLE_DEFAULT

A tree layout style that arranges subtrees in a layered tree fashion with grouped edge routes, generated by a DefaultNodePlacer with routing style DefaultNodePlacer.ROUTING_FORK and alignment setting DefaultNodePlacer.ALIGNMENT_CENTER.

Child nodes sharing the same parent node are placed next to each other above/below the root (vertical orientation) or above each other left/right of the root (horizontal orientation).

In contrast to TREE_STYLE_INTEGRATED this style produces more compact layout results. However, the overall layout may be less homogeneous because the subtrees are separately arranged by a dedicated tree layout algorithm which does e.g., not consider the specified grid.

See Also:

setTreeStyle(byte), Constant Field Values

Sample Graph:

Tree style TREE_STYLE_DEFAULT

TREE_STYLE_INTEGRATED

public static final byte TREE_STYLE_INTEGRATED

A tree layout style that arranges subtrees in a layered tree fashion with grouped edge routes and integrates the tree elements into the orthogonal layout framework.

Child nodes sharing the same parent node are placed next to each other above/below the root (vertical orientation) or above each other left/right of the root (horizontal orientation).

In contrast to TREE_STYLE_DEFAULT, the subtree elements are handled by the orthogonal layout framework internally. This makes the final layout more homogeneous, but potentially less compact. Furthermore, the grid will be correctly obeyed also for tree nodes.

See Also:

setTreeStyle(byte), Constant Field Values

Sample Graph:

Tree style TREE_STYLE_INTEGRATED

TREE_STYLE_COMPACT

public static final byte TREE_STYLE_COMPACT

A tree layout style that aims to create maximally compact layouts for the subtrees by using the CompactNodePlacer for the tree layout algorithm.

The algorithm applied to the subtrees tries to combine different placement strategies such that the overall area required by subtrees is small. This means that the style of different tree structures can vary within the same layout.

See Also:

setTreeStyle(byte), Constant Field Values

Sample Graph:

Tree style TREE_STYLE_COMPACT

TREE_STYLE_ASPECT_RATIO_TREE

public static final byte TREE_STYLE_ASPECT_RATIO_TREE

A tree layout style that yields tree layouts with an aspect ratio close to 1:1 that are generated by ARNodePlacer.

To achieve the aspect ratio, tree child nodes are organized in as much rows/columns as needed. Edges are routed orthogonally along the rows/columns. The parent node of the children is placed in a corner besides the child nodes depending on the tree layout orientation, e.g., left above the child nodes for top-to-bottom orientation.

See Also:

setTreeStyle(byte), Constant Field Values

Sample Graph:

Tree style TREE_STYLE_ASPECT_RATIO_TREE

ORIENTATION_TOP_TO_BOTTOM

public static final byte ORIENTATION_TOP_TO_BOTTOM

Orientation specifier that defines that the layout orientation of substructures is top to bottom.

See Also:

setTreeOrientation(byte), Constant Field Values

ORIENTATION_BOTTOM_TO_TOP

public static final byte ORIENTATION_BOTTOM_TO_TOP

Orientation specifier that defines that the layout orientation of substructures is bottom to top.

See Also:

setTreeOrientation(byte), Constant Field Values

ORIENTATION_LEFT_TO_RIGHT

public static final byte ORIENTATION_LEFT_TO_RIGHT

Orientation specifier that defines that the layout orientation of substructures is left to right.

See Also:

setTreeOrientation(byte), Constant Field Values

ORIENTATION_RIGHT_TO_LEFT

public static final byte ORIENTATION_RIGHT_TO_LEFT

Orientation specifier that defines that the layout orientation of substructures is right to left.

See Also:

setTreeOrientation(byte), Constant Field Values

ORIENTATION_AUTO_DETECTION

public static final byte ORIENTATION_AUTO_DETECTION

Orientation specifier that defines that the layout orientation of substructures is chosen automatically.

The automatic orientation selection is made e.g., by searching a side at the root node were no edge connects yet and inserting the substructure at that side using the respective orientation (for example, right side means left-to-right layout). It is recommended to use this setting if layouts should be maximally compact, because specifying a fixed orientation reduces the degree of freedom of the algorithm.

See Also:

setTreeOrientation(byte), Constant Field Values

CHAIN_STYLE_NONE

public static final byte CHAIN_STYLE_NONE

A chain layout style that defines that chains should not be handled specifically.

Chains in the input graph are not detected and will be arranged without specific emphasis of the chain structure.

See Also:

setChainStyle(byte), Constant Field Values

Sample Graph:

Chains are not handled explicitly (CHAIN_STYLE_NONE)

CHAIN_STYLE_STRAIGHT

public static final byte CHAIN_STYLE_STRAIGHT

A chain layout style that defines that chains are arranged in a straight fashion.

See Also:

setChainStyle(byte), Constant Field Values

Sample Graph:

Chain layout style CHAIN_STYLE_STRAIGHT

CHAIN_STYLE_WRAPPED_WITH_NODES_AT_TURNS

public static final byte CHAIN_STYLE_WRAPPED_WITH_NODES_AT_TURNS

A chain layout style that defines that chains are line/column-wrapped such that nodes form the turns/corners of the chain arrangement.

See Also:

setChainStyle(byte), Constant Field Values

Sample Graph:

Chain layout style CHAIN_STYLE_WRAPPED_WITH_NODES_AT_TURNS

CHAIN_STYLE_WRAPPED_WITH_BENDS_AT_TURNS

public static final byte CHAIN_STYLE_WRAPPED_WITH_BENDS_AT_TURNS

A chain layout style that defines that chains are line/column wrapped such that bends of the chain edges form the turns/corners of the chain arrangement.

See Also:

setChainStyle(byte), Constant Field Values

Sample Graph:

Chain layout style CHAIN_STYLE_WRAPPED_WITH_BENDS_AT_TURNS

CYCLE_STYLE_NONE

public static final byte CYCLE_STYLE_NONE

A cycle layout style that defines that cycles should not be handled specifically.

Cycles in the input graph are not detected and will be arranged without specific emphasis of the cycle structure.

See Also:

setCycleStyle(byte), Constant Field Values

Sample Graph:

Cycle not handled specifically (CYCLE_STYLE_NONE)

CYCLE_STYLE_CIRCULAR_WITH_NODES_AT_CORNERS

public static final byte CYCLE_STYLE_CIRCULAR_WITH_NODES_AT_CORNERS

A cycle layout style that defines that cycle structures are arranged in a circular fashion such that nodes form the corners of the circular layout.

See Also:

setCycleStyle(byte), Constant Field Values

Sample Graph:

Cycle layout style CYCLE_STYLE_CIRCULAR_WITH_NODES_AT_CORNERS

CYCLE_STYLE_CIRCULAR_WITH_BENDS_AT_CORNERS

public static final byte CYCLE_STYLE_CIRCULAR_WITH_BENDS_AT_CORNERS

A cycle layout style that defines that cycle structures are arranged in a circular fashion such that bends of cycle edges form the corners of the circular layout.

See Also:

setCycleStyle(byte), Constant Field Values

Sample Graph:

Cycle layout style CYCLE_STYLE_CIRCULAR_WITH_BENDS_AT_CORNERS

Constructor Detail

DirectedOrthogonalLayouter

public DirectedOrthogonalLayouter()

Creates a new DirectedOrthogonalLayouter instance with default settings.

Method Detail

getMaximumDuration

public long getMaximumDuration()

Returns the preferred time limit in milliseconds.

Depending on the specified value and the size of the input graph, the layout algorithm may automatically disable properties setUsePostprocessing(boolean) and setPerceivedBendsOptimizationEnabled(boolean). These properties improve the layout quality but also increase the runtime, especially for larger graphs. If the time limit is set to Long.MAX_VALUE, the layout algorithm runs unrestricted.

Values have to be greater or equal to 0.

Restricting the maximum duration may result in a lower layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Returns:

a non-negative value that specifies the preferred time limit

See Also:

setMaximumDuration(long)

setMaximumDuration

public void setMaximumDuration(long maximumDuration)

Specifies the preferred time limit in milliseconds.

Depending on the specified value and the size of the input graph, the layout algorithm may automatically disable properties setUsePostprocessing(boolean) and setPerceivedBendsOptimizationEnabled(boolean). These properties improve the layout quality but also increase the runtime, especially for larger graphs. If the time limit is set to Long.MAX_VALUE, the layout algorithm runs unrestricted.

Values have to be greater or equal to 0.

Restricting the maximum duration may result in a lower layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Default Value:

The default value is Long.MAX_VALUE. The layout algorithm runs unrestricted.

Parameters:

maximumDuration - a non-negative value that specifies the preferred time limit

Throws:

java.lang.IllegalArgumentException - if the maximum duration is negative

isAlignDegreeOneNodesEnabled

public boolean isAlignDegreeOneNodesEnabled()

Returns whether or not degree-one nodes that have the same neighbor should be aligned.

Returns:

true if the degree-one nodes are aligned, false otherwise

See Also:

setAlignDegreeOneNodesEnabled(boolean)

setAlignDegreeOneNodesEnabled

public void setAlignDegreeOneNodesEnabled(boolean alignDegreeOneNodesEnabled)

Specifies whether or not degree-one nodes that have the same neighbor should be aligned.

Default Value:

The default value is false. Degree-one nodes with the same neighbor are not aligned.

Parameters:

alignDegreeOneNodesEnabled - true if the degree-one nodes should be aligned, false otherwise

Sample Graphs:

Degree-one nodes are not aligned and layout orientation is left-to-right

Degree-one nodes are aligned and layout orientation is left-to-right

getTreeStyle

public byte getTreeStyle()

Returns the tree layout style that defines the basic arrangement style for subtrees.

If there are user-defined node types, a subtree contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

The identified subtrees do never contain parallel edges (multiple edges between the same endpoints).

Tree edges that connect to the subtree root node are never grouped together with non-tree edges connecting to the root node. Edge grouping constraints for these edges are ignored.

Returns:

one of the predefined tree styles

See Also:

setTreeStyle(byte)

setTreeStyle

public void setTreeStyle(byte treeStyle)

Specifies the tree layout style that defines the basic arrangement style for subtrees.

If there are user-defined node types, a subtree contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

The identified subtrees do never contain parallel edges (multiple edges between the same endpoints).

Tree edges that connect to the subtree root node are never grouped together with non-tree edges connecting to the root node. Edge grouping constraints for these edges are ignored.

Default Value:

The default value is TREE_STYLE_NONE. Subtrees are not arranged in a special way.

Parameters:

treeStyle - one of the predefined tree styles

Throws:

java.lang.IllegalArgumentException - if an unknown tree style is given

getTreeSize

public int getTreeSize()

Returns the minimum size (number of nodes) a subtree needs to have to be detected and explicitly handled as a tree substructure.

This setting has no effect if style TREE_STYLE_NONE is specified.

Returns:

the minimum number of nodes a tree needs to contain to be detected as a substructure

See Also:

setTreeSize(int)

setTreeSize

public void setTreeSize(int treeSize)

Specifies the minimum size (number of nodes) a subtree needs to have to be detected and explicitly handled as a tree substructure.

This setting has no effect if style TREE_STYLE_NONE is specified.

Default Value:

The default value is 3.

Parameters:

treeSize - the minimum number of nodes a tree needs to contain to be detected as a substructure

Throws:

java.lang.IllegalArgumentException - if the given minimum size is less than 3

getTreeOrientation

public byte getTreeOrientation()

Returns the desired orientation for subtree layouts.

This orientation affects only trees that are specifically handled as a tree substructure when the tree style is not TREE_STYLE_NONE. It is independent of the main layout orientation. For example, the main orientation could be top-to-bottom while the subtree orientation is left-to-right at the same time.

This property has no effect if TREE_STYLE_NONE is set as tree style.

Returns:

one of the four default layout orientations or ORIENTATION_AUTO_DETECTION

See Also:

setTreeOrientation(byte)

setTreeOrientation

public void setTreeOrientation(byte treeOrientation)

Specifies the desired orientation for subtree layouts.

This orientation affects only trees that are specifically handled as a tree substructure when the tree style is not TREE_STYLE_NONE. It is independent of the main layout orientation. For example, the main orientation could be top-to-bottom while the subtree orientation is left-to-right at the same time.

This property has no effect if TREE_STYLE_NONE is set as tree style.

Default Value:

The default value is ORIENTATION_AUTO_DETECTION. The tree orientation is determined automatically.

Parameters:

treeOrientation - one of the four default layout orientations or ORIENTATION_AUTO_DETECTION

Throws:

java.lang.IllegalArgumentException - if the given layout orientation is unknown

getChainStyle

public byte getChainStyle()

Returns the chain layout style that defines how chain substructures are arranged.

A chain is a simple edge path where the degree of the nodes is less than or equal to 2.

Property setChainSize(int) defines the minimum length a chain needs to have to be handled explicitly.

If there are user-defined node types, a chain substructure contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

If a chain is part of a handled subtree (tree style other than TREE_STYLE_NONE must be selected), then this chain will be arranged according to the tree layout style and not handled as a chain substructure.

Returns:

one of the predefined chain styles

See Also:

setChainStyle(byte)

setChainStyle

public void setChainStyle(byte chainStyle)

Specifies the chain layout style that defines how chain substructures are arranged.

A chain is a simple edge path where the degree of the nodes is less than or equal to 2.

Property setChainSize(int) defines the minimum length a chain needs to have to be handled explicitly.

If there are user-defined node types, a chain substructure contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

If a chain is part of a handled subtree (tree style other than TREE_STYLE_NONE must be selected), then this chain will be arranged according to the tree layout style and not handled as a chain substructure.

Default Value:

The default value is CHAIN_STYLE_NONE. Chains are not handled explicitly.

Parameters:

chainStyle - one of the predefined chain styles

Throws:

java.lang.IllegalArgumentException - if an unknown chain style is given

getChainSize

public int getChainSize()

Returns the minimum size (number of nodes) a chain needs to have to be detected and handled as a chain substructure.

This setting has no effect if style CHAIN_STYLE_NONE is specified.

Returns:

the minimum number of nodes a chain needs to contain to be detected as a substructure

See Also:

setChainSize(int)

setChainSize

public void setChainSize(int chainSize)

Specifies the minimum size (number of nodes) a chain needs to have to be detected and handled as a chain substructure.

This setting has no effect if style CHAIN_STYLE_NONE is specified.

Default Value:

The default value is 4.

Parameters:

chainSize - the minimum number of nodes a chain needs to contain to be detected as a substructure

Throws:

java.lang.IllegalArgumentException - if the given minimum size is less than 2

getCycleStyle

public byte getCycleStyle()

Returns the cycle layout style that defines how cycle substructures are arranged.

A cycle is a simple edge path where the first and last node are identical. The algorithm only considers cycles where at most one edge connects a cycle node with the rest of the graph (i.e. isolated cycles that are connected with one edge).

If there are user-defined node types, a cycle contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

Returns:

one of the predefined cycle styles

See Also:

setCycleStyle(byte)

setCycleStyle

public void setCycleStyle(byte cycleStyle)

Specifies the cycle layout style that defines how cycle substructures are arranged.

A cycle is a simple edge path where the first and last node are identical. The algorithm only considers cycles where at most one edge connects a cycle node with the rest of the graph (i.e. isolated cycles that are connected with one edge).

If there are user-defined node types, a cycle contains only nodes of the same type or only nodes without a type (i.e. null as type). This way, node types can be used to control which elements are allowed to form a substructure.

Default Value:

The default value is CYCLE_STYLE_NONE. Cycles are not handled explicitly.

Parameters:

cycleStyle - one of the predefined cycle styles

Throws:

java.lang.IllegalArgumentException - if an unknown cycle style is given

getCycleSize

public int getCycleSize()

Returns the minimum size (number of nodes) a cycle needs to have to be detected and explicitly handled as a cycle substructure.

This setting has no effect if style CYCLE_STYLE_NONE is specified.

Returns:

the minimum number of nodes a cycle needs to contain to be detected as a substructure

See Also:

setCycleSize(int)

setCycleSize

public void setCycleSize(int cycleSize)

Specifies the minimum size (number of nodes) a cycle needs to have to be detected and explicitly handled as a cycle substructure.

This setting has no effect if style CYCLE_STYLE_NONE is specified.

Default Value:

The default value is 4.

Parameters:

cycleSize - the minimum number of nodes a cycle needs to contain to be detected as a substructure

Throws:

java.lang.IllegalArgumentException - if the given minimum size is less than 4

isParallelRoutesPreferenceEnabled

public boolean isParallelRoutesPreferenceEnabled()

Returns whether or not parallel routes for parallel edges (multi-edges) are preferred over independent routes.

When enabled, the algorithm routes multi-edges (edges that connect the same pair of nodes) in parallel, i.e., these edges connect to the same side of the nodes and have the same or a similar path. Note that the path is not always exactly the same since the algorithm has to omit label-edge intersections if integrated labeling is enabled. If this setting is disabled, the edges are simply independent and might as well connect to different node sides and get very different paths.

A parallel routing is suitable for a lot of diagrams (especially larger ones) as it helps to better recognize multi-edge structures. However, there are scenarios where the routes of such edges might as well be independent. For small examples the structure can also be clear if the edges connect to other node sides, especially when they are in consecutive order around the node.

This property only affects edges that share the same source and target node.

This setting is ignored when CanonicMultiStageLayouter.isParallelEdgeLayouterEnabled() is enabled, that is, if parallel edges are not handled by this layout algorithm internally but by a specified stage.

Returns:

true if parallel edges are routed in parallel, false otherwise

See Also:

setParallelRoutesPreferenceEnabled(boolean)

setParallelRoutesPreferenceEnabled

public void setParallelRoutesPreferenceEnabled(boolean parallelRoutesPreferenceEnabled)

Specifies whether or not parallel routes for parallel edges (multi-edges) are preferred over independent routes.

When enabled, the algorithm routes multi-edges (edges that connect the same pair of nodes) in parallel, i.e., these edges connect to the same side of the nodes and have the same or a similar path. Note that the path is not always exactly the same since the algorithm has to omit label-edge intersections if integrated labeling is enabled. If this setting is disabled, the edges are simply independent and might as well connect to different node sides and get very different paths.

A parallel routing is suitable for a lot of diagrams (especially larger ones) as it helps to better recognize multi-edge structures. However, there are scenarios where the routes of such edges might as well be independent. For small examples the structure can also be clear if the edges connect to other node sides, especially when they are in consecutive order around the node.

This property only affects edges that share the same source and target node.

This setting is ignored when CanonicMultiStageLayouter.isParallelEdgeLayouterEnabled() is enabled, that is, if parallel edges are not handled by this layout algorithm internally but by a specified stage.

Default Value:

The default value is true. The algorithm tries to route parallel edges in parallel.

Parameters:

parallelRoutesPreferenceEnabled - true if parallel edges should be routed in parallel, false otherwise

Sample Graphs:

true

false

createEdgeLayoutDescriptor

protected EdgeLayoutDescriptor createEdgeLayoutDescriptor()

Returns a new EdgeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the edges of the graph.

This method may be overridden to create a new EdgeLayoutDescriptor instance with different configuration settings.

This method must not return null.

Returns:

a new EdgeLayoutDescriptor instance

getEdgeLayoutDescriptor

public EdgeLayoutDescriptor getEdgeLayoutDescriptor()

Returns the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.

By default, this method will return an EdgeLayoutDescriptor instance created with createEdgeLayoutDescriptor().

Returns:

the current EdgeLayoutDescriptor instance

See Also:

setEdgeLayoutDescriptor(EdgeLayoutDescriptor), OrthogonalGroupLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY

setEdgeLayoutDescriptor

public void setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor)

Specifies the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.

Default Value:

The default value is EdgeLayoutDescriptor

Parameters:

edgeLayoutDescriptor - the current EdgeLayoutDescriptor instance

Throws:

java.lang.IllegalArgumentException - if the EdgeLayoutDescriptor is null

See Also:

OrthogonalGroupLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY

setConsiderNodeLabelsEnabled

public void setConsiderNodeLabelsEnabled(boolean enabled)

Specifies whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) is set to true.

Setting this option may overwrite the currently set labeling algorithm. Hence, to combine this option with a generic edge labeling algorithm, the generic labeling has to be applied in an additional step after calculating the layout.

Default Value:

The default value is false. Node labels are not considered.

Parameters:

enabled - true if the layout algorithm should take the node labels into account, false otherwise

Sample Graphs:

Node labels are not taken into account and layout orientation is left-to-right

Node labels are not taken into account and layout orientation is left-to-right

isConsiderNodeLabelsEnabled

public boolean isConsiderNodeLabelsEnabled()

Returns whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) is set to true.

Setting this option may overwrite the currently set labeling algorithm. Hence, to combine this option with a generic edge labeling algorithm, the generic labeling has to be applied in an additional step after calculating the layout.

Returns:

true if the layout algorithm takes the node labels into account, false otherwise

Throws:

java.lang.IllegalStateException - if no properly configured LabelLayoutTranslator is registered even though this property was enabled earlier (can happen when manually specifying the labeling algorithm).

See Also:

setConsiderNodeLabelsEnabled(boolean)

isPerceivedBendsOptimizationEnabled

public boolean isPerceivedBendsOptimizationEnabled()

Returns whether or not the number of perceived bends will be minimized.

A perceived bend is not a real bend. A node with two incident edges induces a perceived bend if the edges are not placed on opposite sides. Enabling this option especially prevents a helical arrangement of chains of nodes.

Returns:

true if the number of perceived bends is minimized, false otherwise

See Also:

setPerceivedBendsOptimizationEnabled(boolean)

setPerceivedBendsOptimizationEnabled

public void setPerceivedBendsOptimizationEnabled(boolean perceivedBendsOptimizationEnabled)

Specifies whether or not the number of perceived bends will be minimized.

A perceived bend is not a real bend. A node with two incident edges induces a perceived bend if the edges are not placed on opposite sides. Enabling this option especially prevents a helical arrangement of chains of nodes.

Default Value:

The default value is false. The number of perceived bends will not be minimized.

Parameters:

perceivedBendsOptimizationEnabled - true if the number of perceived bends should be minimized, false otherwise

Sample Graphs:

Perceived bend minimization is disabled. Marked edges are considered undirected and layout orientation is top-to-bottom.

Perceived bend minimization is enabled. Marked edges are considered undirected and layout orientation is top-to-bottom.

setIntegratedEdgeLabelingEnabled

public void setIntegratedEdgeLabelingEnabled(boolean enabled)

Specifies whether or not the layout algorithm preserves space and places edge labels.

To define the desired placement for each label use PreferredPlacementDescriptor.

This method also assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) is set to true.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property CanonicMultiStageLayouter.setLabelLayouterEnabled(boolean). Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Edge labels are not placed.

Parameters:

enabled - true if integrated edge labeling should be enabled, false otherwise

Sample Graphs:

false

true

isIntegratedEdgeLabelingEnabled

public boolean isIntegratedEdgeLabelingEnabled()

Returns whether or not the layout algorithm preserves space and places edge labels.

To define the desired placement for each label use PreferredPlacementDescriptor.

This method also assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) is set to true.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property CanonicMultiStageLayouter.setLabelLayouterEnabled(boolean). Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Returns:

true if integrated edge labeling is enabled, false otherwise

Throws:

java.lang.IllegalStateException - if no properly configured LabelLayoutTranslator is registered even though integrated labeling was enabled earlier (can happen when manually specifying the labeling algorithm).

See Also:

setIntegratedEdgeLabelingEnabled(boolean)

getGrid

public int getGrid()

Returns the equidistant spacing between the horizontal and vertical grid lines.

Each node will be placed on a grid point. Edges will be routed such that their segments lie on grid lines, if possible.

Returns:

the grid spacing

See Also:

setGrid(int)

setGrid

public void setGrid(int grid)

Specifies the equidistant spacing between the horizontal and vertical grid lines.

Each node will be placed on a grid point. Edges will be routed such that their segments lie on grid lines, if possible.

The grid spacing has to be greater than 0.

Default Value:

The default value is 20.

Parameters:

grid - the grid spacing

Throws:

java.lang.IllegalArgumentException - if the grid spacing is negative or zero

Sample Graphs:

Grid spacing 20.

Grid spacing 5.

getUseSketchDrawing

public boolean getUseSketchDrawing()

Returns whether or not the existing drawing should be used as a sketch for the resulting orthogonal layout.

The layout algorithm will try to orthogonalize the given sketch without making too many modifications with respect to the original drawing.

If the algorithm uses the given sketch, it is no longer guaranteed that the directed edges point to the specified layout orientation.

Returns:

true if the existing drawing is used as a sketch, false otherwise

See Also:

setUseSketchDrawing(boolean)

setUseSketchDrawing

public void setUseSketchDrawing(boolean value)

Specifies whether or not the existing drawing should be used as a sketch for the resulting orthogonal layout.

The layout algorithm will try to orthogonalize the given sketch without making too many modifications with respect to the original drawing.

If the algorithm uses the given sketch, it is no longer guaranteed that the directed edges point to the specified layout orientation.

Default Value:

The default value is false. The existing drawing is not used as a sketch.

Parameters:

value - true if the existing drawing should be used as a sketch, false otherwise

Sample Graphs:

Initial drawing

Directed orthogonal layout when initial drawing is used as sketch and layout orientation is left-to-right

Directed orthogonal layout when initial drawing is not used as sketch and layout orientation is left-to-right

isUsePostprocessing

public boolean isUsePostprocessing()

Returns whether or not an additional postprocessing step that improves compactness and reduces the number of bends should be applied.

Returns:

true if the postprocessing step is applied, false otherwise

setUsePostprocessing

public void setUsePostprocessing(boolean usePostprocessing)

Specifies whether or not an additional postprocessing step that improves compactness and reduces the number of bends should be applied.

Default Value:

The default value is true. The compactness optimization step is applied.

Parameters:

usePostprocessing - true if the postprocessing step should be applied, false otherwise

Sample Graphs:

false

true

setComponentLayouterEnabled

public void setComponentLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.

Overrides:

setComponentLayouterEnabled in class CanonicMultiStageLayouter

DirectedOrthogonalLayouter can only handle single components. Disabling ComponentLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that arranges connected graph components is activated.

Parameters:

enabled - true if the stage that arranges the graph components is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isComponentLayouterEnabled(), CanonicMultiStageLayouter.setComponentLayouter(LayoutStage), ComponentLayouter

setGroupNodeHidingEnabled

public void setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled)

Specifies whether or not the LayoutStage used for hiding group nodes is activated.

Overrides:

setGroupNodeHidingEnabled in class CanonicMultiStageLayouter

DirectedOrthogonalLayouter cannot handle group nodes. Disabling GroupNodeHider will lead to errors during execution.

Default Value:

The default value is true. The stage responsible for hiding group nodes is activated.

Parameters:

groupNodeHidingEnabled - true if the stage used for hiding group nodes is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isGroupNodeHidingEnabled(), CanonicMultiStageLayouter.setGroupNodeHider(LayoutStage), GroupNodeHider

doLayout

public void doLayout(LayoutGraph graph)

Calculates a directed orthogonal layout for the given graph taking the specified layout orientation into consideration.

Specified by:

doLayout in interface Layouter

Overrides:

doLayout in class CanonicMultiStageLayouter

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:

CanonicMultiStageLayouter.appendStage(LayoutStage), CanonicMultiStageLayouter.prependStage(LayoutStage), CanonicMultiStageLayouter.doLayoutCore(LayoutGraph)

doLayoutCore

protected void doLayoutCore(LayoutGraph graph)

Calculates a directed orthogonal layout for the given graph.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

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

canLayoutCore

protected boolean canLayoutCore(LayoutGraph graph)

Accepts general graphs without exceptions.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true for all input graphs