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

All Methods Instance Methods Abstract 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(java.lang.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().
`java.lang.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(java.lang.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
```
java.lang.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(java.lang.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(java.lang.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.

Interface Layout

Method Summary

Methods inherited from interface org.graphstream.stream.Source

Methods inherited from interface org.graphstream.stream.AttributeSink

Methods inherited from interface org.graphstream.stream.ElementSink

Method Detail

getLayoutAlgorithmName

getNodeMovedCount

getStabilization

getStabilizationLimit

getLowPoint

getHiPoint

getSteps

getLastStepTime

getQuality

getForce

clear

setForce

setStabilizationLimit

setQuality

setSendNodeInfos

shake

moveNode

freezeNode

compute