ilog.views.graphlayout.circular

Class IlvCircularLayout

java.lang.Object

ilog.views.graphlayout.IlvGraphLayout

ilog.views.graphlayout.basic.IlvBasicLinkStyleLayout

ilog.views.graphlayout.circular.IlvCircularLayout

public class IlvCircularLayout
extends ilog.views.graphlayout.basic.IlvBasicLinkStyleLayout

The main class for the Circular Layout algorithm.

The Circular Layout algorithm displays graphs representing interconnected ring and/or star network topologies. The algorithm takes into account the size of the nodes and tries to avoid overlapping nodes.

Here are sample drawings produced by the Circular Layout algorithm:

For the layout algorithm to work, you must provide information about the topology of the network, that is about how the network should be divided into interconnected clusters.

The layout algorithm provides three clustering modes (see #setClusteringMode(int)):

• Clustering by cluster identifiers

  For each node of the graph, you must specify the cluster (that is, either the ring or the star) to which it belongs. Note that a node can belong to more than one cluster. To do this, you can use the methods #setClusterId(Object, IlvClusterId) and #addClusterId(Object, IlvClusterId). The class IlvClusterId is the abstract base class that is used as the identifier for the clusters. You can use one of its subclasses provided in JViews (IlvClusterName and IlvClusterNumber) or write your own subclass.

  In addition, for each cluster (ring or star), you can specify the order of the nodes along the cluster (with the exception of the central node for star clusters). To do this, you must use the methods #setClusterId(Object, IlvClusterId, int) and #addClusterId(Object, IlvClusterId, int), where the last argument is an integer index value associated with the node and the cluster. If the index values are provided, the layout algorithm places the nodes on the cluster in the order specified by the indexes.

  Note that in this mode the initial position of the nodes (at the moment you start the layout) does not affect the resulting layout. However, nodes specified as fixed are not moved if you call the method #setPreserveFixedNodes(boolean) with a true argument.

• Clustering automatically

  This mode works similar to the clustering by cluster identifiers, however you do not need to specify cluster information for all nodes. The topology of the graph is analyzed to determine the clusters. A link crossing reduction heuristic is used to determine the order of the nodes within the clusters. Additionally, you can specify cluster ids or cluster indexe for some nodes, in the same way as in the mode clustering by cluster identifiers.

• Clustering by subgraphs

  In this mode, the algorithm handles a nested graph including intergraph links. It arranges the nodes of each subgraph on a circle, so that the number of link crossings is small. It respects the intergraph links and rotates the cluster so that the number of link crossings is small.

  It assumes that all nodes are nearly square, all nodes are in subgraphs, but the subgraph nesting is only 1. Nodes that are inside subgraphs of subgraphs are not anymore handles.

  Note that in this mode each subgraph keeps its initial position. The subgraphs can be placed either by a different layout algorithm, or interactively.

The following figure illustrates the dimensional parameters of the layout algorithm (clustering by cluster identifiers).

See the corresponding chapter of the User's Manual for details on the algorithm, the types of graphs for which this algorithm can be used, the features and limitations, code samples, parameters, and so on.

CSS example:

SDM {
GraphLayout : true;
}

GraphLayout {
graphLayout : @#layout;
// optional settings for the graph layout renderer
}

Subobject#layout {
class : "ilog.views.graphlayout.circular.IlvCircularLayout";
areaMinimizationEnabled : "false";
clusterByBiconnectivity : "false";
clusteringMode : "BY_CLUSTER_IDS";
coordinatesMode : "MANAGER_COORDINATES";
disconnectedGraphOffset : "3.0";
highDegreeStarClusterSize : "2";
interClusterCrossingReduction : "false";
interClusterLinkCrossingPenalty : "3.0";
intraClusterLinkCrossingPenalty : "3.0";
layoutOfClusterGraph : "@#ilvGraphLayout";
layoutOfConnectedComponentsEnabled : "false";
levelOffset : "3.0";
maximumClusterSize : "2";
maximumNumberOfIterationsToReachMaxClusterSize : "2";
maxNumberOfPermutations : "2";
minBusyTime : "3";
minimumClusterSize : "2";
mixedClusterLinkCrossingPenalty : "3.0";
offset : "3.0";
}

CSS specification of per-node and per-link layout parameters:

The following table lists the per-object rendering properties of the GraphLayout renderer:

Property	Type	Default	Description
GraphLayout	IlvGraphLayout	null	Lets you define a different graph layout algorithm for each subgraph. If one is not specified, the same algorithm is applied recursively to all subgraphs.
LayoutFixed	String	false	Deprecated, replaced by Fixed.
Fixed	String	false	Lets you specify that the node or link must not be moved or reshaped by the layout algorithm.
LayoutGroup	String	null	Lets you apply the algorithm to different groups of objects, one group after the other.
LayoutIgnored	boolean	false	If true, the object is ignored by the layout.

The per-node and per-link layout parameters are specified in the style sheet through the CSS rules for nodes and links, not through the CSS rule for graph layout. For instance:

link.tag {
LinkStyle : "ORTHOGONAL_STYLE";
}

Note that the names of the node and link layout parameters use an initial capital, unlike the regular properties. You can add a node to several clusters by setting the ClusterId property several times:

node[name="foo"] {
ClusterId : "cluster1;cluster2;cluster3";
}

You can optionally specify an index inside each cluster:

ClusterId : "cluster1,5;cluster2,1;cluster3,4"; See also the documentation of the class IlvGraphLayoutRenderer.

Property Summary

Properties

Modifier and Type	Property and Description
boolean	areaMinimizationEnabled Sets whether the total area minimization option is enabled.
java.lang.String	class Default constructor.
boolean	clusterByBiconnectivity Sets whether the clustering by biconnectivity is enabled.
int	clusteringMode Sets the clustering mode.
int	coordinatesMode Sets the coordinates mode to be used during layout.
double	disconnectedGraphOffset Sets the offset between disconnected groups of clusters (rings and/or stars).
int	highDegreeStarClusterSize Sets the minimum size to create star clusters from nodes with high degree.
boolean	interClusterCrossingReduction Sets whether the crossing reduction takes inter cluster links into account.
double	interClusterLinkCrossingPenalty Sets the penalty for crossings of links between nodes of different clusters.
double	intraClusterLinkCrossingPenalty Sets the penalty for crossings of links between nodes of the same cluster.
IlvGraphLayout	layoutOfClusterGraph Sets the layout instance that lays out the graph of clusters.
boolean	layoutOfConnectedComponentsEnabled Sets whether the generic connected component layout mechanism is enabled.
double	levelOffset Sets the offset between two concentric levels.
int	maximumClusterSize Sets the maximum number of nodes to form a cluster.
int	maximumNumberOfIterationsToReachMaxClusterSize Sets the number of iterations to achieve the maximum cluster size.
int	maxNumberOfPermutations Sets the maximum number of permutations tested for a cluster of more than 7 nodes.
long	minBusyTime Sets the minimal time that the layout algorithm can be busy.
int	minimumClusterSize Sets the minimum number of nodes to form a cluster.
double	mixedClusterLinkCrossingPenalty Sets the penalty for crossings of intra cluster links with inter cluster links.
double	offset Sets the offset value.

Properties inherited from class ilog.views.graphlayout.basic.IlvBasicLinkStyleLayout

connectLinksToNodeCenters, linkStyle, multiLinkMaxSpread, multiLinkMode, multiLinkOffset, multiSelfLinkDistribution, multiSelfLinkMaxSpread, multiSelfLinkOffset, selfLinkAbsoluteAttachPosition, selfLinkAllowedCorners, selfLinkConnectToNodeCenter, selfLinkMode, selfLinkOrientation, selfLinkRelativeAttachPosition, selfLinkSpacing

In addition, for each cluster (ring or star), you can specify the order of the nodes along the cluster (with the exception of the central node for star clusters). To do this, you must use the methods #setClusterId(Object, IlvClusterId, int) and #addClusterId(Object, IlvClusterId, int), where the last argument is an integer index value associated with the node and the cluster. If the index values are provided, the layout algorithm places the nodes on the cluster in the order specified by the indexes.

The position of the clusters is computed using a radial tree-like algorithm.

Note that in this mode the initial position of the nodes (at the moment you start the layout) does not affect the resulting layout. However, nodes specified as fixed are not moved if you call the method #setPreserveFixedNodes(boolean) with a true argument.

#BY_SUBGRAPHS - The information needed for dividing the graph into clusters is provided by placing the nodes and links into subgraphs.

In this mode, the algorithm handles a nested graph including intergraph links. It arranges the nodes of each subgraph on a circle, so that the number of link crossings is small. It respects the intergraph links and rotates the cluster so that the number of link crossings is small.

It assumes that all nodes are nearly square, all nodes are in subgraphs, but the subgraph nesting is only 1. Nodes that are inside subgraphs of subgraphs are not anymore handles.

Note that in this mode each subgraph keeps its initial position. The subgraphs can be placed either by a different layout algorithm, or interactively.

#AUTOMATIC - This is similar to the mode #BY_CLUSTER_IDS, but does not require any specification of clusters. The graph is divided into clusters by anaylizing the topology of the graph. Biconnected components form initial clusters. The remaining nodes that do not belong to any (nontrivial) biconnected component form star clusters if their degree is larger than the star cluster threshold. Then, the initial clusters are merged if they are smaller than the minimal size of a cluster, or split if they are larger than the maximal size of a cluster.

You can specify clusters using IlvClusterId objects for some nodes, but it is not needed to specify it for all nodes. The class IlvClusterId is the abstract base class that is used as the identifier for the clusters. You can use one of its subclasses provided in JViews (IlvClusterName and IlvClusterNumber) or write your own subclass.

In addition, for specified cluster (ring or star), you can optionally specify the order of the nodes along the cluster (with the exception of the central node for star clusters). To do this, you must use the methods #setClusterId(Object, IlvClusterId, int) and #addClusterId(Object, IlvClusterId, int), where the last argument is an integer index value associated with the node and the cluster. You can specify indexe for all or some nodes of the cluster. Nodes with specified index are placed in this relative order on the cluster. Nodes without specified index are merged into this relative order by using a heuristic to reduce the number of link crossings.

The position of the clusters is computed using an instance of IlvTreeLayout.

The default value is #BY_CLUSTER_IDS .

CSS example: clusteringMode : "BY_CLUSTER_IDS";

Allowed values:
BY_CLUSTER_IDS		Provided by cluster ids
BY_SUBGRAPHS		Provided by subgraphs
AUTOMATIC

coordinatesMode

public int coordinatesMode

Sets the coordinates mode to be used during layout.

Valid values are:

• ilog.views.graphlayout.IlvGraphLayout#MANAGER_COORDINATES - The geometry of the graph is computed using the coordinate space of the manager (that is, the attached IlvGrapher) without applying any transformation.

  This mode should be used if you visualize the graph at zoom level 1, or you do not visualize it at all, or the graph contains only fully zoomable objects. In all these cases there is no need to take the transformer into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates.

• ilog.views.graphlayout.IlvGraphLayout#VIEW_COORDINATES - The geometry of the graph is computed in the coordinate space of the manager view. More exactly, all the coordinates are transformed using the current reference transformer.

  This mode should be used if you want the dimensional parameters of the layout algorithms to be considered as being specified in manager view coordinates.

• ilog.views.graphlayout.IlvGraphLayout#INVERSE_VIEW_COORDINATES - The geometry of the graph is computed using the coordinate space of the manager view and then applying the inverse transformation. This mode is equivalent to the "manager coordinates" mode if the geometry of the graphic objects strictly obeys the transformer. (A small difference may exist because of the limited precision of the computations.)

  On the contrary, if some graphic objects are either nonzoomable (see IlvGraphic#zoomable) or semizoomable (for example, links with a maximum line width), this mode gives different results than the manager coordinates mode. These results are optimal if the graph is visualized using the same transformer as the one taken into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates.

The default value is IlvGraphLayout#INVERSE_VIEW_COORDINATES.

This option is useful only if the attached graph model is an IlvGrapherAdapter (or a subclass). Otherwise, it has no effect. Note: the coordinates mode of the layout is used only while this layout is running. If layout is not running, operations on the grapher adapter use the coordinates mode that was set on the grapher adapter directly (see IlvGrapherAdapter#setCoordinatesMode).

CSS example: coordinatesMode : "MANAGER_COORDINATES";

Allowed values:

MANAGER_COORDINATES

VIEW_COORDINATES

INVERSE_VIEW_COORDINATES

disconnectedGraphOffset

public double disconnectedGraphOffset

Sets the offset between disconnected groups of clusters (rings and/or stars). Disconnected groups of clusters are laid out in rows. This offset value represents the offset between the rows and the offset between groups on the same row.

The default value is 10.

Note that this parameter is only used if the clustering mode (see #setClusteringMode(int)) is #BY_CLUSTER_IDS.

CSS example: disconnectedGraphOffset : "3.0";

highDegreeStarClusterSize

public int highDegreeStarClusterSize

Sets the minimum size to create star clusters from nodes with high degree. The algorithm searches for nodes of high degree (high number of connected nodes) that are not yet clustered by biconnectivity. If the degree is at least the minimum size, it creates a star cluster with the high degree nodes as center of the cluster.

The default value is 5.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

CSS example: highDegreeStarClusterSize : "2";

interClusterCrossingReduction

public boolean interClusterCrossingReduction

Sets whether the crossing reduction takes inter cluster links into account. This is enabled by default.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

CSS example: interClusterCrossingReduction : "false";

interClusterLinkCrossingPenalty

public double interClusterLinkCrossingPenalty

Sets the penalty for crossings of links between nodes of different clusters. These links are called inter cluster links.

The default value is 1.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

During the crossing reduction, intra cluster links compete with inter cluster links, since some node orderings of a cluster produce more crossings of links inside the cluster, while other node orderings produce more crossings of links connecting different clusters. The penalty allows to fine tune whether intra cluster links or inter cluster links are more important.

CSS example: interClusterLinkCrossingPenalty : "3.0";

intraClusterLinkCrossingPenalty

public double intraClusterLinkCrossingPenalty

Sets the penalty for crossings of links between nodes of the same cluster. These links are called intra cluster links.

The default value is 1.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

During the crossing reduction, intra cluster links compete with inter cluster links, since some node orderings of a cluster produce more crossings of links inside the cluster, while other node orderings produce more crossings of links connecting different clusters. The penalty allows to fine tune whether intra cluster links or inter cluster links are more important.

CSS example: intraClusterLinkCrossingPenalty : "3.0";

layoutOfClusterGraph

public IlvGraphLayout layoutOfClusterGraph

Sets the layout instance that lays out the graph of clusters. This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

If a layout instance has been specified, this instance is used. If no layout instance has been specified, an instance of IlvTreeLayout is used. The tree layout is set to balloon layout mode. Note that the node comparator of the tree layout should not be set on this layout instance because it is modified at runtime (see #customizeLayoutOfClusterGraph). You can call this method with a null argument to return to the default tree layout instance.

The layout instance cannot be used independently as long as it is set as a layout of the cluster graph.

CSS example: layoutOfClusterGraph : "@#ilvGraphLayout";

layoutOfConnectedComponentsEnabled

public boolean layoutOfConnectedComponentsEnabled

Sets whether the generic connected component layout mechanism is enabled. If enabled on a layout class that supports this mechanism (see #supportsLayoutOfConnectedComponents()), the method #performLayout(boolean, boolean, boolean) cuts the attached graph model into connected components and lays out each connected component separately. Then the connected components are placed using the layout instance returned by the method #getLayoutOfConnectedComponents().

Notice that the connected component layout is not used if the graph is connected.

A RuntimeException is thrown if the layout does not support this mechanism.

The default value is the value returned by the method #isLayoutOfConnectedComponentsEnabledByDefault().

CSS example: layoutOfConnectedComponentsEnabled : "false";

levelOffset

public double levelOffset

Sets the offset between two concentric levels. This is an additional offset that is added to the minimum value computed by the layout algorithm to avoid overlapping clusters on the same level.

The default value is zero.

Note that this parameter is only used if the clustering mode (see #setClusteringMode(int)) is #BY_CLUSTER_IDS.

CSS example: levelOffset : "3.0";

maximumClusterSize

public int maximumClusterSize

Sets the maximum number of nodes to form a cluster. The value is obeyed for regular clusters, but not for star clusters. The value is only a hint. If the minimum and maximum cluster size are close, then the maximunm cluster size is sometimes not obeyed, in order to satisfy the minimum cluster size.

The default value is 50.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

CSS example: maximumClusterSize : "2";

maximumNumberOfIterationsToReachMaxClusterSize

public int maximumNumberOfIterationsToReachMaxClusterSize

Sets the number of iterations to achieve the maximum cluster size.

The default value is 10.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

Splitting a cluster is an iterative process that tries to find good subclusters with only few links that run between different clusters. Initial subclusters are improved iteratively. If the cluster algorithm takes too much time, reducting the number of iterations speeds up the algorithm.

CSS example: maximumNumberOfIterationsToReachMaxClusterSize : "2";

maxNumberOfPermutations

public int maxNumberOfPermutations

Sets the maximum number of permutations tested for a cluster of more than 7 nodes. For smaller cluster, always all permutations are tested.

This parameter is only used if the clustering mode (see #setClusteringMode(int)) is #BY_SUBGRAPHS.

The algorithm generates permutations of node orderings along the cluster circle and chooses the one with the best crossing and rotation behavior according to some quality criteria. Since the number of permutations is exponential, it is feasible to test all permutations only if there are no more than 7 nodes. Otherwise, the algorithm randomly generates some permutations and chooses the best one. The more permutations are chosen, the better the layout result.

CSS example: maxNumberOfPermutations : "2";

minBusyTime

public long minBusyTime

Sets the minimal time that the layout algorithm can be busy. This is the time between two calls of #layoutStepPerformed() when the method #callLayoutStepPerformedIfNeeded() is used.

The objective is to avoid the overhead of #layoutStepPerformed() becoming too high if the method is called too often. Internal routines of layout algorithms usually call #callLayoutStepPerformedIfNeeded(), which calls #layoutStepPerformed() if the time since the last call was at least the minimal busy time.

The default value is 50 (milliseconds).

CSS example: minBusyTime : "3";

minimumClusterSize

public int minimumClusterSize

Sets the minimum number of nodes to form a cluster. The value is obeyed for regular clusters, but not for star clusters.

The default value is 4.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

CSS example: minimumClusterSize : "2";

mixedClusterLinkCrossingPenalty

public double mixedClusterLinkCrossingPenalty

Sets the penalty for crossings of intra cluster links with inter cluster links. Links between nodes of the same cluster are called intra cluster links, while links connecting different clusters are called inter cluster links.

The default value is 1.

This parameter is used only if the clustering mode (see #setClusteringMode(int)) is #AUTOMATIC.

During the crossing reduction, intra cluster links compete with inter cluster links, since some node orderings of a cluster produce more crossings of links inside the cluster, while other node orderings produce more crossings of links connecting different clusters. The penalty allows to fine tune whether intra cluster links or inter cluster links are more important.

CSS example: mixedClusterLinkCrossingPenalty : "3.0";

offset

public double offset

Sets the offset value. The Circular Layout algorithm tries to ensure that the minimum distance between two nodes is approximately equal to the offset value.

The default value is 10.

CSS example: offset : "3.0";