ilog.views.graphlayout.uniformlengthedges

Class IlvUniformLengthEdgesLayout

java.lang.Object

ilog.views.graphlayout.IlvGraphLayout

ilog.views.graphlayout.basic.IlvBasicLinkStyleLayout

ilog.views.graphlayout.uniformlengthedges.IlvUniformLengthEdgesLayout

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

The main class for the Uniform Length Edges Layout algorithm.

The Uniform Length Edges Layout algorithm can be used to lay out any type of graph. It often provides a drawing with no, or only a few, edge crossings and with approximately equal-length edges for small- and medium-size graphs having a small number of cycles.

This layout algorithm iteratively searches for a configuration of the graph such that the lengths of the edges are close to a desired value.

Here are sample drawings produced with the Uniform Length Edges Layout algorithm:

Performance hints

Several parameters have an impact on speed. In some extent, the performance can be improved by modifying these parameters.

• Parameter with the largest impact on speed:
  • #setLayoutMode(int). The algorithm provides three modes with different tradeoffs between quality and speed. For details, please refer to documentation of this method.
• Parameters that allow to reduce the number of iterations that are executed:
  • #setPreferredLinksLength(double). The algorithm stops iterating when the length of all links is close to the specified "preferredLinksLength" parameter. If the preferred length is very high while the initial length of the links is small, reducing the preferred length is an indirect way to reduce the necessary number of iterations, hence to speed up.
  • #setAllowedTime(long). Reducing the allowed time is a way to force the completion of the layout quicker. However, the quality gets of course worst.
  • #setAllowedNumberOfIterations(int). Similar as for #setAllowedTime(long).
• Parameters that allow to reduce the time spent on each iteration:
  • #setRespectNodeSizes(boolean). If disabled, the algorithm is a bit quicker because it does not try to avoid overlaps between nodes. This is in particular possible, without quality degradation, when all the nodes have approximately the same size and have more or less a square shape. In such cases, specifying a "preferredLinksLength" high enough usually avoids overlaps even if "respectNodeSizes" is not enabled.
  • #setAnimate(boolean). For maximum performance, ensure the animation is not enabled (it is disabled by default). Enabling the animation is costly for large graphs (requires a grapher update and redraw at each iteration).
  • #setMaxAllowedMovePerIteration(double). This indicates the maximum distance the algorithm is allowed to move a node at each iteration. The higher the value, quicker the optimum may be reached, but also the algorithm may fail to converge (no "crash", just that the quality may be worst).

See the corresponding chapter of the JViews Graph Layout 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.

You can specify a preferred length for the links globally (#setPreferredLinksLength(double) or for specific links (#setPreferredLength(Object, double)).

You can request that the real size of the nodes is taken into account (#setRespectNodeSizes(boolean)). This is especially recommended when the nodes are not square (have a larger or smaller width than height), or have different sizes. In such a case, the layout quality can be often further improved by increasing the weight of the node repulsion force (see #setAdditionalNodeRepulsionWeight(double); the default is zero).

While the layout algorithm optionally restricts the region where the nodes are placed (see #setForceFitToLayoutRegion(boolean)), the layout quality is usually much better if this option is not used (this is the default behavior).

If this option is not set, the nodes are considered to be points located in the center of the bounding box of the nodes. Using the layout algorithm without setting this option is recommended when the width of the nodes is close to their height and there are no significant size differences among the nodes.

Note that, in the incremental mode (which is the default), the initial position of the nodes (at the moment you start the layout) is taken into account by the layout algorithm, so you may get different results depending on the initial position.

CSS example:

SDM {
GraphLayout : true;
}

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

Subobject#layout {
class : "ilog.views.graphlayout.uniformlengthedges.IlvUniformLengthEdgesLayout";
additionalNodeRepulsionWeight : "3.0";
allowedNumberOfIterations : "2";
convergenceThreshold : "3.0";
coordinatesMode : "MANAGER_COORDINATES";
forceFitToLayoutRegion : "false";
layoutMode : "INCREMENTAL_MODE";
layoutOfConnectedComponentsEnabled : "false";
linkLengthWeight : "3.0";
maxAllowedMovePerIteration : "3.0";
maxPercentageOfElapsedTimeForRefinement : "3.0";
maxPercentageOfTotalAllowedTimeForRefinement : "3.0";
maxRepeatForConvergence : "2";
minBusyTime : "3";
nodeDistanceThreshold : "3.0";
preferredLinksLength : "3.0";
respectNodeSizes : "false";
}

link.tag {
PreferredLength : "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. See also the documentation of the class IlvGraphLayoutRenderer.

Property Summary

Properties

Modifier and Type	Property and Description
double	additionalNodeRepulsionWeight Sets the weight of the additional node repulsion force.
int	allowedNumberOfIterations Sets the maximum number of iterations of the layout algorithm.
java.lang.String	class Default constructor.
double	convergenceThreshold Sets the threshold value for the convergence detection mechanism.
int	coordinatesMode Sets the coordinates mode to be used during layout.
boolean	forceFitToLayoutRegion Sets whether the layout algorithm must force the graph drawing to fit the layout region.
int	layoutMode Sets the layout mode.
boolean	layoutOfConnectedComponentsEnabled Sets whether the generic connected component layout mechanism is enabled.
double	linkLengthWeight Sets the link length weight.
double	maxAllowedMovePerIteration Sets the maximum authorized node move at each iteration of the layout algorithm.
double	maxPercentageOfElapsedTimeForRefinement Sets the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is #FAST_MULTILEVEL_MODE .
double	maxPercentageOfTotalAllowedTimeForRefinement Sets the maximum percentage of the total allowed time that should be spent on the final refinement step when the layout mode is #FAST_MULTILEVEL_MODE .
int	maxRepeatForConvergence Sets the maximum number of attempts to reach convergence at each step when the layout mode is #FAST_MULTILEVEL_MODE .
long	minBusyTime Sets the minimal time that the layout algorithm can be busy.
double	nodeDistanceThreshold Sets the node distance threshold.
double	PreferredLength Sets the preferred length of a link.
double	preferredLinksLength Sets the global preferred length of the links.
boolean	respectNodeSizes Sets whether the algorithm must try to respect the size of the nodes.

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

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

Method Summary

Methods inherited from class java.lang.Object

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

Property Detail

class

public java.lang.String class

Default constructor.

CSS example: class : "ilog.views.graphlayout.uniformlengthedges.IlvUniformLengthEdgesLayout";

additionalNodeRepulsionWeight

public double additionalNodeRepulsionWeight

Sets the weight of the additional node repulsion force. This weight is a multiplier which is applied to the repulsion force between two nodes that are not connected by a link. The additional repulsion force is applied only if the distance between the nodes is smaller than the node distance threshold (see #setNodeDistanceThreshold(double)).

The default value is 0.2. Increasing the weight increases the priority that is given to maintaining the nodes at a distance larger than the node distance threshold. However, increasing the weight decreases the ability of the algorithm to reach convergence quickly.

CSS example: additionalNodeRepulsionWeight : "3.0";

See Also:

linkLengthWeight

allowedNumberOfIterations

public int allowedNumberOfIterations

Sets the maximum number of iterations of the layout algorithm. The default value is 1000.

CSS example: allowedNumberOfIterations : "2";

convergenceThreshold

public double convergenceThreshold

Sets the threshold value for the convergence detection mechanism. The iterative algorithm is stopped if the greatest movement of a node at an iteration #getMaxAllowedMovePerIteration() is smaller than threshold during several successive iterations.

The default value is 1. The units are in the same coordinate space as the coordinates and size of the nodes. Increasing this value may speed up the layout because the iterations may be stopped earlier. However, this may produce a nonoptimal layout. Decreasing this value in some cases improves the quality of the layout but needs more time because more iterations are performed. Note that if the specified value is too small, the iterations cannot be stopped until the allowed time or the allowed number of iterations is reached.

CSS example: convergenceThreshold : "3.0";

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

forceFitToLayoutRegion

public boolean forceFitToLayoutRegion

Sets whether the layout algorithm must force the graph drawing to fit the layout region. If the argument is false (which is the default), the layout algorithm is free to move nodes outside the layout region. Note that the layout may not be optimal if the size of the layout region is too small. It is recommended to avoid forcing the use of a layout region anytime this is possible.

CSS example: forceFitToLayoutRegion : "false";

layoutMode

public int layoutMode

Sets the layout mode. Valid values are:

• #INCREMENTAL_MODE - The algorithm starts from the current position and iteratively tries to converge towards the optimal layout. Thus, in some cases, this mode avoids a major reorganization of the graph, which helps to preserve the "mental map" of the user as much as possible. However, this approach is not guaranteed, and depends on how far the initial position of the nodes is from the position that satisfies the criteria of the algorithm.
• #NON_INCREMENTAL_MODE - The algorithm is free to reorganize the graph without trying to stay close to the initial positions. Often, the nonincremental mode is faster than the incremental mode, sometimes at the price of lower quality.
• #FAST_MULTILEVEL_MODE - The algorithm uses a multilevel graph decomposition strategy that usually leads to significant speed gain. In this mode, the behavior is nonincremental.

The default value is #INCREMENTAL_MODE .

CSS example: layoutMode : "INCREMENTAL_MODE";

Allowed values:
INCREMENTAL_MODE		Incremental
NON_INCREMENTAL_MODE		Non-incremental
FAST_MULTILEVEL_MODE		Fast multilevel

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";

linkLengthWeight

public double linkLengthWeight

Sets the link length weight. This weight is a multiplier that is applied when two nodes connected by a link are moved in order to obtain a link length close to the preferred value (see #setPreferredLinksLength(double) and #setPreferredLength(Object, double)). The default value is 1. Increasing (or decreasing) this value increases (or decreases) the priority that is given to the link length criteria with respect to the minimum distance between nodes not connected by a link.

CSS example: linkLengthWeight : "3.0";

See Also:

additionalNodeRepulsionWeight

maxAllowedMovePerIteration

public double maxAllowedMovePerIteration

Sets the maximum authorized node move at each iteration of the layout algorithm. The default value is 5.

Increasing this parameter may speed up the layout, but the algorithm may fail to converge. Decreasing this parameter slows down the layout but in some cases improves the convergence. You should not specify a zero value, because in this case the layout cannot move the nodes at all.

CSS example: maxAllowedMovePerIteration : "3.0";

See Also:

convergenceThreshold

maxPercentageOfElapsedTimeForRefinement

public double maxPercentageOfElapsedTimeForRefinement

Sets the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is #FAST_MULTILEVEL_MODE . The parameter has no effect in other layototut modes.

If the specified value is negative, the value 0 is used.

The default value is 1000 percent. That is, the refinement step should not take longer than 10 times the time already spent before this step.

Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

CSS example: maxPercentageOfElapsedTimeForRefinement : "3.0";

maxPercentageOfTotalAllowedTimeForRefinement

public double maxPercentageOfTotalAllowedTimeForRefinement

Sets the maximum percentage of the total allowed time that should be spent on the final refinement step when the layout mode is #FAST_MULTILEVEL_MODE . The parameter has no effect in other layout modes.

If the specified value is negative, the value 0 is used.

The default value is 1O percent. Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

CSS example: maxPercentageOfTotalAllowedTimeForRefinement : "3.0";

See Also:

maxRepeatForConvergence

maxRepeatForConvergence

public int maxRepeatForConvergence

Sets the maximum number of attempts to reach convergence at each step when the layout mode is #FAST_MULTILEVEL_MODE . The parameter has no effect in other layout modes.

If the specified value is less than 0, the value 1 is used.

The default value is 3. Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

CSS example: maxRepeatForConvergence : "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";

nodeDistanceThreshold

public double nodeDistanceThreshold

Sets the node distance threshold. The additional repulsion force (see #setAdditionalNodeRepulsionWeight(double)) is applied only for nodes that are not connected by a link and are at a distance smaller than this threshold.

The default value is 30.

Note that the additional repulsion force is applied only if the corresponding weight (see #setAdditionalNodeRepulsionWeight(double)) is larger than 0. The default weight is 0; therefore, the node distance threshold has no effect if the weight is not modified.

CSS example: nodeDistanceThreshold : "3.0";

See Also:

preferredLinksLength

PreferredLength

public double PreferredLength

Sets the preferred length of a link. The layout algorithm tries to compute a layout where the link has the specified length. If a preferred length is set for a link, this overrides the global preferred length for this link.

After having specified a length for a link, you can call the method with a strictly negative value to indicate that the global preferred length must be used again for this link.

By default, no length is specified for the individual links.

CSS example: PreferredLength : "3.0";

Important: This layout parameter applies to subsets of links. Therefore, the CSS declaration must be added to the corresponding CSS rule for links. Note also that the name of such layout parameters uses an initial capital, unlike the regular properties which hold for the entire content of the graph.

See Also:

preferredLinksLength, nodeDistanceThreshold

preferredLinksLength

public double preferredLinksLength

Sets the global preferred length of the links. The layout algorithm tries to compute a layout where the links have the specified length. The preferred length can also be specified individually for each link (or for some links). If an individual length is not specified for a particular link, the global length specified using this method is used for this link.

The default value is 60.

CSS example: preferredLinksLength : "3.0";

See Also:

nodeDistanceThreshold

respectNodeSizes

public boolean respectNodeSizes

Sets whether the algorithm must try to respect the size of the nodes. If the argument is true, the preferred length parameter is interpreted as a minimum distance between the bounding boxes of the end nodes. Otherwise, the preferred length parameter is considered as the center-to-center distance between the end nodes.

CSS example: respectNodeSizes : "false";