Package ptolemy.vergil.basic.layout.kieler

Class KielerLayout

java.lang.Object

diva.graph.layout.AbstractGlobalLayout

ptolemy.vergil.basic.layout.kieler.KielerLayout

All Implemented Interfaces:

GlobalLayout

public class KielerLayout
extends AbstractGlobalLayout

Ptolemy Layouter that uses the KIELER layout algorithm from an external library to layout a given ptolemy model.

See http://www.informatik.uni-kiel.de/rtsys/kieler/ for more information about KIELER.

KIELER - Kiel Integrated Environment for Layout for the Eclipse RichClientPlatform

The KIELER project tries to enhance graphical modeling pragmatics. Next to higher level solutions (meta layout, view management, structure-based editing, etc.) developed for Eclipse models, it also implements custom layout algorithms.

This class interfaces a standalone KIELER layout algorithm for actor oriented port based graphical diagrams with a Ptolemy diagram.

While KIELER is mainly developed for an Eclipse environment, most algorithms are also available standalone and can be used in a non-Eclipse environment. This class is an approach to leverage this by employing the algorithms within Ptolemy. Two standalone external libraries are required, one containing KIELER classes and a small subset of the Eclipse Modeling Framework (EMF), the other containing the Google Guava library, which is used as utility.

Calling the layout() method will create a new KIELER graph data structure, run KIELER layout algorithms on it and augment it with resulting layout information (locations and sizes of nodes, bend points of connections). Then this layout is applied to the Ptolemy model. Moving of nodes in Ptolemy is done via adding or changing location attributes.

Setting bend points was not supported in Ptolemy. Ptolemy's built-in connection routing does not consider obstacle avoidance, hence overlaps with other nodes and connections might appear. In order to gap this problem, the actual drawing of the connections is performed by KielerLayoutConnector instead of the standard Manhattan connector. This KielerLayout stores bend points of connections persistently in a Ptolemy model via LayoutHint attributes attached to relations. The KielerLayoutConnector then reads these attributes and routes the edges accordingly. If the bend points are not valid anymore, the attribute is removed and layout has to be performed again.

Since:

Ptolemy II 8.0

Version:

$Id$

Author:

Hauke Fuhrmann (haf), Christian Motika (cmot), Miro Spönemann (msp) , Christoph Daniel Schulze (cds), Ulf Rueegg

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (cxh)

Constructor Summary

Constructors

Constructor	Description
KielerLayout(LayoutTarget target)	Construct an instance taking a LayoutTarget for specifying some methods for layout handling as given by the standard Ptolemy AbstractGlobalLayout.
KielerLayout(LayoutTarget target, CompositeActor ptolemyContainer)	Construct an instance setting the LayoutTarget as requested by the AbstractGlobalLayout and the containing Ptolemy model.

Method Summary

Modifier and Type	Method	Description
protected static de.cau.cs.kieler.core.alg.InstancePool<de.cau.cs.kieler.kiml.AbstractLayoutProvider>	_getLayouterPool()	Return a pool for layout provider instances that can be reused in subsequent layout runs.
protected static de.cau.cs.kieler.core.math.KVector	_getMultiportOffsets(Port port, de.cau.cs.kieler.kiml.klayoutdata.KShapeLayout kportlayout, int index, int maxIndex, boolean outer)	For a given Ptolemy port, its channel index in a multiport, and the maximum index in that multiport, calculate its offset in X and Y coordinates.
void	layout(java.lang.Object composite)	Layout the given composite.
void	setModel(CompositeEntity model)	Set the Ptolemy Model that contains the graph that is to be layouted.
void	setTop(Top top)	Set the Top window to enable status reports on the status bar.

Methods inherited from class diva.graph.layout.AbstractGlobalLayout

getLayoutTarget, setLayoutTarget

Methods inherited from class java.lang.Object

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

Constructor Detail

KielerLayout

public KielerLayout(LayoutTarget target)

Construct an instance taking a LayoutTarget for specifying some methods for layout handling as given by the standard Ptolemy AbstractGlobalLayout. The KielerLayout will need access to the top level Ptolemy model, so either use corresponding constructor or call setModel() prior to layout invocation.

Parameters:

target - The LayoutTarget on which layout will be performed

KielerLayout

public KielerLayout(LayoutTarget target,
                    CompositeActor ptolemyContainer)

Construct an instance setting the LayoutTarget as requested by the AbstractGlobalLayout and the containing Ptolemy model. Preferred constructor.

Parameters:

target - The LayoutTarget on which layout will be performed

ptolemyContainer - The composite actor that contains all elements to be layouted

Method Detail

layout

public void layout(java.lang.Object composite)

Layout the given composite. Main entry point for the layout action. Create a KIELER KGraph data structure corresponding to the Ptolemy model, instantiate a KIELER layout algorithm (AbstractLayoutProvider) and run its doLayout() method on the KGraph. The KGraph is augmented with layout information (position and sizes of objects and bend points for connections). This information is then reapplied to the ptolemy model by stating MoMLChangeRequests with location attributes for nodes. Connection bend points are applied using LayoutHints.

Specified by:

layout in interface GlobalLayout

Specified by:

layout in class AbstractGlobalLayout

Parameters:

composite - the container of the diagram in terms of a GraphModel.

setModel

public void setModel(CompositeEntity model)

Set the Ptolemy Model that contains the graph that is to be layouted. The layouter will require access to the Ptolemy model because the lower level Diva abstraction does not consider certain properties required by the KIELER layouter such as port positions.

Parameters:

model - The parent composite entity which internal diagram shall be layouted.

setTop

public void setTop(Top top)

Set the Top window to enable status reports on the status bar.

Parameters:

top - The Top window

_getLayouterPool

protected static de.cau.cs.kieler.core.alg.InstancePool<de.cau.cs.kieler.kiml.AbstractLayoutProvider> _getLayouterPool()

Return a pool for layout provider instances that can be reused in subsequent layout runs. New instances can be fetched from the pool and should be released back to the pool after use.

Returns:

a layout provider pool

_getMultiportOffsets

protected static de.cau.cs.kieler.core.math.KVector _getMultiportOffsets(Port port,
                                                                         de.cau.cs.kieler.kiml.klayoutdata.KShapeLayout kportlayout,
                                                                         int index,
                                                                         int maxIndex,
                                                                         boolean outer)

For a given Ptolemy port, its channel index in a multiport, and the maximum index in that multiport, calculate its offset in X and Y coordinates. For example, the first channel on the east side has offset 0 and the next channel is moved below the first one and so on. On the north side, the last channel has offset 0 and the first channel is at the most left side.

Parameters:

port - the Ptolemy port

kportlayout - the corresponding KPort KShapeLayout

index - index of the channel

maxIndex - maximum available channel

outer - True if the direction of the ports is obtained by calling IOPortController.getDirection(). Otherwise, the direction is obtained by calling PtolemyModelUtil._getExternalPortDirection().

Returns:

offset vector