y.layout.partial
Class PartialLayouter

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.partial.PartialLayouter

All Implemented Interfaces:

Layouter, LayoutStage

public class PartialLayouter
extends AbstractLayoutStage

This class represents a partial layout algorithm which changes the coordinates for a given set of graph elements (called partial elements) only. The location and size of the remaining elements (called fixed elements) is not allowed to be changed.

Layout Style

This partial layout algorithm offers a kind of generic partial layout support for other existing layout algorithms. Hence, its layout style heavily depends on the selected core layout algorithm as well as the specified edge router or edge routing strategy.

The partial layout is suitable for applications where users may incrementally add new elements to an existing drawing. The added elements should be arranged so that they fit best possible into the given diagram without making any changes to the already existing layout. Hence, the so-called mental map of the existing drawing is preserved.

The input graph where marked nodes denote the partial elements that were incrementally added to the existing diagram.

The result of a partial layout run with component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE and with node alignment enabled.

Features

Similar to the layout style, the supported feature set mainly depends on the features supported by the specified core layout algorithm as well as the specified edge router or edge routing strategy. The internal step that places the components can handle group nodes and is able to consider minimum distance constraints and node labels.

Furthermore, the algorithm tries to place a subgraph component within the associated cell of the PartitionGrid. For this feature to work properly it is required that the values of the properties ColumnDescriptor.getOriginalPosition(), RowDescriptor.getOriginalPosition() ColumnDescriptor.getOriginalWidth() and RowDescriptor.getOriginalHeight() are correctly specified. Note that the algorithm does not guarantee that the calculated subgraph layout fits into the grid cell.

Concept

The layout algorithm tries to place the partial elements such that the resulting drawing (including the fixed elements) has a good quality with respect to common graph drawing aesthetics.

The layout algorithm handles each selected graph element as partial element. For this, it looks up the DataProvider keys PARTIAL_NODES_DPKEY and PARTIAL_EDGES_DPKEY. Partial node elements can be assigned to the so-called subgraph components. During the layout process each subgraph induced by the nodes of a component is first laid out using the specified core layout algorithm. Then, the different components are placed one-by-one onto the drawing area such that the number of overlaps among graph elements is small. The user can specify different objectives for finding 'good' positions for subgraph components (see setPositioningStrategy(byte)), e.g., SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER specifies that the component should be placed close to the barycenter of its graph neighbors and SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH specifies that the component should be placed close to its original position.

Method setComponentAssignmentStrategy(byte) allows to specify the strategy that assigns partial nodes to subgraph components. Possible values are COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING, COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED, COMPONENT_ASSIGNMENT_STRATEGY_SINGLE and COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. The last value allows to use a customized component assignment. Note that nodes of a component cannot be assigned to different group nodes.

Furthermore, the user can specify the edge routing strategy (see setEdgeRoutingStrategy(byte)) that is used for routing partial edges and edges between different subgraph components (so-called inter-edges). Possible values are EDGE_ROUTING_STRATEGY_ORGANIC, EDGE_ROUTING_STRATEGY_ORTHOGONAL, EDGE_ROUTING_STRATEGY_STRAIGHTLINE, EDGE_ROUTING_STRATEGY_OCTILINEAR and EDGE_ROUTING_STRATEGY_AUTOMATIC.

When a partial node should be placed inside a fixed group node, it is important that there is enough free space inside the group. Otherwise, there may be overlapping node elements.

Nested Class Summary

static class

PartialLayouter.StraightLineEdgeRouter Deprecated. Use class StraightLineEdgeRouter instead.

Field Summary

static java.lang.Object	COMPONENT_ASSIGNMENT_DPKEY A DataProvider key for defining custom subgraph components.
static byte	COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING A component assignment strategy where the subgraph components correspond to the clusters computed by a clustering algorithm based on edge betweenness centrality.
static byte	COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED A component assignment strategy where the subgraph components correspond to the connected components of the graph.
static byte	COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED A component assignment strategy where the subgraph components are defined by the user.
static byte	COMPONENT_ASSIGNMENT_STRATEGY_SINGLE A component assignment strategy that assigns each node to a separate subgraph component.
static java.lang.Object	DIRECTED_EDGES_DPKEY A DataProvider key for specifying the edges that should be considered to be directed.
static byte	EDGE_ROUTING_STRATEGY_AUTOMATIC Automatically chooses a suitable routing strategy by analyzing the existing edge routes.
static byte	EDGE_ROUTING_STRATEGY_OCTILINEAR A routing strategy that produces octilinear routes.
static byte	EDGE_ROUTING_STRATEGY_ORGANIC A routing strategy that produces organic routes for partial edges and inter-edges.
static byte	EDGE_ROUTING_STRATEGY_ORTHOGONAL A routing strategy that produces orthogonal routes.
static byte	EDGE_ROUTING_STRATEGY_STRAIGHTLINE A routing strategy that produces straight-line routes.
static byte	ORIENTATION_AUTO_DETECTION Layout orientation specifier where the orientation is automatically detected.
static byte	ORIENTATION_BOTTOM_TO_TOP Layout orientation specifier which defines that the main layout orientation is from bottom to top.
static byte	ORIENTATION_LEFT_TO_RIGHT Layout orientation specifier which defines that the main layout orientation is from left to right.
static byte	ORIENTATION_NONE Layout orientation specifier where the layout orientation is completely ignored.
static byte	ORIENTATION_RIGHT_TO_LEFT Layout orientation specifier which defines that the main layout orientation is from right to left.
static byte	ORIENTATION_TOP_TO_BOTTOM Layout orientation specifier which defines that the main layout orientation is from top to bottom.
static java.lang.Object	PARTIAL_EDGES_DPKEY A DataProvider key for marking partial edges.
static java.lang.Object	PARTIAL_NODES_DPKEY A DataProvider key for marking partial nodes.
static java.lang.String	ROUTE_EDGE_DPKEY A DataProvider key for obtaining the edges that should be routed by the edge router.
static byte	SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER A positioning strategy which tries to place each subgraph component close to the barycenter of its graph neighbors.
static byte	SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH A positioning strategy which tries to place each subgraph component close to its original position.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

PartialLayouter()
Creates a new instance of PartialLayouter.

PartialLayouter(Layouter subgraphLayouter)
Creates a new instance of PartialLayouter which uses the specified Layouter instance as the core layout algorithm.

Method Summary

boolean	canLayout(LayoutGraph graph) Delegates the call to the specified core layout algorithm.
protected void	configureEdgeRouter(Layouter edgeRouter) This method is called each time when edges are routed with an edge router.
void	doLayout(LayoutGraph graph) This method calculates the partial layout.
void	doPartialLayout(LayoutGraph graph) This method calculates the partial layout.
byte	getComponentAssignmentStrategy() Returns the strategy that assigns partial nodes to subgraph components.
Layouter	getCoreLayouter() Returns the Layouter instance that is applied to each subgraph component.
Layouter	getEdgeRouter() Returns the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).
byte	getEdgeRoutingStrategy() Returns the routing strategy that is used for partial edges and inter-edges.
byte	getLayoutOrientation() Returns the layout orientation that is considered during the placement of partial elements.
long	getMaximalDuration() Returns the preferred time limit (in milliseconds) for the layout algorithm.
int	getMinimalNodeDistance() Returns the minimum distance between two adjacent nodes.
byte	getPositioningStrategy() Returns the objective used for finding 'good' positions for subgraph components.
boolean	isConsiderNodeAlignment() Returns whether or not partial nodes should be aligned.
boolean	isFixedGroupResizingEnabled() Returns whether or not fixed (non-partial) group nodes may be resized.
boolean	isMirroringAllowed() Returns whether or not subgraph components are mirrored to improve the layout quality.
boolean	isMovingFixedElementsAllowed() Returns whether or not the algorithm may move fixed elements.
boolean	isOrientationOptimizationEnabled() Returns whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.
boolean	isPackComponentsEnabled() Returns whether or not a subgraph component may be placed within another subgraph component.
boolean	isRouteInterEdgesImmediatelyEnabled() Returns whether or not edges between different subgraph components should be routed immediately.
protected void	layoutSubgraph(LayoutGraph subGraph) This method is called during the layout process and calculates the layout for the given subgraph component using the specified core layout algorithm.
protected void	placeSubgraphs(LayoutGraph graph, NodeList[] subgraphComponents) This method is called during the layout process and places the subgraph components one-by-one onto the drawing area.
protected void	routeEdgesBetweenFixedElements(LayoutGraph graph, EdgeList partialEdges) This method is called during the layout process and routes all partial edges that connect two fixed elements.
protected void	routeInterEdges(LayoutGraph graph, EdgeList interEdges) This method is called during the layout process and routes all inter-edges.
void	setComponentAssignmentStrategy(byte strategy) Specifies the strategy that assigns partial nodes to subgraph components.
void	setConsiderNodeAlignment(boolean considerNodeAlignment) Specifies whether or not partial nodes should be aligned.
void	setCoreLayouter(Layouter layouter) Specifies the Layouter instance that is applied to each subgraph component.
void	setEdgeRouter(Layouter edgeRouter) Specifies the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).
void	setEdgeRoutingStrategy(byte strategy) Specifies the routing strategy that is used for partial edges and inter-edges.
void	setFixedGroupResizingEnabled(boolean fixedGroupResizingEnabled) Specifies whether or not fixed (non-partial) group nodes may be resized.
void	setLayoutOrientation(byte layoutOrientation) Specifies the layout orientation that is considered during the placement of partial elements.
void	setMaximalDuration(long maximalDuration) Specifies the preferred time limit (in milliseconds) for the layout algorithm.
void	setMinimalNodeDistance(int minimalNodeDistance) Specifies the minimum distance between two adjacent nodes.
void	setMirroringAllowed(boolean mirroringAllowed) Specifies whether or not subgraph components are mirrored to improve the layout quality.
void	setMovingFixedElementsAllowed(boolean movingFixedElementsAllowed) Specifies whether or not the algorithm may move fixed elements.
void	setOrientationOptimizationEnabled(boolean enabled) Specifies whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.
void	setPackComponentsEnabled(boolean packComponentsEnabled) Specifies whether or not a subgraph component may be placed within another subgraph component.
void	setPositioningStrategy(byte strategy) Specifies the objective used for finding 'good' positions for subgraph components.
void	setRouteInterEdgesImmediatelyEnabled(boolean enabled) Specifies whether or not edges between different subgraph components should be routed immediately.

Methods inherited from class y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore

Methods inherited from class java.lang.Object

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

Field Detail

PARTIAL_NODES_DPKEY

public static final java.lang.Object PARTIAL_NODES_DPKEY

A DataProvider key for marking partial nodes.

See Also:

PARTIAL_EDGES_DPKEY

DIRECTED_EDGES_DPKEY

public static final java.lang.Object DIRECTED_EDGES_DPKEY

A DataProvider key for specifying the edges that should be considered to be directed.

If a layout orientation is specified (i.e., getLayoutOrientation() is not ORIENTATION_NONE), the algorithm tries to route directed edges such that they adhere to that orientation.

If this DataProvider is not registered, all edges are considered to be directed.

See Also:

setLayoutOrientation(byte)

PARTIAL_EDGES_DPKEY

public static final java.lang.Object PARTIAL_EDGES_DPKEY

A DataProvider key for marking partial edges.

All edges with at least one partial endpoint are automatically considered to be partial.

See Also:

PARTIAL_NODES_DPKEY

ROUTE_EDGE_DPKEY

public static final java.lang.String ROUTE_EDGE_DPKEY

A DataProvider key for obtaining the edges that should be routed by the edge router.

The associated DataProvider must not be set by the user! The key is used by this algorithm to temporarily add a DataProvider that marks edges that should be routed by the specified edge router, see setEdgeRouter(y.layout.Layouter).

See Also:

setEdgeRouter(y.layout.Layouter), Constant Field Values

COMPONENT_ASSIGNMENT_DPKEY

public static final java.lang.Object COMPONENT_ASSIGNMENT_DPKEY

A DataProvider key for defining custom subgraph components.

The associated DataProvider is only considered if setComponentAssignmentStrategy(byte) is set to COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED.

Nodes of a subgraph component cannot be assigned to different group nodes or different partition cells.

See Also:

COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED, setComponentAssignmentStrategy(byte)

Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with core layout algorithm set to IncrementalHierarchicLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. Furthermore, in this example, the DataProvider associated with this key returns the same object for all partial nodes and, thus, all nodes are assigned to the same component.

EDGE_ROUTING_STRATEGY_ORTHOGONAL

public static final byte EDGE_ROUTING_STRATEGY_ORTHOGONAL

A routing strategy that produces orthogonal routes.

A route of an edge is called orthogonal if it only consists of vertical and horizontal segments.

See Also:

setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_STRAIGHTLINE

public static final byte EDGE_ROUTING_STRATEGY_STRAIGHTLINE

A routing strategy that produces straight-line routes.

See Also:

setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_AUTOMATIC

public static final byte EDGE_ROUTING_STRATEGY_AUTOMATIC

Automatically chooses a suitable routing strategy by analyzing the existing edge routes.

If, for example, all edges have orthogonal edge routes, edges that are rerouted are routed orthogonally, too.

See Also:

setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_ORGANIC

public static final byte EDGE_ROUTING_STRATEGY_ORGANIC

A routing strategy that produces organic routes for partial edges and inter-edges.

See Also:

setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_OCTILINEAR

public static final byte EDGE_ROUTING_STRATEGY_OCTILINEAR

A routing strategy that produces octilinear routes.

A route of an edge is called octilinear if the slope of each segment is a multiple of 45 degrees.

See Also:

setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_SINGLE

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_SINGLE

A component assignment strategy that assigns each node to a separate subgraph component.

See Also:

setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED

A component assignment strategy where the subgraph components correspond to the connected components of the graph.

See Also:

setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING

A component assignment strategy where the subgraph components correspond to the clusters computed by a clustering algorithm based on edge betweenness centrality.

See Also:

setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED

A component assignment strategy where the subgraph components are defined by the user.

See Also:

setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER

public static final byte SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER

A positioning strategy which tries to place each subgraph component close to the barycenter of its graph neighbors.

See Also:

setPositioningStrategy(byte), Constant Field Values

Sample Graphs:

Initial graph where node 3 is a partial node.

After applying the layout algorithm the partial node 3 is placed near the barycenter of its neighbor.

SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH

public static final byte SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH

A positioning strategy which tries to place each subgraph component close to its original position.

The algorithm still tries to prevent overlaps.

See Also:

setPositioningStrategy(byte), Constant Field Values

Sample Graphs:

Initial graph where node 3 is a partial node.

After applying the layout algorithm the partial node 3 is located near its original position.

ORIENTATION_TOP_TO_BOTTOM

public static final byte ORIENTATION_TOP_TO_BOTTOM

Layout orientation specifier which defines that the main layout orientation is from top to bottom.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_BOTTOM_TO_TOP

public static final byte ORIENTATION_BOTTOM_TO_TOP

Layout orientation specifier which defines that the main layout orientation is from bottom to top.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_LEFT_TO_RIGHT

public static final byte ORIENTATION_LEFT_TO_RIGHT

Layout orientation specifier which defines that the main layout orientation is from left to right.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_RIGHT_TO_LEFT

public static final byte ORIENTATION_RIGHT_TO_LEFT

Layout orientation specifier which defines that the main layout orientation is from right to left.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_AUTO_DETECTION

public static final byte ORIENTATION_AUTO_DETECTION

Layout orientation specifier where the orientation is automatically detected.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_NONE

public static final byte ORIENTATION_NONE

Layout orientation specifier where the layout orientation is completely ignored.

See Also:

setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

Constructor Detail

PartialLayouter

public PartialLayouter()

Creates a new instance of PartialLayouter.

PartialLayouter

public PartialLayouter(Layouter subgraphLayouter)

Creates a new instance of PartialLayouter which uses the specified Layouter instance as the core layout algorithm. This instance is applied to each subgraph component, see setComponentAssignmentStrategy(byte).

Parameters:

subgraphLayouter - the layout algorithm that is applied to the subgraph components

See Also:

setComponentAssignmentStrategy(byte)

Method Detail

isMovingFixedElementsAllowed

public boolean isMovingFixedElementsAllowed()

Returns whether or not the algorithm may move fixed elements.

Even though the main objective of the partial layout is to keep non-partial elements fixed, it may sometimes be advantageous to allow to move them in order to obtain more suitable placements of the partial components. Especially if the partial components are quite large, it is very difficult to find a good place without moving fixed elements.

Enabling this option is only recommended if the routing style of the edges (including the current routing style of the non-partial edges) is either orthogonal or octilinear.

Returns:

true if the algorithm may move fixed elements, false otherwise.

See Also:

setMovingFixedElementsAllowed(boolean)

setMovingFixedElementsAllowed

public void setMovingFixedElementsAllowed(boolean movingFixedElementsAllowed)

Specifies whether or not the algorithm may move fixed elements.

Even though the main objective of the partial layout is to keep non-partial elements fixed, it may sometimes be advantageous to allow to move them in order to obtain more suitable placements of the partial components. Especially if the partial components are quite large, it is very difficult to find a good place without moving fixed elements.

Enabling this option is only recommended if the routing style of the edges (including the current routing style of the non-partial edges) is either orthogonal or octilinear.

Default Value:

The default value is false. The algorithm doesn't move fixed elements.

Parameters:

movingFixedElementsAllowed - true if the algorithm may move fixed elements, false otherwise

setCoreLayouter

public void setCoreLayouter(Layouter layouter)

Specifies the Layouter instance that is applied to each subgraph component.

More precisely, during the layout process each subgraph induced by the (partial) nodes of a component (see setComponentAssignmentStrategy(byte)) is first laid out using this instance.

Specified by:

setCoreLayouter in interface LayoutStage

Overrides:

setCoreLayouter in class AbstractLayoutStage

Parameters:

layouter - the Layouter instance that is applied to each subgraph component

Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with core layout algorithm set to IncrementalHierarchicLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

getCoreLayouter

public Layouter getCoreLayouter()

Returns the Layouter instance that is applied to each subgraph component.

More precisely, during the layout process each subgraph induced by the (partial) nodes of a component (see setComponentAssignmentStrategy(byte)) is first laid out using this instance.

Specified by:

getCoreLayouter in interface LayoutStage

Overrides:

getCoreLayouter in class AbstractLayoutStage

Returns:

the Layouter instance that is applied to each subgraph component

See Also:

setCoreLayouter(Layouter)

getMaximalDuration

public long getMaximalDuration()

Returns the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be greater than or equal to 0. If the value is Integer.MAX_VALUE, the time is not limited.

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

Returns:

the preferred time limit

See Also:

setMaximalDuration(long)

setMaximalDuration

public void setMaximalDuration(long maximalDuration)

Specifies the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be greater than or equal to 0. If the value is Integer.MAX_VALUE, the time is not limited.

Restricting the maximum duration may result in a worse 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 Integer.MAX_VALUE. The time is not limited.

Parameters:

maximalDuration - the preferred time limit

Throws:

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

isRouteInterEdgesImmediatelyEnabled

public boolean isRouteInterEdgesImmediatelyEnabled()

Returns whether or not edges between different subgraph components should be routed immediately. If this option is enabled, edges are routed during the placement of the subgraph components, i.e., immediately after a component is placed, its edges to other already placed components are routed. Otherwise, these edges are routed in a separate step after placing all subgraph components. Hence, while enabling this option usually leads to shorter edge routes, the placement of subgraph components is less compact.

Returns:

true if edges between different subgraph components are routed immediately, false otherwise.

See Also:

setRouteInterEdgesImmediatelyEnabled(boolean)

setRouteInterEdgesImmediatelyEnabled

public void setRouteInterEdgesImmediatelyEnabled(boolean enabled)

Specifies whether or not edges between different subgraph components should be routed immediately. If this option is enabled, edges are routed during the placement of the subgraph components, i.e., immediately after a component is placed, its edges to other already placed components are routed. Otherwise, these edges are routed in a separate step after placing all subgraph components. Hence, while enabling this option usually leads to shorter edge routes, the placement of subgraph components is less compact.

Default Value:

The default value is false. Edges are not routed immediately.

Parameters:

enabled - true if edges between different subgraph components should be routed immediately, false otherwise

See Also:

routeInterEdges(y.layout.LayoutGraph, y.base.EdgeList), placeSubgraphs(y.layout.LayoutGraph, y.base.NodeList[])

isPackComponentsEnabled

public boolean isPackComponentsEnabled()

Returns whether or not a subgraph component may be placed within another subgraph component. Enabling this option leads to more compact layout results but requires more runtime.

Returns:

true if a subgraph component may be placed within another subgraph component, false otherwise

See Also:

setPackComponentsEnabled(boolean)

setPackComponentsEnabled

public void setPackComponentsEnabled(boolean packComponentsEnabled)

Specifies whether or not a subgraph component may be placed within another subgraph component. Enabling this option leads to more compact layout results but requires more runtime.

Default Value:

The default value is true. Subgraph component may be placed within another subgraph component.

Parameters:

packComponentsEnabled - true if a subgraph component may be placed within another subgraph component, false otherwise

isFixedGroupResizingEnabled

public boolean isFixedGroupResizingEnabled()

Returns whether or not fixed (non-partial) group nodes may be resized. Enabling this option may lead to better results if there are fixed group nodes, since there is more space for the partial elements.

Returns:

true if fixed group nodes may be resized, false otherwise

See Also:

setFixedGroupResizingEnabled(boolean)

setFixedGroupResizingEnabled

public void setFixedGroupResizingEnabled(boolean fixedGroupResizingEnabled)

Specifies whether or not fixed (non-partial) group nodes may be resized. Enabling this option may lead to better results if there are fixed group nodes since there is more space for the partial elements.

Default Value:

The default value is false. Fixed group nodes may not be resized.

Parameters:

fixedGroupResizingEnabled - true if fixed group nodes may be resized, false otherwise

getPositioningStrategy

public byte getPositioningStrategy()

Returns the objective used for finding 'good' positions for subgraph components.

Returns:

one of the predefined positioning strategies

See Also:

setPositioningStrategy(byte)

setPositioningStrategy

public void setPositioningStrategy(byte strategy)

Specifies the objective used for finding 'good' positions for subgraph components.

Default Value:

The default value is SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER. Each subgraph component is placed close to the barycenter of its graph neighbors.

Parameters:

strategy - one of the predefined positioning strategies

Throws:

java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined positioning strategies

getMinimalNodeDistance

public int getMinimalNodeDistance()

Returns the minimum distance between two adjacent nodes.

The specified value has to be non-negative.

Returns:

the non-negative minimum distance

See Also:

setMinimalNodeDistance(int)

setMinimalNodeDistance

public void setMinimalNodeDistance(int minimalNodeDistance)

Specifies the minimum distance between two adjacent nodes.

The specified value has to be non-negative.

Default Value:

The default value is 10.

Parameters:

minimalNodeDistance - the non-negative minimum distance

Throws:

java.lang.IllegalArgumentException - if the distance is negative

Sample Graphs:

10 - the partial nodes (node 2 and 3) are placed such that the minimum distance between adjacent nodes is at least 10

60 - the partial nodes (node 2 and 3) are placed such that the minimum distance between adjacent nodes is at least 60

isConsiderNodeAlignment

public boolean isConsiderNodeAlignment()

Returns whether or not partial nodes should be aligned. If this option is enabled, the algorithm tries to align the center of partial nodes with other nodes.

Since the specified core layout algorithm doesn't consider this option, the alignment works best if the component assignment is set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.

Returns:

true if nodes are aligned, false otherwise

See Also:

setConsiderNodeAlignment(boolean)

setConsiderNodeAlignment

public void setConsiderNodeAlignment(boolean considerNodeAlignment)

Specifies whether or not partial nodes should be aligned. If this option is enabled, the algorithm tries to align the center of partial nodes with other nodes.

Since the specified core layout algorithm doesn't consider this option, the alignment works best if the component assignment is set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.

Default Value:

The default value is false. Nodes are not aligned.

Parameters:

considerNodeAlignment - true if nodes should be aligned, false otherwise

Sample Graphs:

false - partial node 3 is not aligned with the other nodes.

true - partial node 3 is horizontally aligned with node 1.

canLayout

public boolean canLayout(LayoutGraph graph)

Delegates the call to the specified core layout algorithm. If no core layout algorithm is specified, this method always returns true.

Parameters:

graph - the input graph

Returns:

true if the partial layout algorithm can be applied to the specified graph, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

getComponentAssignmentStrategy

public byte getComponentAssignmentStrategy()

Returns the strategy that assigns partial nodes to subgraph components.

The specified core layout algorithm independently calculates the layout for each subgraph component.

• COMPONENT_ASSIGNMENT_STRATEGY_SINGLE: each partial node is a separate subgraph component. The specified core layout doesn't have any effect because it is applied to each single node separately.
• COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED: components are defined by the connected components of the graph induced by the partial elements.
• COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING: components are defined by edge betweenness clustering.
• COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED: components are user-defined. Two partial nodes are considered to be in the same component if the DataProvider associated with key COMPONENT_ASSIGNMENT_DPKEY returns the same object for both of them.

Borders of groups and partition cells always split up the components, i.e., two nodes assigned to different groups or partition cells are always assigned to different subgraph components.

Returns:

one of the predefined assignment strategies

See Also:

setComponentAssignmentStrategy(byte), COMPONENT_ASSIGNMENT_DPKEY, setCoreLayouter(Layouter)

setComponentAssignmentStrategy

public void setComponentAssignmentStrategy(byte strategy)

Specifies the strategy that assigns partial nodes to subgraph components.

The specified core layout algorithm independently calculates the layout for each subgraph component.

• COMPONENT_ASSIGNMENT_STRATEGY_SINGLE: each partial node is a separate subgraph component. The specified core layout doesn't have any effect because it is applied to each single node separately.
• COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED: components are defined by the connected components of the graph induced by the partial elements.
• COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING: components are defined by edge betweenness clustering.
• COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED: components are user-defined. Two partial nodes are considered to be in the same component if the DataProvider associated with key COMPONENT_ASSIGNMENT_DPKEY returns the same object for both of them.

Borders of groups and partition cells always split up the components, i.e., two nodes assigned to different groups or partition cells are always assigned to different subgraph components.

Default Value:

The default value is COMPONENT_ASSIGNMENT_STRATEGY_SINGLE. Each partial node is assigned to a separate subgraph component.

Parameters:

strategy - one of the predefined assignment strategies

Throws:

java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined strategies

See Also:

COMPONENT_ASSIGNMENT_DPKEY, setCoreLayouter(Layouter)

Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. In this example, all nodes are manually assigned to the same component (i.e. the DataProvider associated with key COMPONENT_ASSIGNMENT_DPKEY returns the same object for all partial nodes).

isOrientationOptimizationEnabled

public boolean isOrientationOptimizationEnabled()

Returns whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.

Returns:

true if this postprocessing step is applied, false otherwise

See Also:

setOrientationOptimizationEnabled(boolean)

setOrientationOptimizationEnabled

public void setOrientationOptimizationEnabled(boolean enabled)

Specifies whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.

Default Value:

The default value is true. This postprocessing step is enabled.

Parameters:

enabled - true if this postprocessing step should be applied, false otherwise

See Also:

setLayoutOrientation(byte), DIRECTED_EDGES_DPKEY

getEdgeRouter

public Layouter getEdgeRouter()

Returns the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).

Calling method setEdgeRoutingStrategy(byte) automatically sets a new edge router instance according to the specified routing strategy.

Edges that have to be routed with the specified router will be marked using DataProvider key ROUTE_EDGE_DPKEY. Hence, the specified router has to be configured such that it observes this key and only routes marked edges!

Returns:

the custom edge router instance that is used for partial edges and edges between different subgraph components

See Also:

setEdgeRouter(y.layout.Layouter), ROUTE_EDGE_DPKEY, setEdgeRoutingStrategy(byte)

setEdgeRouter

public void setEdgeRouter(Layouter edgeRouter)

Specifies the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).

Calling method setEdgeRoutingStrategy(byte) automatically sets a new edge router instance according to the specified routing strategy.

Edges that have to be routed with the specified router will be marked using DataProvider key ROUTE_EDGE_DPKEY. Hence, the specified router has to be configured such that it observes this key and only routes marked edges!

Default Value:

The default value is PartialLayouter.StraightLineEdgeRouter

Parameters:

edgeRouter - the custom edge router instance that is used for partial edges and edges between different subgraph components

See Also:

ROUTE_EDGE_DPKEY, setEdgeRoutingStrategy(byte)

getEdgeRoutingStrategy

public byte getEdgeRoutingStrategy()

Returns the routing strategy that is used for partial edges and inter-edges.

Inter-edges are edges between fixed and partial nodes as well as edges between different subgraph components. The available strategies are listed in the following.

• EDGE_ROUTING_STRATEGY_STRAIGHTLINE produces straight-line edge routes.
• EDGE_ROUTING_STRATEGY_ORTHOGONAL produces orthogonal edge routes.
• EDGE_ROUTING_STRATEGY_OCTILINEAR produces octilinear edge routes.
• EDGE_ROUTING_STRATEGY_ORGANIC produces organic edge routes.
• EDGE_ROUTING_STRATEGY_AUTOMATIC automatically chooses a suitable strategy for the partial edges inter-edges, based on the existing routes of the fixed edges.

Calling this method disables a previously set customized edge router, see setEdgeRouter(Layouter).

Returns:

one of the predefined edge routing strategies

See Also:

setEdgeRoutingStrategy(byte), setEdgeRouter(Layouter)

setEdgeRoutingStrategy

public void setEdgeRoutingStrategy(byte strategy)

Specifies the routing strategy that is used for partial edges and inter-edges.

Inter-edges are edges between fixed and partial nodes as well as edges between different subgraph components. The available strategies are listed in the following.

• EDGE_ROUTING_STRATEGY_STRAIGHTLINE produces straight-line edge routes.
• EDGE_ROUTING_STRATEGY_ORTHOGONAL produces orthogonal edge routes.
• EDGE_ROUTING_STRATEGY_OCTILINEAR produces octilinear edge routes.
• EDGE_ROUTING_STRATEGY_ORGANIC produces organic edge routes.
• EDGE_ROUTING_STRATEGY_AUTOMATIC automatically chooses a suitable strategy for the partial edges inter-edges, based on the existing routes of the fixed edges.

Calling this method disables a previously set customized edge router, see setEdgeRouter(Layouter).

Default Value:

The default value is EDGE_ROUTING_STRATEGY_STRAIGHTLINE

Parameters:

strategy - one of the predefined edge routing strategies

Throws:

java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined routing strategies

See Also:

setEdgeRouter(Layouter)

Sample Graphs:

The input graph where node 2 is a partial node.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_STRAIGHTLINE.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_ORTHOGONAL.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_OCTILINEAR.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_ORGANIC.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_AUTOMATIC. The algorithm detects that the fixed edge between node 1 and 3 is routed straight-line and, thus, routes the inter-edge straight-line, too.

getLayoutOrientation

public byte getLayoutOrientation()

Returns the layout orientation that is considered during the placement of partial elements.

More precisely, the algorithm tries to place each subgraph component such that each predecessor of a component's node v is placed before v and each successor after v with respect to the layout orientation.

• ORIENTATION_NONE: the layout orientation is completely ignored.
• ORIENTATION_AUTO_DETECTION: the layout orientation is automatically detected. The algorithm analyzes the flow direction of fixed edges in the current drawing. If there is no common flow direction, the results are the same as for ORIENTATION_NONE. Otherwise, the layout orientation is one of the four main orientation.
• ORIENTATION_TOP_TO_BOTTOM: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed above v and each successor below v.
• ORIENTATION_BOTTOM_TO_TOP: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed below v and each successor above v.
• ORIENTATION_LEFT_TO_RIGHT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the left of v and each successor to the right of v.
• ORIENTATION_RIGHT_TO_LEFT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the right of v and each successor to the left of v.

This only affects the placement of nodes of different subgraph components that are connected by directed edges. For nodes of the same subgraph component the layout orientation depends on the chosen core layout algorithm.

Returns:

one of the predefined layout orientations

See Also:

setLayoutOrientation(byte), DIRECTED_EDGES_DPKEY

setLayoutOrientation

public void setLayoutOrientation(byte layoutOrientation)

Specifies the layout orientation that is considered during the placement of partial elements.

More precisely, the algorithm tries to place each subgraph component such that each predecessor of a component's node v is placed before v and each successor after v with respect to the layout orientation.

• ORIENTATION_NONE: the layout orientation is completely ignored.
• ORIENTATION_AUTO_DETECTION: the layout orientation is automatically detected. The algorithm analyzes the flow direction of fixed edges in the current drawing. If there is no common flow direction, the results are the same as for ORIENTATION_NONE. Otherwise, the layout orientation is one of the four main orientation.
• ORIENTATION_TOP_TO_BOTTOM: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed above v and each successor below v.
• ORIENTATION_BOTTOM_TO_TOP: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed below v and each successor above v.
• ORIENTATION_LEFT_TO_RIGHT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the left of v and each successor to the right of v.
• ORIENTATION_RIGHT_TO_LEFT: the algorithm tries to place partial nodes (subgraph components) such that each predecessor of a node v is placed to the right of v and each successor to the left of v.

This only affects the placement of nodes of different subgraph components that are connected by directed edges. For nodes of the same subgraph component the layout orientation depends on the chosen core layout algorithm.

Default Value:

The default value is ORIENTATION_NONE. The layout orientation is completely ignored.

Parameters:

layoutOrientation - one of the predefined layout orientations

Throws:

java.lang.IllegalArgumentException - if the specified orientation does not match one of the predefined orientations

See Also:

DIRECTED_EDGES_DPKEY

Sample Graphs:

ORIENTATION_NONE: the partial node 3 is placed without considering the layout orientation.

ORIENTATION_AUTO_DETECTION: the layout algorithm detects that the placement of the fixed nodes (node 1 and 2) corresponds to ORIENTATION_TOP_TO_BOTTOM placement and, thus, uses this orientation during the placement of the partial node (node 3).

ORIENTATION_TOP_TO_BOTTOM: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_TOP_TO_BOTTOM placement rule, node 3 is placed below node 1.

ORIENTATION_BOTTOM_TO_TOP: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_BOTTOM_TO_TOP placement rule, node 3 is placed above node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

ORIENTATION_LEFT_TO_RIGHT: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_LEFT_TO_RIGHT placement rule, node 3 is placed to the right of node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

ORIENTATION_RIGHT_TO_LEFT: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_RIGHT_TO_LEFT placement rule, node 3 is placed to the left of node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

isMirroringAllowed

public boolean isMirroringAllowed()

Returns whether or not subgraph components are mirrored to improve the layout quality. If enabled, the algorithm checks for each component which of the four possible mirrorings minimizes the edge length.

Returns:

true if subgraph components are mirrored, false otherwise

See Also:

setMirroringAllowed(boolean)

setMirroringAllowed

public void setMirroringAllowed(boolean mirroringAllowed)

Specifies whether or not subgraph components are mirrored to improve the layout quality. If enabled, the algorithm checks for each component which of the four possible mirrorings minimizes the edge length.

Default Value:

The default value is false. Mirroring is disabled.

Parameters:

mirroringAllowed - true if subgraph components should be mirrored, false otherwise

Sample Graphs:

The input graph where node 1 and 2 are fixed while the remaining nodes are partial. The partial layout is applied to this graph with core layout algorithm set to SingleCycleLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

false

true

doLayout

public void doLayout(LayoutGraph graph)

This method calculates the partial layout. It calls the following methods:

1. routeEdgesBetweenFixedElements(y.layout.LayoutGraph, y.base.EdgeList)
2. layoutSubgraph(y.layout.LayoutGraph) for each subgraph component
3. placeSubgraphs(y.layout.LayoutGraph, y.base.NodeList[])
4. routeInterEdges(y.layout.LayoutGraph, y.base.EdgeList)

The above methods are called after applying the OrientationLayouter. Hence, they always assume that the graph is drawn from top to bottom.

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)

doPartialLayout

public void doPartialLayout(LayoutGraph graph)

This method calculates the partial layout.

For internal use only. Users should start the layout by calling doLayout(LayoutGraph).

Parameters:

graph - the input graph

layoutSubgraph

protected void layoutSubgraph(LayoutGraph subGraph)

This method is called during the layout process and calculates the layout for the given subgraph component using the specified core layout algorithm. It is called once for each subgraph component.

Subclasses may implement a custom layout strategy or add some additional data.

Parameters:

subGraph - the subgraph component

placeSubgraphs

protected void placeSubgraphs(LayoutGraph graph,
                              NodeList[] subgraphComponents)

This method is called during the layout process and places the subgraph components one-by-one onto the drawing area. Therefore, it considers the specified objective for finding a suitable position.

Subclasses may implement a custom placement strategy or add some additional data. However, they must not modify the given subgraph component lists.

Parameters:

graph - the input graph

subgraphComponents - each entry contains a NodeList that induces a subgraph component

routeInterEdges

protected void routeInterEdges(LayoutGraph graph,
                               EdgeList interEdges)

This method is called during the layout process and routes all inter-edges. Inter-edges are edges between different subgraph components including edges between fixed and partial elements. For the routing, this method uses the edge router instance set with method setEdgeRouter(y.layout.Layouter). If no edge router was specified by the user, it uses an internal edge router with routing strategy getEdgeRoutingStrategy().

Subclasses may implement a custom routing strategy or add some additional data.

Parameters:

graph - the relevant subgraph

interEdges - the list of inter-edges to be routed

routeEdgesBetweenFixedElements

protected void routeEdgesBetweenFixedElements(LayoutGraph graph,
                                              EdgeList partialEdges)

This method is called during the layout process and routes all partial edges that connect two fixed elements. It either uses a custom edge router or an internal edge router that produces routes according to the specified routing strategy.

Subclasses may implement a custom routing strategy or add some additional data.

Parameters:

graph - the subgraph of the input graph induced by the fixed nodes

partialEdges - the list of partial edges to be routed

configureEdgeRouter

protected void configureEdgeRouter(Layouter edgeRouter)

This method is called each time when edges are routed with an edge router.

Subclasses may modify the configuration of the given edge router instance.

The type of the given instance depends on the edge routing strategy, i.e., if the routing strategy is set to EDGE_ROUTING_STRATEGY_OCTILINEAR or EDGE_ROUTING_STRATEGY_ORTHOGONAL it's an instance of EdgeRouter, if the routing strategy is set to EDGE_ROUTING_STRATEGY_ORGANIC it's an instance of OrganicEdgeRouter, and, if the routing strategy is set to EDGE_ROUTING_STRATEGY_STRAIGHTLINE it's an instance of PartialLayouter.StraightLineEdgeRouter. If the edge routing strategy is set to EDGE_ROUTING_STRATEGY_AUTOMATIC, the layout algorithm chooses one of the above strategies that best fits the routing style of the fixed edges.

If a custom edge router is set (see setEdgeRouter(y.layout.Layouter)), its instance corresponds to that of the parameter.

Parameters:

edgeRouter - the instance used for routing the edges

See Also:

setEdgeRouter(y.layout.Layouter), setEdgeRoutingStrategy(byte)