org.graphstream.ui.layout
Interface Layout

All Superinterfaces:

AttributeSink, ElementSink, Pipe, Sink, Source

All Known Implementing Classes:

SpringBox

public interface Layout
extends Pipe

Layout algorithm interface.

The layout algorithm role is to compute the best possible positions of nodes in a given space (2D or 3D). As there are many such algorithms with distinct qualities and uses, this interface defines what is awaited from a layout algorithm.

The algorithm follows a graph by being a Sink. However, at the contrary of several other algorithms, it does not work on the graph itself. It works on a description of the graph and maintains its own vision of this graph. In return, it does not modify the graph, but sends events to listeners telling the new positions of nodes in the graph.

Here a layout algorithm continuously updates its internal representation of the graph following a given method and outputs its computations to a listener for each element of the graph (iterative algorithm). Such a layout algorithm is not made to compute a layout once and for all. This is the best way to handle evolving graphs.

This behaviour has been chosen because this algorithm is often run aside the main thread that works on the graph. We want a thread to be able to compute a new layout on its side, without disturbing the main algorithm run on the graph. See the LayoutRunner for an helper class allowing to create such a thread.

To be notified of the layout changes dynamically, you must register a LayoutListener that will be called each time a node changes its position.

The graph viewers in the UI package often use a layout algorithm to present graphs on screen.

TODO: would it be interesting, for some layouts, to have edges that contain "break points" or curve points (Bezier for example) that are also moved by the layout algorithm ?

Since:

20050706

Method Summary

void	addListener(LayoutListener listener) Add a listener for specific layout events.
void	clear() Clears the whole nodes and edges structures
void	compute() Method to call repeatedly to compute the layout.
void	freezeNode(String id, boolean frozen) Freeze or un-freeze a node.
double	getForce() The current layout force.
Point3	getHiPoint() Largest point in space of the layout bounding box.
long	getLastStepTime() Time in nanoseconds used by the last call to step().
String	getLayoutAlgorithmName() Name of the layout algorithm.
Point3	getLowPoint() Smallest point in space of the layout bounding box.
int	getNodeMoved() How many nodes moved during the last step?.
int	getQuality() The current layout algorithm quality.
double	getStabilization() How close to stabilisation the layout algorithm is.
double	getStabilizationLimit() Above which value a correct stabilisation is achieved?
int	getSteps() Number of calls made to step() so far.
void	inputPos(String filename) Read the nodes positions from a file.
void	moveNode(String id, double x, double y, double z) Move a node by force to a new location.
void	outputPos(String filename) Output the nodes positions to a file.
void	removeListener(LayoutListener listener) Remove a listener for specific layout events.
void	setForce(double value) The general "speed" of the algorithm.
void	setQuality(int qualityLevel) Set the overall quality level.
void	setSendNodeInfos(boolean send) If true, node informations messages are sent for every node.
void	setStabilizationLimit(double value) Change the stabilisation limit for this layout algorithm.
void	shake() Add a random vector whose length is 10% of the size of the graph to all node positions.

Methods inherited from interface org.graphstream.stream.Source

addAttributeSink, addElementSink, addSink, clearAttributeSinks, clearElementSinks, clearSinks, removeAttributeSink, removeElementSink, removeSink

Methods inherited from interface org.graphstream.stream.AttributeSink

edgeAttributeAdded, edgeAttributeChanged, edgeAttributeRemoved, graphAttributeAdded, graphAttributeChanged, graphAttributeRemoved, nodeAttributeAdded, nodeAttributeChanged, nodeAttributeRemoved

Methods inherited from interface org.graphstream.stream.ElementSink

edgeAdded, edgeRemoved, graphCleared, nodeAdded, nodeRemoved, stepBegins

Method Detail

getLayoutAlgorithmName

String getLayoutAlgorithmName()

Name of the layout algorithm.

getNodeMoved

int getNodeMoved()

How many nodes moved during the last step?. When this method returns zero, the layout stabilised.

getStabilization

double getStabilization()

How close to stabilisation the layout algorithm is.

Returns:

a value between 0 and 1. 1 means fully stabilised.

getStabilizationLimit

double getStabilizationLimit()

Above which value a correct stabilisation is achieved?

Returns:

The stabilisation limit.

getLowPoint

Point3 getLowPoint()

Smallest point in space of the layout bounding box.

getHiPoint

Point3 getHiPoint()

Largest point in space of the layout bounding box.

getSteps

int getSteps()

Number of calls made to step() so far.

getLastStepTime

long getLastStepTime()

Time in nanoseconds used by the last call to step().

getQuality

int getQuality()

The current layout algorithm quality. There are five quality levels. The higher the level, the higher the quality.

Returns:

A number between 0 and 4.

getForce

double getForce()

The current layout force.

Returns:

A real number.

clear

void clear()

Clears the whole nodes and edges structures

addListener

void addListener(LayoutListener listener)

Add a listener for specific layout events.

removeListener

void removeListener(LayoutListener listener)

Remove a listener for specific layout events.

setForce

void setForce(double value)

The general "speed" of the algorithm. For some algorithm this will have no effect. For most "dynamic" algorithms, this change the way iterations toward stabilisation are done.

Parameters:

value - A number in [0..1].

setStabilizationLimit

void setStabilizationLimit(double value)

Change the stabilisation limit for this layout algorithm.

The stabilisation is a number between 0 and 1 that indicates how close to stabilisation (no nodes need to move) the layout is. The value 1 means the layout is fully stabilised. Naturally this is often only an indication only, for some algorithms, it is difficult to determine if the layout is correct or acceptable enough. You can get the actual stabilisation limit using getStabilizationLimit(). You can get the actual stabilisation using getStabilization().

Be careful, most layout classes do not use the stabilisation limit, this number is mostly used the process that control the layout, like the LayoutRunner for example. The stabilisation limit is only an indication with a default set for each layout algorithm. However this default can be changed using this method, or by storing on the graph an attribute "layout.stabilization-limit" (or "layout.stabilisation-limit").

The convention is that the value 0 means that the process controlling the layout will not stop the layout (will therefore not consider the stabilisation limit). In other words the layout will compute endlessly.

Parameters:

value - The new stabilisation limit, 0 means no need to stabilise. Else a value larger than zero or equal to 1 is accepted.

setQuality

void setQuality(int qualityLevel)

Set the overall quality level. There are five quality levels.

Parameters:

qualityLevel - The quality level in [0..4].

setSendNodeInfos

void setSendNodeInfos(boolean send)

If true, node informations messages are sent for every node. This is mainly for debugging and slows down the process a lot.

Parameters:

send - If true, send node informations.

shake

void shake()

Add a random vector whose length is 10% of the size of the graph to all node positions.

moveNode

void moveNode(String id,
              double x,
              double y,
              double z)

Move a node by force to a new location.

Parameters:

id - The node identifier.

x - The node new X.

y - The node new Y.

z - The node new Z.

freezeNode

void freezeNode(String id,
                boolean frozen)

Freeze or un-freeze a node.

Parameters:

id - The node identifier.

frozen - If true the node is frozen.

compute

void compute()

Method to call repeatedly to compute the layout.

This method implements the layout algorithm proper. It must be called in a loop, until the layout stabilises. You can know if the layout is stable by using the getNodeMoved() method that returns the number of node that have moved during the last call to step().

The listener is called by this method, therefore each call to step() will also trigger layout events, allowing to reproduce the layout process graphically for example. You can insert the listener only when the layout stabilised, and then call step() anew if you do not want to observe the layout process.

inputPos

void inputPos(String filename)
              throws IOException

Read the nodes positions from a file. See outputPos(String) for the file format.

Throws:

IOException

outputPos

void outputPos(String filename)
               throws IOException

Output the nodes positions to a file. The file format is

• each line gives the position of one node.
• the list starts with the node identifier (maybe between quotes if needed).
• a colon.
• and a list of two to three double numbers indicating the position of the node in a given space.
• Empty lines are ignored.
• Lines beginning with an arbitrary number of spaces and then a sharp sign (#) are ignored.

Throws:

IOException