org.graphstream.ui.layout

Interface Layout

All Superinterfaces:

AttributeSink, ElementSink, Pipe, Sink, Source

All Known Implementing Classes:

BarnesHutLayout, LinLog, 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) and eventually break points for edges if supported using either aesthetic constraints, hierarchical constraints or grouping constraints. As there are many such algorithms with distinct qualities and uses, this interface defines what is awaited from a general layout algorithm.

This algorithm is a Pipe that receives notifications on the graph eventually maintain an internal representation of it (or for some of them work directly on the graph), and in return send graph events to give each node a position via "xyz" attributes. Some algorithms may also export more information for nodes and edges. For example some algorithms are also able to work on the shape of an edge or the shape of a node.

The layout algorithm described by this interface may be iterative. Some algorithm will compute directly their final representation of the graph in one pass. However most algorithms will probably work step by step until a global quality function is satisfied. This is the best way to handle evolving graphs.

This behavior 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 as a sink of the layout.

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

Since:

20050706

Method Summary

Methods

Modifier and Type	Method and Description
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	getNodeMovedCount() How many nodes moved during the last step?.
double	getQuality() The current layout algorithm quality.
double	getStabilization() Estimate of how close to stabilization the layout algorithm is.
double	getStabilizationLimit() Above which value a correct stabilization is achieved?
int	getSteps() Number of calls made to step() so far.
void	moveNode(String id, double x, double y, double z) Move a node by force to a new location.
void	setForce(double value) The general "speed" of the algorithm.
void	setQuality(double qualityLevel) Set the overall quality level, a number between 0 and 1 with 1 the highest quality available, but often with a slower computation.
void	setSendNodeInfos(boolean send) If true, node informations messages are sent for every node.
void	setStabilizationLimit(double value) Change the stabilization 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.

getNodeMovedCount

int getNodeMovedCount()

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

getStabilization

double getStabilization()

Estimate of how close to stabilization the layout algorithm is.

Returns:

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

getStabilizationLimit

double getStabilizationLimit()

Above which value a correct stabilization is achieved?

Returns:

The stabilization 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

double getQuality()

The current layout algorithm quality. A number between 0 and 1 with 1 the highest (but probably slowest) quality.

Returns:

A number between 0 and 1.

getForce

double getForce()

The current layout force.

Returns:

A real number.

clear

void clear()

Clears the whole nodes and edges structures

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 stabilization are done.

Parameters:

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

setStabilizationLimit

void setStabilizationLimit(double value)

Change the stabilization limit for this layout algorithm.

The stabilization is a number between 0 and 1 that indicates how close to stabilization (no nodes need to move) the layout is. The value 1 means the layout is fully stabilized. 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 stabilization limit using getStabilizationLimit(). You can get the actual stabilization using getStabilization().

Be careful, most layout classes do not use the stabilization limit, this number is mostly used the process that control the layout, like the LayoutRunner for example. The stabilization 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 stabilization limit). In other words the layout will compute endlessly.

Parameters:

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

setQuality

void setQuality(double qualityLevel)

Set the overall quality level, a number between 0 and 1 with 1 the highest quality available, but often with a slower computation.

Parameters:

qualityLevel - The quality level, a number between 0 and 1.

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. The contents of the node information is specific to the algorithm, and sent via a specific "layout.info" attribute.

Parameters:

send - If true, send node informations to a "layout.info" attribute.

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. It is preferable to first freeze the node before moving it by force, and then un-freeze it.

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. The freezed node position will not be changed by the algorithm until un-freezed.

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 stabilizes. You can know if the layout is stable by using the getNodeMovedCount() 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 stabilized, and then call step() anew if you do not want to observe the layout process.