Package 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 Details

    • 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.