ilog.views.graphlayout.uniformlengthedges

Class IlvUniformLengthEdgesLayout

java.lang.Object

ilog.views.graphlayout.IlvGraphLayout

ilog.views.graphlayout.basic.IlvBasicLinkStyleLayout

ilog.views.graphlayout.uniformlengthedges.IlvUniformLengthEdgesLayout

All Implemented Interfaces:

GraphModelListener, Serializable, EventListener

public class IlvUniformLengthEdgesLayout
extends 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.
  • IlvGraphLayout.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 IlvGraphLayout.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.
  • IlvGraphLayout.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.

Since:

JViews 2.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	FAST_MULTILEVEL_MODE Fast multilevel layout mode.
static int	INCREMENTAL_MODE Incremental layout mode.
static int	NO_RESHAPE_STYLE No links reshape option.
static int	NON_INCREMENTAL_MODE Non-incremental layout mode.
static int	STRAIGHT_LINE_STYLE Straight-line links shape option.

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

ALL_CORNERS, BOTTOM_LEFT, BOTTOM_RIGHT, CENTERED, CLOCK_WISE, CONNECTED_ONE_BEND_BUNDLE, CONNECTED_RECTANGULAR, CONNECTED_SQUARE, COUNTER_CLOCK_WISE, FREE_ONE_BEND_BUNDLE, FREE_RECTANGULAR, FREE_SQUARE, HORIZONTAL_TO_VERTICAL, INNER, NARROW_CONNECTED_RECTANGULAR, NARROW_CONNECTED_SQUARE, NARROW_FREE_RECTANGULAR, NARROW_FREE_SQUARE, NARROW_STRAIGHT_LINE_BUNDLE, NO_BENDS, NO_BUNDLE, OUTER, STRAIGHT_LINE_BUNDLE, TOP_LEFT, TOP_RIGHT, VERTICAL_TO_HORIZONTAL

Fields inherited from class ilog.views.graphlayout.IlvGraphLayout

INVERSE_VIEW_COORDINATES, MANAGER_COORDINATES, VIEW_COORDINATES

Constructor Summary

Constructors

Constructor and Description
IlvUniformLengthEdgesLayout() Creates a new instance of the Uniform Length Edges Layout algorithm.
IlvUniformLengthEdgesLayout(IlvUniformLengthEdgesLayout source) Creates a new layout instance by copying an existing one.

Method Summary

Modifier and Type	Method and Description
IlvGraphLayout	copy() Copies the layout instance.
void	copyParameters(IlvGraphLayout source) Copies the parameters from a given layout instance.
protected IlvGraphLayoutGrapherProperty	createLayoutGrapherProperty(String name, boolean withDefaults) Returns a new instance of IlvUniformLengthEdgesLayoutGrapherProperty that stores the parameter settings of this layout class.
protected IlvGraphLayoutLinkProperty	createLayoutLinkProperty(String name, IlvGraphic link, boolean withDefaults) Returns a new instance of IlvUniformLengthEdgesLayoutLinkProperty that stores the parameter settings of this layout class for links.
IlvGraphLayoutReport	createLayoutReport() Creates the graph layout report instance.
void	detach() Detaches the graph model from the layout instance.
double	getAdditionalNodeRepulsionWeight() Returns the weight of the additional node repulsion force.
int	getAllowedNumberOfIterations() Returns the maximum number of allowed iterations.
double	getConvergenceThreshold() Returns the threshold value for the convergence detection mechanism.
protected int	getLayoutCodeOnInterrupt() Returns the layout code when the allowed time elapsed before completion of the layout.
int	getLayoutMode() Returns the current layout mode.
double	getLinkLengthWeight() Returns the link length weight.
double	getMaxAllowedMovePerIteration() Returns the maximum authorized move at each iteration of the layout algorithm.
double	getMaxPercentageOfElapsedTimeForRefinement() Returns 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	getMaxPercentageOfTotalAllowedTimeForRefinement() Returns the upper limit for the duration of the finetuning step in "fast multilevel" layout mode as percentage of the total allowed time.
int	getMaxRepeatForConvergence() Returns the maximum number of attempts to reach convergence at each step when the layout mode is FAST_MULTILEVEL_MODE .
double	getNodeDistanceThreshold() Returns the node distance threshold.
double	getPreferredLength(Object link) Returns the preferred length of a link; returns -1 if the length is unspecified (in this case, the layout uses the global length; see getPreferredLinksLength()).
double	getPreferredLinksLength() Returns the global preferred length of the links.
protected void	init() Initializes instance variables.
protected void	internalLayout(boolean redraw) Computes the layout using the Uniform Length Edges Layout algorithm.
boolean	isForceFitToLayoutRegion() Returns the current choice for the force-fit-to-layout-region parameter.
protected boolean	isInterrupted() Returns true if the layout is interrupted.
protected boolean	isLayoutOfConnectedComponentsEnabledByDefault() Overridden version of the method from the superclass that always returns true.
boolean	isRespectNodeSizes() Returns true if the algorithm tries to respect the size of the nodes.
void	setAdditionalNodeRepulsionWeight(double weight) Sets the weight of the additional node repulsion force.
void	setAllowedNumberOfIterations(int iterations) Sets the maximum number of iterations of the layout algorithm.
void	setConvergenceThreshold(double threshold) Sets the threshold value for the convergence detection mechanism.
void	setForceFitToLayoutRegion(boolean option) Sets whether the layout algorithm must force the graph drawing to fit the layout region.
void	setLayoutMode(int mode) Sets the layout mode.
void	setLinkLengthWeight(double weight) Sets the link length weight.
void	setMaxAllowedMovePerIteration(double maxMove) Sets the maximum authorized node move at each iteration of the layout algorithm.
void	setMaxPercentageOfElapsedTimeForRefinement(double percentage) 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 .
void	setMaxPercentageOfTotalAllowedTimeForRefinement(double percentage) 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 .
void	setMaxRepeatForConvergence(int repeat) Sets the maximum number of attempts to reach convergence at each step when the layout mode is FAST_MULTILEVEL_MODE .
void	setNodeDistanceThreshold(double threshold) Sets the node distance threshold.
void	setPreferredLength(Object link, double length) Sets the preferred length of a link.
void	setPreferredLinksLength(double length) Sets the global preferred length of the links.
void	setRespectNodeSizes(boolean respect) Sets whether the algorithm must try to respect the size of the nodes.
boolean	supportsAllowedTime() Indicates that this layout class can stop the layout computation when the user-defined allowed time is exceeded.
boolean	supportsAnimation() Indicates that this layout class supports the animation mechanism; that is, it performs a redraw of the grapher after each iteration if the method IlvGraphLayout.setAnimate(boolean) is called with a true argument.
boolean	supportsLayoutRegion() Indicates that this layout class can control the size of the graph drawing to fit (approximately) a user-defined region (a rectangle) or a user-defined manager view.
boolean	supportsPercentageComplete() Indicates that this layout class can not estimate the percentage of completion during the layout run.
boolean	supportsStopImmediately() Indicates that this layout class can interrupt the current run of the layout immediately in a controlled way.

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

checkAppropriateLink, checkAppropriateLinks, getLinkStyle, getMovingNodes, getMultiLinkMaxSpread, getMultiLinkMode, getMultiLinkOffset, getMultiLinksCount, getMultiSelfLinkDistribution, getMultiSelfLinkMaxSpread, getMultiSelfLinkOffset, getPercentagesOfCompletion, getSelfLinkAbsoluteAttachPosition, getSelfLinkAllowedCorners, getSelfLinkMode, getSelfLinkOrientation, getSelfLinkRelativeAttachPosition, getSelfLinksCount, getSelfLinkSpacing, increasePercentageComplete, isConnectLinksToNodeCenters, isSelfLinkConnectToNodeCenter, layout, setConnectLinksToNodeCenters, setLinkStyle, setMultiLinkMaxSpread, setMultiLinkMode, setMultiLinkOffset, setMultiSelfLinkDistribution, setMultiSelfLinkMaxSpread, setMultiSelfLinkOffset, setSelfLinkAbsoluteAttachPosition, setSelfLinkAllowedCorners, setSelfLinkConnectToNodeCenter, setSelfLinkMode, setSelfLinkOrientation, setSelfLinkRelativeAttachPosition, setSelfLinkSpacing, supportsLayoutOfConnectedComponents, supportsLinkClipping, supportsLinkConnectionBox, supportsPreserveFixedLinks, supportsPreserveFixedNodes, supportsSaveParametersToNamedProperties

Methods inherited from class ilog.views.graphlayout.IlvGraphLayout

addGraphLayoutEventListener, addGraphLayoutParameterEventListener, afterLayoutOfSubgraph, attach, attach, beforeLayout, beforeLayoutOfSubgraph, callLayoutStepPerformedIfNeeded, cleanGraphModel, cleanLink, cleanNode, clipAllLinks, clipLink, connectAllLinksToCenter, connectLinkToCenter, contentsChanged, createLayoutNodeProperty, getAllowedTime, getAutoLayoutHandler, getBalanceSplineCurveThreshold, getCalcLayoutRegion, getCoordinatesMode, getGrapher, getGraphModel, getInstanceId, getLayout, getLayoutOfConnectedComponents, getLayoutOfConnectedComponentsReport, getLayoutRegion, getLayoutReport, getLayouts, getLinkClipInterface, getLinkConnectionBoxInterface, getMaxSplineCurveSize, getMinBusyTime, getMinSplineCurveSize, getParentLayout, getProperty, getProperty, getRecursiveLayout, getRemainingAllowedTime, getSeedValueForRandomGenerator, getSpecLayoutRegion, getSplineLinkFilter, isAnimate, isAutoLayout, isFitToView, isFixed, isGeometryUpToDate, isInputCheckEnabled, isLayoutNeeded, isLayoutOfConnectedComponentsEnabled, isLayoutRunning, isLayoutRunning, isLayoutTimeElapsed, isLocalRecursiveLayoutNeeded, isMemorySavings, isParametersUpToDate, isPreserveFixedLinks, isPreserveFixedNodes, isSplineRoutingEnabled, isStoppedImmediately, isStructureUpToDate, isUseDefaultParameters, isUseSeedValueForRandomGenerator, layoutStepPerformed, onParameterChanged, onParameterChanged, performAutoLayout, performLayout, performLayout, performLayout, PerformLayout, performSublayout, removeGraphLayoutEventListener, removeGraphLayoutParameterEventListener, setAllowedTime, setAnimate, setAutoCheckAppropriateLinksEnabled, setAutoLayout, setAutoLayoutHandler, setBalanceSplineCurveThreshold, setCoordinatesMode, setFixed, setGeometryUpToDate, setGrapher, setGraphModel, setInputCheckEnabled, setLayoutOfConnectedComponents, setLayoutOfConnectedComponentsEnabled, setLayoutRegion, setLayoutRegion, setLayoutRegion, setLayoutReport, setLayoutRunning, setLinkClipInterface, setLinkConnectionBoxInterface, setMaxSplineCurveSize, setMemorySavings, setMinBusyTime, setMinSplineCurveSize, setParametersUpToDate, setParentLayout, setPreserveFixedLinks, setPreserveFixedNodes, setProperty, setProperty, setSeedValueForRandomGenerator, setSplineLinkFilter, setSplineRoutingEnabled, setStructureUpToDate, setUseDefaultParameters, setUseSeedValueForRandomGenerator, stopImmediately, supportsMemorySavings, supportsRandomGenerator, supportsSplineRouting, unfixAllLinks, unfixAllNodes, useAnimateRedraw

Methods inherited from class java.lang.Object

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

Field Detail

INCREMENTAL_MODE

public static final int INCREMENTAL_MODE

Incremental layout mode. When used as an argument of setLayoutMode(int), the layout is executed in incremental mode. For details, see setLayoutMode(int).

Since:

JViews 8.5

See Also:

setLayoutMode(int), Constant Field Values

NON_INCREMENTAL_MODE

public static final int NON_INCREMENTAL_MODE

Non-incremental layout mode. When used as an argument of setLayoutMode(int), the layout is executed in nonincremental mode. For details, see setLayoutMode(int).

Since:

JViews 8.5

See Also:

setLayoutMode(int), Constant Field Values

FAST_MULTILEVEL_MODE

public static final int FAST_MULTILEVEL_MODE

Fast multilevel layout mode. When used as an an argument of setLayoutMode(int), the layout is executed in fast multilevel mode. For details, see setLayoutMode(int).

Since:

JViews 8.5

See Also:

setLayoutMode(int), Constant Field Values

STRAIGHT_LINE_STYLE

public static final int STRAIGHT_LINE_STYLE

Straight-line links shape option. When used as an argument of IlvBasicLinkStyleLayout.setLinkStyle(int), the links are given a straight-line shape.

See Also:

IlvBasicLinkStyleLayout.setLinkStyle(int), Constant Field Values

NO_RESHAPE_STYLE

public static final int NO_RESHAPE_STYLE

No links reshape option. When used as an argument of IlvBasicLinkStyleLayout.setLinkStyle(int), the links are not reshaped.

See Also:

IlvBasicLinkStyleLayout.setLinkStyle(int), Constant Field Values

Constructor Detail

IlvUniformLengthEdgesLayout

public IlvUniformLengthEdgesLayout()

Creates a new instance of the Uniform Length Edges Layout algorithm.
To indicate the grapher you want to lay out, use the method IlvGraphLayout.attach(ilog.views.IlvGrapher).
To indicate the graph model you want to lay out, use the method IlvGraphLayout.attach(IlvGraphModel).
To perform the layout, use the method IlvGraphLayout.performLayout().
To modify the layout parameters, use the different methods provided in this class and its superclass.

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), IlvGraphLayout.attach(ilog.views.graphlayout.IlvGraphModel), IlvGraphLayout.performLayout(), IlvGrapherAdapter.addLayer(ilog.views.IlvManagerLayer), IlvGrapherAdapter.setFilter(ilog.views.graphlayout.IlvLayoutGraphicFilter)

IlvUniformLengthEdgesLayout

public IlvUniformLengthEdgesLayout(IlvUniformLengthEdgesLayout source)

Creates a new layout instance by copying an existing one. This constructor is used by the copy() method. Any subclass should provide a copy constructor.

The parameters of the source layout are copied using the method copyParameters(IlvGraphLayout).

Parameters:

source - The layout instance that is copied.

Since:

JViews 5.0

See Also:

copy(), copyParameters(IlvGraphLayout)

Method Detail

init

protected void init()

Initializes instance variables.

You should not call this method directly. The method is called internally by the constructor without arguments and by the copy constructor. The method must be overridden by subclasses that need to initialize additional instance variables.

Overrides:

init in class IlvBasicLinkStyleLayout

Since:

JViews 5.0

copy

public IlvGraphLayout copy()

Copies the layout instance.

This method copies the layout instance by calling the copy constructor.

When performing a recursive layout of a nested graph, this method is used by IlvLayoutProvider to "clone" the layout instance of a parent graph.

Note that the parameters which are specific to a node or a link are not copied. The other parameters, including the layout region specification and the customization interfaces, are also copied. A copy of the layout instance used for laying out the connected components is set on the new instance.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

Overrides:

copy in class IlvBasicLinkStyleLayout

Returns:

A copy of the layout instance.

Since:

JViews 5.0

copyParameters

public void copyParameters(IlvGraphLayout source)

Copies the parameters from a given layout instance.

Note that the parameters which are specific to a node or a link are not copied. The other parameters, including the layout region specification and the customization interfaces, are also copied. A copy of the layout instance used for laying out the connected components is set on this layout instance.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

Overrides:

copyParameters in class IlvBasicLinkStyleLayout

Parameters:

source - The layout instance from which the parameters are copied.

Since:

JViews 5.0

See Also:

copy()

detach

public void detach()

Detaches the graph model from the layout instance. When you attach a new graph model to the layout instance, you do not need to detach the old graph model because this is done automatically when you call IlvGraphLayout.attach(IlvGraphModel).

The method performs cleaning operations on the graph model.

Note that you must call this method when you no longer need the layout instance. Otherwise, some objects may not be garbage collected.

Overrides:

detach in class IlvGraphLayout

See Also:

IlvGraphLayout.attach(IlvGraphModel)

createLayoutReport

public IlvGraphLayoutReport createLayoutReport()

Creates the graph layout report instance.

Overrides:

createLayoutReport in class IlvGraphLayout

Returns:

A new instance of graph layout report. The current implementation creates an instance of IlvUniformLengthEdgesLayoutReport.

See Also:

IlvUniformLengthEdgesLayoutReport, createLayoutReport()

isLayoutOfConnectedComponentsEnabledByDefault

protected boolean isLayoutOfConnectedComponentsEnabledByDefault()

Overridden version of the method from the superclass that always returns true.

Overrides:

isLayoutOfConnectedComponentsEnabledByDefault in class IlvGraphLayout

Returns:

true

Since:

JViews 3.5

See Also:

IlvGraphLayout.setLayoutOfConnectedComponentsEnabled(boolean)

supportsAllowedTime

public final boolean supportsAllowedTime()

Indicates that this layout class can stop the layout computation when the user-defined allowed time is exceeded. The result code in the layout report is IlvGraphLayoutReport.STOPPED_AND_VALID in this case.

Overrides:

supportsAllowedTime in class IlvBasicLinkStyleLayout

Returns:

Always true.

See Also:

IlvGraphLayout.setAllowedTime(long), IlvGraphLayout.getAllowedTime(), IlvGraphLayoutReport.getCode()

supportsStopImmediately

public final boolean supportsStopImmediately()

Indicates that this layout class can interrupt the current run of the layout immediately in a controlled way. The result code in the layout report is IlvGraphLayoutReport.STOPPED_AND_VALID in this case.

Overrides:

supportsStopImmediately in class IlvBasicLinkStyleLayout

Returns:

Always true.

See Also:

IlvGraphLayout.stopImmediately(), IlvGraphLayout.isStoppedImmediately(), IlvGraphLayoutReport.getCode()

supportsLayoutRegion

public final boolean supportsLayoutRegion()

Indicates that this layout class can control the size of the graph drawing to fit (approximately) a user-defined region (a rectangle) or a user-defined manager view. By default, this feature is disabled. To enable it, use the method setForceFitToLayoutRegion(boolean).

Overrides:

supportsLayoutRegion in class IlvGraphLayout

Returns:

Always true.

See Also:

setForceFitToLayoutRegion(boolean), IlvGraphLayout.setLayoutRegion(ilog.views.IlvManagerView), IlvGraphLayout.setLayoutRegion(ilog.views.IlvManagerView, ilog.views.IlvRect), IlvGraphLayout.setLayoutRegion(ilog.views.IlvRect), IlvGraphLayout.getSpecLayoutRegion(), IlvGraphLayout.getCalcLayoutRegion()

supportsAnimation

public final boolean supportsAnimation()

Indicates that this layout class supports the animation mechanism; that is, it performs a redraw of the grapher after each iteration if the method IlvGraphLayout.setAnimate(boolean) is called with a true argument.

Overrides:

supportsAnimation in class IlvGraphLayout

Returns:

Always true.

See Also:

IlvGraphLayout.setAnimate(boolean), IlvGraphLayout.isAnimate()

supportsPercentageComplete

public final boolean supportsPercentageComplete()

Indicates that this layout class can not estimate the percentage of completion during the layout run.

Overrides:

supportsPercentageComplete in class IlvBasicLinkStyleLayout

Returns:

Always false.

See Also:

IlvBasicLinkStyleLayout.increasePercentageComplete(int), IlvGraphLayoutReport.getPercentageComplete(), IlvJGraphLayoutProgressBar

internalLayout

protected void internalLayout(boolean redraw)
                       throws IlvGraphLayoutException

Computes the layout using the Uniform Length Edges Layout algorithm. To start the layout, call the method IlvGraphLayout.performLayout(). Note that this class overrides the createLayoutReport() and creates an instance of IlvUniformLengthEdgesLayoutReport.

Overrides:

internalLayout in class IlvBasicLinkStyleLayout

Throws:

IlvInappropriateLinkException - if the grapher contains links that cannot be reshaped to a straight line and the link style is STRAIGHT_LINE_STYLE. (For details, see IlvInappropriateLinkException.)

IlvGraphLayoutException

See Also:

IlvGraphLayout.performLayout(), createLayoutReport(), IlvUniformLengthEdgesLayoutReport, IlvGraphLayout.getCalcLayoutRegion()

isInterrupted

protected boolean isInterrupted()

Returns true if the layout is interrupted.

Overrides:

isInterrupted in class IlvBasicLinkStyleLayout

Returns:

true if the layout is interrupted.

getLayoutCodeOnInterrupt

protected int getLayoutCodeOnInterrupt()

Returns the layout code when the allowed time elapsed before completion of the layout.

Overrides:

getLayoutCodeOnInterrupt in class IlvBasicLinkStyleLayout

Returns:

IlvGraphLayoutReport.STOPPED_AND_VALID

See Also:

supportsAllowedTime(), supportsStopImmediately()

setConvergenceThreshold

public final void setConvergenceThreshold(double threshold)

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.

Since:

JViews 3.5

See Also:

getConvergenceThreshold()

getConvergenceThreshold

public final double getConvergenceThreshold()

Returns the threshold value for the convergence detection mechanism.

Since:

JViews 3.5

See Also:

setConvergenceThreshold(double)

setMaxAllowedMovePerIteration

public final void setMaxAllowedMovePerIteration(double maxMove)

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.

Since:

JViews 5.0

See Also:

getMaxAllowedMovePerIteration(), setConvergenceThreshold(double)

getMaxAllowedMovePerIteration

public final double getMaxAllowedMovePerIteration()

Returns the maximum authorized move at each iteration of the layout algorithm.

Since:

JViews 5.0

See Also:

setMaxAllowedMovePerIteration(double), setConvergenceThreshold(double)

setForceFitToLayoutRegion

public void setForceFitToLayoutRegion(boolean option)

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.

See Also:

IlvGraphLayout.setLayoutRegion(ilog.views.IlvManagerView), IlvGraphLayout.setLayoutRegion(ilog.views.IlvManagerView, ilog.views.IlvRect), IlvGraphLayout.setLayoutRegion(ilog.views.IlvRect), isForceFitToLayoutRegion(), IlvGraphLayout.getCalcLayoutRegion()

isForceFitToLayoutRegion

public boolean isForceFitToLayoutRegion()

Returns the current choice for the force-fit-to-layout-region parameter.

See Also:

setForceFitToLayoutRegion(boolean), IlvGraphLayout.getCalcLayoutRegion()

setPreferredLinksLength

public void setPreferredLinksLength(double length)

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.

See Also:

getPreferredLinksLength(), setPreferredLength(Object, double), setNodeDistanceThreshold(double)

getPreferredLinksLength

public double getPreferredLinksLength()

Returns the global preferred length of the links.

See Also:

setPreferredLinksLength(double), setPreferredLength(Object, double), setNodeDistanceThreshold(double)

setPreferredLength

public void setPreferredLength(Object link,
                               double length)

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.

Parameters:

link - The link instance.

length - The preferred length of the link.

Since:

JViews 5.0

See Also:

getPreferredLength(Object), setPreferredLinksLength(double), setNodeDistanceThreshold(double)

getPreferredLength

public double getPreferredLength(Object link)

Returns the preferred length of a link; returns -1 if the length is unspecified (in this case, the layout uses the global length; see getPreferredLinksLength()).

Parameters:

link - The link instance.

Returns:

The preferred length of a link, if one is specified; or -1 if the layout uses the global length.

Since:

JViews 5.0

See Also:

setPreferredLength(Object, double), setPreferredLinksLength(double), setNodeDistanceThreshold(double)

setLayoutMode

public void setLayoutMode(int mode)

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 .

Since:

JViews 8.5

See Also:

getLayoutMode()

getLayoutMode

public int getLayoutMode()

Returns the current layout mode.

Since:

JViews 8.5

See Also:

setLayoutMode(int)

setNodeDistanceThreshold

public void setNodeDistanceThreshold(double threshold)

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.

Since:

JViews 5.0

See Also:

getNodeDistanceThreshold(), setPreferredLinksLength(double), setPreferredLength(Object, double)

getNodeDistanceThreshold

public double getNodeDistanceThreshold()

Returns the node distance threshold.

Since:

JViews 5.0

See Also:

setNodeDistanceThreshold(double), setPreferredLinksLength(double), setPreferredLength(Object, double)

setRespectNodeSizes

public void setRespectNodeSizes(boolean respect)

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.

Since:

JViews 3.0

See Also:

isRespectNodeSizes()

isRespectNodeSizes

public boolean isRespectNodeSizes()

Returns true if the algorithm tries to respect the size of the nodes.

Since:

JViews 3.0

See Also:

setRespectNodeSizes(boolean)

setLinkLengthWeight

public void setLinkLengthWeight(double weight)

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.

Since:

JViews 5.0

See Also:

getLinkLengthWeight(), setAdditionalNodeRepulsionWeight(double)

getLinkLengthWeight

public double getLinkLengthWeight()

Returns the link length weight.

Since:

JViews 5.0

See Also:

setLinkLengthWeight(double), setAdditionalNodeRepulsionWeight(double)

setAdditionalNodeRepulsionWeight

public void setAdditionalNodeRepulsionWeight(double weight)

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.

Since:

JViews 5.0

See Also:

getAdditionalNodeRepulsionWeight(), setNodeDistanceThreshold(double), setLinkLengthWeight(double)

getAdditionalNodeRepulsionWeight

public double getAdditionalNodeRepulsionWeight()

Returns the weight of the additional node repulsion force.

Since:

JViews 5.0

See Also:

setAdditionalNodeRepulsionWeight(double), setLinkLengthWeight(double)

getAllowedNumberOfIterations

public int getAllowedNumberOfIterations()

Returns the maximum number of allowed iterations.

See Also:

setAllowedNumberOfIterations(int)

setAllowedNumberOfIterations

public void setAllowedNumberOfIterations(int iterations)

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

See Also:

getAllowedNumberOfIterations()

setMaxPercentageOfElapsedTimeForRefinement

public void setMaxPercentageOfElapsedTimeForRefinement(double percentage)

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.

Since:

JViews 8.7

See Also:

getMaxPercentageOfElapsedTimeForRefinement(), setMaxPercentageOfTotalAllowedTimeForRefinement(double), setLayoutMode(int)

getMaxPercentageOfElapsedTimeForRefinement

public double getMaxPercentageOfElapsedTimeForRefinement()

Returns 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 .

Since:

JViews 8.7

See Also:

setMaxPercentageOfElapsedTimeForRefinement(double)

setMaxPercentageOfTotalAllowedTimeForRefinement

public void setMaxPercentageOfTotalAllowedTimeForRefinement(double percentage)

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.

Since:

JViews 8.7

See Also:

getMaxPercentageOfTotalAllowedTimeForRefinement(), setMaxPercentageOfElapsedTimeForRefinement(double), IlvGraphLayout.getAllowedTime(), setLayoutMode(int)

getMaxPercentageOfTotalAllowedTimeForRefinement

public double getMaxPercentageOfTotalAllowedTimeForRefinement()

Returns the upper limit for the duration of the finetuning step in "fast multilevel" layout mode as percentage of the total allowed time.

Since:

JViews 8.7

See Also:

setMaxRepeatForConvergence(int)

setMaxRepeatForConvergence

public void setMaxRepeatForConvergence(int repeat)

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.

Since:

JViews 8.7

See Also:

getMaxRepeatForConvergence(), setMaxPercentageOfElapsedTimeForRefinement(double), setMaxPercentageOfTotalAllowedTimeForRefinement(double), setLayoutMode(int)

getMaxRepeatForConvergence

public int getMaxRepeatForConvergence()

Returns the maximum number of attempts to reach convergence at each step when the layout mode is FAST_MULTILEVEL_MODE .

Since:

JViews 8.7

See Also:

setMaxRepeatForConvergence(int)

createLayoutGrapherProperty

protected IlvGraphLayoutGrapherProperty createLayoutGrapherProperty(String name,
                                                                    boolean withDefaults)

Returns a new instance of IlvUniformLengthEdgesLayoutGrapherProperty that stores the parameter settings of this layout class.

The method is used by IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean) to create a named property that contains parameter settings of this layout instance.

Overrides:

createLayoutGrapherProperty in class IlvBasicLinkStyleLayout

Since:

JViews 3.5

See Also:

IlvGraphLayoutGrapherProperty, IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean), IlvGrapherAdapter.loadParametersFromNamedProperties(IlvGraphLayout), IlvGrapherAdapter.removeParametersFromNamedProperties()

createLayoutLinkProperty

protected IlvGraphLayoutLinkProperty createLayoutLinkProperty(String name,
                                                              IlvGraphic link,
                                                              boolean withDefaults)

Returns a new instance of IlvUniformLengthEdgesLayoutLinkProperty that stores the parameter settings of this layout class for links.

The method is used by IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean) to create a named property for a link that contains parameter settings of this layout instance for the input link.

Overrides:

createLayoutLinkProperty in class IlvGraphLayout

Since:

JViews 5.0

See Also:

IlvGraphLayoutLinkProperty, IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean), IlvGrapherAdapter.loadParametersFromNamedProperties(IlvGraphLayout), IlvGrapherAdapter.removeParametersFromNamedProperties()