y.layout.circular
Class SingleCycleLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.circular.SingleCycleLayouter

All Implemented Interfaces:

Layouter

public class SingleCycleLayouter
extends CanonicMultiStageLayouter

This layout algorithm places all nodes of a graph on a single cycle.

Layout Style

All nodes of a graph are placed on one common circle, generating circular layouts. The edges are drawn as simple, straight lines. The resulting layouts look like a ring. Edges connecting nodes which are not next to each other on the ring are routed inside of the circle.

Single-cycle circular layouts are suitable for the visualization of networks such as ring networks or smaller social networks. They are also useful to layout cyclic subgraphs of a larger graph.

An example of a single cycle layout

Concept

First, the nodes are sorted by applying either a custom or some default NodeSequencer. Then, all nodes are placed on a circle with an appropriate radius according to the calculated order.

Features

The order in which the nodes are placed on the circle is a crucial aspect of this algorithm. By specifying a NodeSequencer instance via setNodeSequencer(NodeSequencer), the order can be customized.

There are two options to determine the radius of the circle on which nodes are placed:

1. The radius can be determined automatically. A specified minimum radius will be obeyed when choosing the radius.
2. The radius can be chosen manually. To do so, disable the automatic radius selection and specify the custom radius via setFixedRadius(double).

Field Summary

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

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

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts general graphs without exception.
void	doLayoutCore(LayoutGraph graph) Arranges the nodes of the given graph such that they all lie on a common circle.
boolean	getAutomaticRadius() Returns whether or not the radius of the circle should be determined automatically.
double	getFixedRadius() Returns a fixed radius for the circle on which the nodes will be placed.
double	getInitialAngle() Returns the angle that describes the location on the circle of the first node.
double	getLastAppliedRadius() Returns the radius that was applied to the last layout calculated by this algorithm.
int	getMinimalNodeDistance() Returns the minimum distance between nodes that are next to each other on the circle.
double	getMinimalRadius() Returns the minimum radius for the circle on which the nodes are placed.
NodeSequencer	getNodeSequencer() Returns the custom NodeSequencer that will be used for determining the order of the nodes for the circle placement.
boolean	isFromSketchModeEnabled() Returns whether or not to consider the coordinates of the input diagram when arranging the graph.
void	setAutomaticRadius(boolean automatic) Specifies whether or not the radius of the circle should be determined automatically.
void	setFixedRadius(double radius) Specifies a fixed radius for the circle on which the nodes will be placed.
void	setFromSketchModeEnabled(boolean fromSketchModeEnabled) Specifies whether or not to consider the coordinates of the input diagram when arranging the graph.
void	setInitialAngle(double initialAngle) Specifies the angle that describes the location on the circle of the first node.
void	setMinimalNodeDistance(int minimumNodeDistance) Specifies the minimum distance between nodes that are next to each other on the circle.
void	setMinimalRadius(double minimumRadius) Specifies the minimum radius for the circle on which the nodes are placed.
void	setNodeSequencer(NodeSequencer sequencer) Specifies the custom NodeSequencer that will be used for determining the order of the nodes for the circle placement.
void	setOrientationLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage that modifies the orientation of the layout is activated.
void	setSelfLoopLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for routing self-loops is activated.

Methods inherited from class y.layout.CanonicMultiStageLayouter

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

Methods inherited from class java.lang.Object

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

Constructor Detail

SingleCycleLayouter

public SingleCycleLayouter()

Creates a new SingleCycleLayouter instance with default settings.

Method Detail

getInitialAngle

public double getInitialAngle()

Returns the angle that describes the location on the circle of the first node.

The angle is measured in radians and world coordinates, e.g., 0 means east, Pi/2 means south.

This setting is ignored if the SingleCycleLayouter is used by CircularLayouter to arrange single-cycle partitions. The CircularLayouter will automatically choose the initial angle.

Returns:

the angle for the placement of the first node in radians

See Also:

setInitialAngle(double)

setInitialAngle

public void setInitialAngle(double initialAngle)

Specifies the angle that describes the location on the circle of the first node.

The angle is measured in radians and world coordinates, e.g., 0 means east, Pi/2 means south.

This setting is ignored if the SingleCycleLayouter is used by CircularLayouter to arrange single-cycle partitions. The CircularLayouter will automatically choose the initial angle.

Default Value:

The default value is 0.0. The first node is placed east.

Parameters:

initialAngle - the angle for the placement of the first node in radians

Sample Graphs:

0.0 - the highlighted first node is placed east

Pi/2 - the highlighted first node is placed south

isFromSketchModeEnabled

public boolean isFromSketchModeEnabled()

Returns whether or not to consider the coordinates of the input diagram when arranging the graph.

If this feature is enabled, the original circular order of peripheral nodes around an estimated circle center will be preserved.

Returns:

true if the initial coordinates of the nodes are considered, false otherwise

See Also:

setFromSketchModeEnabled(boolean)

setFromSketchModeEnabled

public void setFromSketchModeEnabled(boolean fromSketchModeEnabled)

Specifies whether or not to consider the coordinates of the input diagram when arranging the graph.

If this feature is enabled, the original circular order of peripheral nodes around an estimated circle center will be preserved.

Default Value:

The default value is false. The coordinates of the input diagram are not considered.

Parameters:

fromSketchModeEnabled - true if the initial coordinates of the nodes should be considered, false otherwise

Sample Graphs:

Order of nodes when From Sketch mode is disabled

Initial graph with changed node order

Order of nodes when From Sketch mode is enabled

setMinimalNodeDistance

public void setMinimalNodeDistance(int minimumNodeDistance)

Specifies the minimum distance between nodes that are next to each other on the circle.

The minimum node distance will be ignored if the automatic radius selection is disabled. In that case, the distance between nodes will follow from the specified fixed radius.

Default Value:

The default value is 30.

Parameters:

minimumNodeDistance - the non-negative minimum distance between nodes

Throws:

java.lang.IllegalArgumentException - if the given distance is negative

Sample Graphs:

Minimum node distance set to 30

Minimum node distance set to 60

getMinimalNodeDistance

public int getMinimalNodeDistance()

Returns the minimum distance between nodes that are next to each other on the circle.

The minimum node distance will be ignored if the automatic radius selection is disabled. In that case, the distance between nodes will follow from the specified fixed radius.

Returns:

the non-negative minimum distance between nodes

See Also:

setMinimalNodeDistance(int)

setFixedRadius

public void setFixedRadius(double radius)

Specifies a fixed radius for the circle on which the nodes will be placed.

If the radius is too small, the nodes on the circle may overlap with each other.

This fixed radius is only considered if the radius is not automatically selected by the layout algorithm.

Default Value:

The default value is 200.

Parameters:

radius - the fixed radius for the circle

Throws:

java.lang.IllegalArgumentException - if the given radius is negative

See Also:

setMinimalRadius(double), setAutomaticRadius(boolean)

Sample Graphs:

200

50

getFixedRadius

public double getFixedRadius()

Returns a fixed radius for the circle on which the nodes will be placed.

If the radius is too small, the nodes on the circle may overlap with each other.

This fixed radius is only considered if the radius is not automatically selected by the layout algorithm.

Returns:

the fixed radius for the circle

See Also:

setFixedRadius(double), setMinimalRadius(double), setAutomaticRadius(boolean)

setMinimalRadius

public void setMinimalRadius(double minimumRadius)

Specifies the minimum radius for the circle on which the nodes are placed.

This setting is only considered if the automatic radius selection is enabled. Otherwise, the chosen fixed radius will be used.

Default Value:

The default value is 5.0.

Parameters:

minimumRadius - the minimum circle radius

Throws:

java.lang.IllegalArgumentException - if the given minimum radius is negative

See Also:

setFixedRadius(double), setAutomaticRadius(boolean)

getMinimalRadius

public double getMinimalRadius()

Returns the minimum radius for the circle on which the nodes are placed.

This setting is only considered if the automatic radius selection is enabled. Otherwise, the chosen fixed radius will be used.

Returns:

the minimum circle radius

See Also:

setMinimalRadius(double), setFixedRadius(double), setAutomaticRadius(boolean)

setAutomaticRadius

public void setAutomaticRadius(boolean automatic)

Specifies whether or not the radius of the circle should be determined automatically.

If enabled, the radius will be chosen such that the distance between nodes which are next to each other on the circle is approximately the same as the minimum node distance.

If this feature is disabled, the radius specified via setFixedRadius(double) will be applied.

Default Value:

The default value is true. The radius will be chosen automatically.

Parameters:

automatic - true, if the radius of the circle should be determined automatically, false, otherwise

See Also:

setMinimalRadius(double), setFixedRadius(double)

getAutomaticRadius

public boolean getAutomaticRadius()

Returns whether or not the radius of the circle should be determined automatically.

If enabled, the radius will be chosen such that the distance between nodes which are next to each other on the circle is approximately the same as the minimum node distance.

If this feature is disabled, the radius specified via setFixedRadius(double) will be applied.

Returns:

true, if the radius of the circle is determined automatically, false, otherwise

See Also:

setAutomaticRadius(boolean), setMinimalRadius(double), setFixedRadius(double)

setNodeSequencer

public void setNodeSequencer(NodeSequencer sequencer)

Specifies the custom NodeSequencer that will be used for determining the order of the nodes for the circle placement.

To restore the default sequencer, simply set the custom sequencer to null.

Parameters:

sequencer - the sequencer for determining a node order for the circle placement

getNodeSequencer

public NodeSequencer getNodeSequencer()

Returns the custom NodeSequencer that will be used for determining the order of the nodes for the circle placement.

To restore the default sequencer, simply set the custom sequencer to null.

Returns:

the sequencer for determining a node order for the circle placement

See Also:

setNodeSequencer(NodeSequencer)

getLastAppliedRadius

public double getLastAppliedRadius()

Returns the radius that was applied to the last layout calculated by this algorithm.

This method is useful if one wants to know the actual radius of a layout calculated by this algorithm.

Returns:

the radius applied to the result of the last layout calculation

setOrientationLayouterEnabled

public void setOrientationLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage that modifies the orientation of the layout is activated.

Overrides:

setOrientationLayouterEnabled in class CanonicMultiStageLayouter

If the current layout orientation is LayoutOrientation.TOP_TO_BOTTOM, the orientation of the layout will not be modified.

Based on the undirected layout style, disabling OrientationLayouter has no significant effect.

Default Value:

The default value is true. The orientation LayoutStage is activated.

Parameters:

enabled - true if the stage that modifies the orientation is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isOrientationLayouterEnabled(), CanonicMultiStageLayouter.setOrientationLayouter(y.layout.LayoutStage), CanonicMultiStageLayouter.setLayoutOrientation(byte), OrientationLayouter

setSelfLoopLayouterEnabled

public void setSelfLoopLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for routing self-loops is activated.

Overrides:

setSelfLoopLayouterEnabled in class CanonicMultiStageLayouter

CircularLayouter cannot handle self-loops. Disabling SelfLoopLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that routes self-loops is activated.

Parameters:

enabled - true if the stage responsible for routing self-loops is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isSelfLoopLayouterEnabled(), CanonicMultiStageLayouter.setSelfLoopLayouter(y.layout.LayoutStage), SelfLoopLayouter

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Accepts general graphs without exception.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true for all general graphs, false if the given graph is null

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Arranges the nodes of the given graph such that they all lie on a common circle.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph