ilog.views.graphlayout.springembedder
Class IlvSpringEmbedderLayout

java.lang.Object
  ilog.views.graphlayout.IlvGraphLayout
      ilog.views.graphlayout.springembedder.IlvSpringEmbedderLayout

All Implemented Interfaces:

GraphModelListener, Serializable, EventListener

public class IlvSpringEmbedderLayout
extends IlvGraphLayout

The main class for the Spring Embedder Layout algorithm.

The Spring Embedder Layout algorithm can be used to lay out any type of graph. It often provides a drawing with no edge crossings or few edge crossings for small- and medium-sized graphs. The nodes are placed inside a rectangle which is controlled by the layoutRegion parameter. It is important to specify a layout region that is in proportion to the number and size of the nodes.

This algorithm is based on an analogy between graph drawings and mechanical systems: Nodes correspond to point masses and edges correspond to springs. Attractive and repulsive forces between each pair of nodes are defined depending on the distance between the nodes and the connectivity of the graph. The algorithm searches a sort of minimal-energy configuration of the graph, computing iteratively the positions of the nodes.

Sample drawings produced with the Spring Embedder algorithm:

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.

Note that 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 with a true argument.

See Also:

IlvUniformLengthEdgesLayout, Serialized Form

Field Summary

static int	NO_RESHAPE_STYLE No links reshape option.
static int	STRAIGHT_LINE_STYLE Straight-line links shape option.

Fields inherited from class ilog.views.graphlayout.IlvGraphLayout

INVERSE_VIEW_COORDINATES, MANAGER_COORDINATES, VIEW_COORDINATES

Constructor Summary

IlvSpringEmbedderLayout()
Creates a new instance of the Spring Embedder layout algorithm.

IlvSpringEmbedderLayout(IlvSpringEmbedderLayout source)
Creates a new layout instance by copying an existing one.

Method Summary

int	checkAppropriateLink(Object link) Checks whether the input link is appropriate for this layout.
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 IlvSpringEmbedderLayoutGrapherProperty that stores the parameter settings of this layout class.
int	getLinkStyle() Returns the current option for the style of the shape of the links.
IlvGraphicVector	getMovingNodes() Returns the vector of nodes being moved by the graph layout algorithm.
float	getSpringConstant() Returns the current spring constant.
protected void	init() Initializes instance variables.
protected boolean	isLayoutOfConnectedComponentsEnabledByDefault() Overridden version of the method from the superclass that always returns true.
protected void	layout(boolean redraw) Computes the layout using the Spring Embedder algorithm.
void	setLinkStyle(int style) Sets the style of the shape of the links.
void	setSpringConstant(float constant) Sets the constant for the springs.
boolean	supportsAllowedTime() Indicates that this layout class can stop the layout computation in a proper manner 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 setAnimate(boolean) is called with a true argument.
boolean	supportsLayoutOfConnectedComponents() Indicates that this layout class can cut the attached graph into connected components, apply itself to each connected component separately, and then use the layout instance returned by the method IlvGraphLayout.getLayoutOfConnectedComponents() to place the connected components.
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	supportsLinkClipping() Indicates that this layout class can use a link clip interface to clip the end points of a link.
boolean	supportsLinkConnectionBox() Indicates that this layout class can use a link connection box interface to calculate the end points of a link.
boolean	supportsMemorySavings() Indicates that this layout class can perform the layout using two partially different implementations: one that gives priority to speed, the other that gives priority to memory usage.
boolean	supportsPercentageComplete() Indicates that this layout class can determine the percentage of completion during the run of layout.
boolean	supportsPreserveFixedNodes() Indicates that this layout class allows the user to specify fixed nodes.
boolean	supportsRandomGenerator() Indicates that this layout class uses randomly generated numbers that can be initialized with a user-defined seed value.
boolean	supportsSaveParametersToNamedProperties() Indicates that this layout class can transfer the layout parameters to named properties.
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.IlvGraphLayout

addGraphLayoutEventListener, addGraphLayoutParameterEventListener, afterLayoutOfSubgraph, attach, attach, beforeLayout, beforeLayoutOfSubgraph, callLayoutStepPerformedIfNeeded, checkAppropriateLinks, cleanGraphModel, cleanLink, cleanNode, clipAllLinks, clipLink, contentsChanged, createLayoutLinkProperty, createLayoutNodeProperty, createLayoutReport, detach, 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, increasePercentageComplete, isAnimate, isAutoLayout, isFitToView, isFixed, isGeometryUpToDate, isInputCheckEnabled, isLayoutNeeded, isLayoutOfConnectedComponentsEnabled, isLayoutRunning, isLayoutTimeElapsed, isMemorySavings, isParametersUpToDate, isPreserveFixedLinks, isPreserveFixedNodes, isSplineRoutingEnabled, isStoppedImmediately, isStructureUpToDate, isUseDefaultParameters, isUseSeedValueForRandomGenerator, layoutStepPerformed, onParameterChanged, onParameterChanged, performAutoLayout, performLayout, performLayout, performLayout, PerformLayout, performSublayout, removeGraphLayoutEventListener, removeGraphLayoutParameterEventListener, setAllowedTime, setAnimate, setAutoLayout, setAutoLayoutHandler, setBalanceSplineCurveThreshold, setCoordinatesMode, setFixed, setGeometryUpToDate, setGrapher, setGraphModel, setInputCheckEnabled, setLayoutOfConnectedComponents, setLayoutOfConnectedComponentsEnabled, setLayoutRegion, setLayoutRegion, setLayoutRegion, setLayoutReport, setLinkClipInterface, setLinkConnectionBoxInterface, setMaxSplineCurveSize, setMemorySavings, setMinBusyTime, setMinSplineCurveSize, setParametersUpToDate, setParentLayout, setPreserveFixedLinks, setPreserveFixedNodes, setProperty, setProperty, setSeedValueForRandomGenerator, setSplineLinkFilter, setSplineRoutingEnabled, setStructureUpToDate, setUseDefaultParameters, setUseSeedValueForRandomGenerator, stopImmediately, supportsPreserveFixedLinks, supportsSplineRouting, unfixAllLinks, unfixAllNodes, useAnimateRedraw

Methods inherited from class java.lang.Object

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

Field Detail

STRAIGHT_LINE_STYLE

public static final int STRAIGHT_LINE_STYLE

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

Since:

JViews 3.0

See Also:

Constant Field Values

NO_RESHAPE_STYLE

public static final int NO_RESHAPE_STYLE

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

Since:

JViews 3.0

See Also:

Constant Field Values

Constructor Detail

IlvSpringEmbedderLayout

public IlvSpringEmbedderLayout()

Creates a new instance of the Spring Embedder layout algorithm.
To indicate the grapher you want to lay out, use the method IlvGraphLayout.attach(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)

IlvSpringEmbedderLayout

public IlvSpringEmbedderLayout(IlvSpringEmbedderLayout 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(ilog.views.graphlayout.IlvGraphLayout).

Parameters:

source - The layout instance that is copied.

Since:

JViews 5.0

See Also:

copy(), copyParameters(ilog.views.graphlayout.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 IlvGraphLayout

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 link clip and link connection box 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.

Specified by:

copy in class IlvGraphLayout

Returns:

A copy of the layout instance.

Since:

JViews 5.0

See Also:

copyParameters(ilog.views.graphlayout.IlvGraphLayout)

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 IlvGraphLayout

Parameters:

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

Since:

JViews 5.0

See Also:

copy()

isLayoutOfConnectedComponentsEnabledByDefault

protected boolean isLayoutOfConnectedComponentsEnabledByDefault()

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

Overrides:

isLayoutOfConnectedComponentsEnabledByDefault in class IlvGraphLayout

Since:

JViews 3.5

See Also:

IlvGraphLayout.setLayoutOfConnectedComponentsEnabled(boolean)

supportsPreserveFixedNodes

public final boolean supportsPreserveFixedNodes()

Indicates that this layout class allows the user to specify fixed nodes. Fixed nodes are not moved during the layout if the method setPreserveFixedNodes(boolean) is called with a true argument.

Overrides:

supportsPreserveFixedNodes in class IlvGraphLayout

Returns:

Always true

See Also:

IlvGraphLayout.setPreserveFixedNodes(boolean), IlvGraphLayout.isPreserveFixedNodes()

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.

Overrides:

supportsLayoutRegion in class IlvGraphLayout

Returns:

Always true

See Also:

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

supportsRandomGenerator

public final boolean supportsRandomGenerator()

Indicates that this layout class uses randomly generated numbers that can be initialized with a user-defined seed value. When you perform the layout several times on the same graph and use the same user-defined seed value, you obtain the same drawing of the grapher. If you want different drawings each time you perform the layout, you should modify the seed value and call the method useSeedValueForRandomGenerator with a true argument.

Overrides:

supportsRandomGenerator in class IlvGraphLayout

Returns:

Always true

See Also:

IlvGraphLayout.setSeedValueForRandomGenerator(long), IlvGraphLayout.getSeedValueForRandomGenerator(), IlvGraphLayout.setUseSeedValueForRandomGenerator(boolean), IlvGraphLayout.isUseSeedValueForRandomGenerator()

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 setAnimate(boolean) is called with a true argument.

Overrides:

supportsAnimation in class IlvGraphLayout

Returns:

Always true

See Also:

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

supportsMemorySavings

public final boolean supportsMemorySavings()

Indicates that this layout class can perform the layout using two partially different implementations: one that gives priority to speed, the other that gives priority to memory usage. The choice depends on the parameter specified using IlvGraphLayout.setMemorySavings(boolean).
You should use the memory savings mode if memory is critical for your application or if you received an "out of memory" error on a large graph.
Note that no guarantee is given for the amount of memory savings and that the layout process can be slower.

Overrides:

supportsMemorySavings in class IlvGraphLayout

Returns:

Always true

See Also:

IlvGraphLayout.setMemorySavings(boolean), IlvGraphLayout.isMemorySavings()

supportsAllowedTime

public final boolean supportsAllowedTime()

Indicates that this layout class can stop the layout computation in a proper manner 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 IlvGraphLayout

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 IlvGraphLayout

Returns:

Always true

Since:

JViews 3.5

See Also:

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

supportsPercentageComplete

public final boolean supportsPercentageComplete()

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

Overrides:

supportsPercentageComplete in class IlvGraphLayout

Returns:

Always true

Since:

JViews 3.5

See Also:

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

supportsLayoutOfConnectedComponents

public final boolean supportsLayoutOfConnectedComponents()

Indicates that this layout class can cut the attached graph into connected components, apply itself to each connected component separately, and then use the layout instance returned by the method IlvGraphLayout.getLayoutOfConnectedComponents() to place the connected components. By default, this layout is an instance of IlvGridLayout that can be customized as needed.

Overrides:

supportsLayoutOfConnectedComponents in class IlvGraphLayout

Returns:

Always true

Since:

JViews 3.5

See Also:

IlvGraphLayout.getLayoutOfConnectedComponents(), IlvGraphLayout.isLayoutOfConnectedComponentsEnabled(), IlvGraphLayout.performLayout(boolean, boolean)

supportsLinkConnectionBox

public final boolean supportsLinkConnectionBox()

Indicates that this layout class can use a link connection box interface to calculate the end points of a link. The link connection box interface is an object that provides the rectangle to which the links are connected for each node and the tangential shift offset at each side for the connection points.

The connection box interface is used only if link clipping is enabled by setting a link clip interface and if the link style is straight line. In this case, the layout algorithm calculates the virtual center of the end nodes of each link by the link connection box interface and obtains the final connection points by clipping with the link clip interface. The virtual center is defined as the center of the connection box shifted by the average of the tangential "top" and "bottom" offset in the horizontal direction and by the average of the tangential "left" and "right" offset in the vertical direction. For instance, if the tangential offset is 20 at the top side and 10 at all other sides, the average shift offset is (20 + 10)/2 = 15 in the horizontal direction and (10 + 10)/2 = 10 in the vertical direction, hence the virtual center is at connectionBox.center() + (15, 10).

If no link clipping is performed, the layout algorithm does not actively place the end points of links. It relies on the link connectors that are attached to the nodes to find appropriate connection points for the links.

Overrides:

supportsLinkConnectionBox in class IlvGraphLayout

Returns:

Always true.

Since:

JViews 5.0

See Also:

IlvGraphLayout.setLinkConnectionBoxInterface(ilog.views.graphlayout.IlvLinkConnectionBoxInterface), IlvGraphLayout.setLinkClipInterface(ilog.views.graphlayout.IlvLinkClipInterface), IlvLinkConnector, setLinkStyle(int), supportsLinkClipping()

supportsLinkClipping

public final boolean supportsLinkClipping()

Indicates that this layout class can use a link clip interface to clip the end points of a link. The link clip interface is an object that provides the connection for a link clipped at the border of the shape of the end node. This is useful if the nodes have a nonrectangular shape such as a triangle, rhombus, or circle.

Link clipping is performed only if the link style is straight line. If no link clip interface is given, the layout algorithm does not actively place the end points of links. It relies on the link connectors that are attached to the nodes to find appropriate connection points for the links.

Overrides:

supportsLinkClipping in class IlvGraphLayout

Returns:

Always true.

Since:

JViews 5.0

See Also:

IlvGraphLayout.setLinkClipInterface(ilog.views.graphlayout.IlvLinkClipInterface), IlvLinkConnector, setLinkStyle(int), supportsLinkConnectionBox()

supportsSaveParametersToNamedProperties

public final boolean supportsSaveParametersToNamedProperties()

Indicates that this layout class can transfer the layout parameters to named properties. This mechanism can be used if layout parameters must be stored persistently in an .ivl file.

Overrides:

supportsSaveParametersToNamedProperties in class IlvGraphLayout

Returns:

Always true

Since:

JViews 3.5

See Also:

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

layout

protected void layout(boolean redraw)
               throws IlvGraphLayoutException

Computes the layout using the Spring Embedder algorithm. To start the layout, call the method IlvGraphLayout.performLayout().

Specified by:

layout in class IlvGraphLayout

Parameters:

redraw - If true, the attached graph model will be asked to redraw the graph after layout. When the layout algorithm moves the nodes and reshapes the links, it is required to pass the value of the redraw argument to the methods IlvGraphModel.moveNode(java.lang.Object, float, float, boolean) and IlvGraphModel.reshapeLink(java.lang.Object, ilog.views.IlvPoint, ilog.views.IlvPoint[], int, int, ilog.views.IlvPoint, boolean).

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 - If an unusual situation occurs. WARNING: this method can throw one of the subclasses of IlvGraphLayoutException. Specifically, it can throw an IlvInappropriateGraphException. It can also throw an IlvInappropriateLinkException when inappropriate types of links and/or link connectors are used in an IlvGrapher. For details, refer to the documentation of these exception classes.

See Also:

IlvGraphLayout.performLayout(), IlvGraphLayout.getCalcLayoutRegion()

setSpringConstant

public void setSpringConstant(float constant)

Sets the constant for the springs. The constant must be positive; if negative, the value is not changed. Recommended values range from 6. to 18.. A better range is from 12. to 16..

See Also:

getSpringConstant()

getSpringConstant

public float getSpringConstant()

Returns the current spring constant.

See Also:

setSpringConstant(float)

setLinkStyle

public void setLinkStyle(int style)

Sets the style of the shape of the links. Valid values are STRAIGHT_LINE_STYLE (the links are given a straight-line shape) and NO_RESHAPE_STYLE (no reshape is performed on the links).

This feature can be useful if the graph contains links that have intermediate points and are not straight-line links, for instance IlvPolylineLinkImage links with intermediate points.

Note that when the graph attached to the layout is of type IlvGrapher, the effect of the link reshaping depends on the type of the links and the connectors installed at the node. For all link styles, we recommend using links of type IlvPolylineLinkImage and either no link connector or any link connector except IlvFreeLinkConnector. Other link or connector types may cause an IlvInappropriateLinkException during layout. You can use the method IlvGraphLayoutUtil.EnsureAppropriateLinks(ilog.views.graphlayout.IlvGraphModel, ilog.views.graphlayout.IlvLayoutProvider) before layout or when the exception is caught to convert all links and link connectors to an appropriate type.

The default value is STRAIGHT_LINE_STYLE.

Since:

JViews 3.0

See Also:

getLinkStyle()

getLinkStyle

public int getLinkStyle()

Returns the current option for the style of the shape of the links.

Since:

JViews 3.0

See Also:

setLinkStyle(int)

checkAppropriateLink

public int checkAppropriateLink(Object link)

Checks whether the input link is appropriate for this layout. You should not call this method directly. It is called by IlvGraphLayout.checkAppropriateLinks().

Overrides:

checkAppropriateLink in class IlvGraphLayout

Parameters:

link - The link to be checked.

Returns:

The exception type for the link.

Since:

JViews 5.0

See Also:

IlvGraphLayout.checkAppropriateLinks()

getMovingNodes

public IlvGraphicVector getMovingNodes()

Returns the vector of nodes being moved by the graph layout algorithm. You should not call this method. It is only used when the graph model is an IlvGrapherAdaper in order to optimize for speed.

Overrides:

getMovingNodes in class IlvGraphLayout

Since:

JViews 5.5

createLayoutGrapherProperty

protected IlvGraphLayoutGrapherProperty createLayoutGrapherProperty(String name,
                                                                    boolean withDefaults)

Returns a new instance of IlvSpringEmbedderLayoutGrapherProperty 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 IlvGraphLayout

Since:

JViews 3.5

See Also:

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