com.nwoods.jgo.layout
Class JGoForceDirectedAutoLayout

java.lang.Object
  extended bycom.nwoods.jgo.layout.JGoAutoLayout
      extended bycom.nwoods.jgo.layout.JGoForceDirectedAutoLayout

public class JGoForceDirectedAutoLayout
extends JGoAutoLayout

JGoForceDirectedAutoLayout provides an auto-layout algorithm for graphs which utilizes a force-directed method. The graph is viewed as a system of bodies with forces acting between the bodies. The algorithm seeks a configuration of the bodies with locally minimal energy, i.e., a position such that the sum of the forces on each body is zero.


Constructor Summary
JGoForceDirectedAutoLayout()
          Constucts a ForceDirectedAutoLayout with null network, document.
JGoForceDirectedAutoLayout(JGoDocument doc)
          Constructs a ForceDirectedAutoLayout with a document of doc, and a network containing all of the top-level objects contained in doc.
JGoForceDirectedAutoLayout(JGoDocument doc, int Nmax_iterations)
          Constructs a ForceDirectedAutoLayout for the passed in document that will run for a maximum of Nmax_iterations when performLayout() is called.
JGoForceDirectedAutoLayout(JGoDocument doc, JGoNetwork network, int Nmax_iterations)
          Constructs a ForceDirectedAutoLayout for the passed in document, and network, that will run for a maximum of Nmax_iterations when performLayout() is called.
JGoForceDirectedAutoLayout(JGoForceDirectedAutoLayout layout)
          Make a copy of a JGoForceDirectedAutoLayout, copying most of the important properties except for the JGoNetwork.
JGoForceDirectedAutoLayout(JGoSelection sel)
          Constructs a ForceDirectedAutoLayout with a network containing all of the top-level objects contained in sel.
 
Method Summary
static int getDefaultMaxIterations()
          Returns the default maximum number of iterations to use in looking for a layout.
protected  double getElectricalCharge(JGoNetworkNode pNode)
          Returns the charge of the point representing the JGoNetworkNode pNode.
protected  double getElectricalFieldX(org.eclipse.swt.graphics.Point xy)
          Returns the electrical field in the X direction acting on a node at the logical point Point xy.
protected  double getElectricalFieldY(org.eclipse.swt.graphics.Point xy)
          Returns the electrical field in the Y direction acting on a node at the logical point Point xy.
protected  double getGravitationalFieldX(org.eclipse.swt.graphics.Point xy)
          The function getGravitationalFieldX returns the graviational field in the X direction acting on a node at the logical point Point xy.
protected  double getGravitationalFieldY(org.eclipse.swt.graphics.Point xy)
          The function getGravitationalFieldY returns the graviational field in the Y direction acting on a node at the logical point Point xy.
protected  double getGravitationalMass(JGoNetworkNode pNode)
          The function getGravitationalMass returns the mass of the point representing the JGoNetworkNode pNode.
 int getMaxIterations()
          Gets the limit on the number of iterations that updatePositions will perform on the network.
protected  double getNodeDistance(JGoNetworkNode pNodeA, JGoNetworkNode pNodeB)
          Returns the distance between two nodes.
 java.util.Random getRandomNumberGenerator()
          Gets the Random number generator used to give an initial push between objects that are located at the same position.
protected  double getSpringLength(JGoNetworkLink pLink)
          Returns the length of the spring representing the JGoNetworkLink pLink.
protected  double getSpringStiffness(JGoNetworkLink pLink)
          Returns the stiffness of the spring representing the JGoNetworkLink pLink.
protected  boolean isFixed(JGoNetworkNode pGoNode)
          The protected function isFixed returns true if the node should not be moved by the layout algorithm.
protected  void layoutNodesAndLinks(boolean isfinal)
          Updates the physical location of "real" nodes and links to reflect the layout.
 JGoForceDirectedAutoLayoutLinkData linkData(JGoNetworkLink pLink)
          Takes in a JGoNetworkLink and returns the link's ForceDirectedAutoLayout data.
 JGoForceDirectedAutoLayoutNodeData nodeData(JGoNetworkNode pNode)
          Takes in a JGoNetworkNode and returns the node's ForceDirectedAutoLayout data.
 void performLayout()
          Performs force-directed auto-layout.
static void setDefaultMaxIterations(int x)
          Sets the default maximum number of iterations to use in looking for a layout to x.
 void setMaxIterations(int max)
          Sets the limit on the number of iterations that updatePositions will perform on the network.
 void setRandomNumberGenerator(java.util.Random value)
          Sets the Random number generator used to give an initial push between objects that are located at the same position.
protected  boolean updatePositions()
          Peforms one iteration of the ForceDirectedAutoLayout algorithm and updates the positions of the nodes.
 
Methods inherited from class com.nwoods.jgo.layout.JGoAutoLayout
getDocument, getNetwork, progressUpdate, setDocument, setNetwork
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout()
Constucts a ForceDirectedAutoLayout with null network, document. performLayout() will be a no-op until the network has been set.


JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout(JGoDocument doc)
Constructs a ForceDirectedAutoLayout with a document of doc, and a network containing all of the top-level objects contained in doc. The default maximum iterations will be used.

Parameters:
doc - the JGoDocument containing the JGoObjects to layout

JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout(JGoSelection sel)
Constructs a ForceDirectedAutoLayout with a network containing all of the top-level objects contained in sel. The default maximum iterations will be used.

Parameters:
sel - the JGoSelection containing the JGoObjects to layout

JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout(JGoDocument doc,
                                  int Nmax_iterations)
Constructs a ForceDirectedAutoLayout for the passed in document that will run for a maximum of Nmax_iterations when performLayout() is called.

Parameters:
doc - the JGoDocument containing the JGoObjects to layout
Nmax_iterations - the maximum number of iterations to use in looking for a local equilibrium

JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout(JGoDocument doc,
                                  JGoNetwork network,
                                  int Nmax_iterations)
Constructs a ForceDirectedAutoLayout for the passed in document, and network, that will run for a maximum of Nmax_iterations when performLayout() is called.

Parameters:
doc - the JGoDocument containing the JGoObjects to layout
network - the JGoNetwork representation of the JGoObjects to layout
Nmax_iterations - the maximum number of iterations to use in looking for a local equilibrium

JGoForceDirectedAutoLayout

public JGoForceDirectedAutoLayout(JGoForceDirectedAutoLayout layout)
Make a copy of a JGoForceDirectedAutoLayout, copying most of the important properties except for the JGoNetwork.

Method Detail

performLayout

public void performLayout()
Performs force-directed auto-layout. This method can be overridden to customize the layout algorithm, but care should be taken to ensure that each node and link in the input network are properly initialized and terminated.

Specified by:
performLayout in class JGoAutoLayout

getNodeDistance

protected double getNodeDistance(JGoNetworkNode pNodeA,
                                 JGoNetworkNode pNodeB)
Returns the distance between two nodes. The default implementation considers the shortest distance between the two nodes. If the nodes correspond to top-level JGo objects, the width and height of the JGoObject is factored into the distance between the nodes. If the nodes do not correspond to top-level JGo objects, then the nodes implicitly have a width and height of zero, and the distance is calculated.


getSpringStiffness

protected double getSpringStiffness(JGoNetworkLink pLink)
Returns the stiffness of the spring representing the JGoNetworkLink pLink. The to and from nodes of pLink are acted upon by a force of magnitude getSpringStiffness(pLink) * (getNodeDistance(pLink.from, pLink.to) - getSpringLength(pLink)).


getSpringLength

protected double getSpringLength(JGoNetworkLink pLink)
Returns the length of the spring representing the JGoNetworkLink pLink. The to and from nodes of a link L are acted upon by a force of magnitude getSpringStiffness(L) * (getNodeDistance(L.from, L.to) - getSpringLength(L)).


getElectricalCharge

protected double getElectricalCharge(JGoNetworkNode pNode)
Returns the charge of the point representing the JGoNetworkNode pNode. A node U and a node V are acted upon by a force of magnitude (getElectricalCharge(U) * getElectricalCharge(V)) / (getNodeDistance(U,V) * getNodeDistance(U,V)). A node U is acted upon by forces in the X and Y directions of magnitude getElectricalFieldX(U.position) * getElectricalCharge(U) and getElectricalFieldY(U.position) * getElectricalCharge(U).


getElectricalFieldX

protected double getElectricalFieldX(org.eclipse.swt.graphics.Point xy)
Returns the electrical field in the X direction acting on a node at the logical point Point xy. A node U is acted upon by a force in the X direction of magnitude getElectricalFieldX(U.position) * getElectricalCharge(U).


getElectricalFieldY

protected double getElectricalFieldY(org.eclipse.swt.graphics.Point xy)
Returns the electrical field in the Y direction acting on a node at the logical point Point xy. A node U is acted upon by a force in the Y direction of magnitude getElectricalFieldY(U.position) * getElectricalCharge(U).


getGravitationalMass

protected double getGravitationalMass(JGoNetworkNode pNode)
The function getGravitationalMass returns the mass of the point representing the JGoNetworkNode pNode. A node U is acted upon by forces in the X and Y directions of magnitude getGravitationalFieldX(U.position) * getGravitationalMass(U) and getGravitationalFieldY(U.position) * getGravitationalMass(U).


getGravitationalFieldX

protected double getGravitationalFieldX(org.eclipse.swt.graphics.Point xy)
The function getGravitationalFieldX returns the graviational field in the X direction acting on a node at the logical point Point xy. A node U is acted upon by a force in the X direction of magnitude getGravitationalFieldX(U.position) * getGravitationalMass(U).


getGravitationalFieldY

protected double getGravitationalFieldY(org.eclipse.swt.graphics.Point xy)
The function getGravitationalFieldY returns the graviational field in the Y direction acting on a node at the logical point Point xy. A node U is acted upon by a force in the Y direction of magnitude getGravitationalFieldY(U.position) * getGravitationalMass(U).


isFixed

protected boolean isFixed(JGoNetworkNode pGoNode)
The protected function isFixed returns true if the node should not be moved by the layout algorithm. The default implementation returns false on all nodes. This function can be overridden to provide "fine-tuning" of the layout.


updatePositions

protected boolean updatePositions()
Peforms one iteration of the ForceDirectedAutoLayout algorithm and updates the positions of the nodes. Returns true if additional iterations are needed to find a solution.


layoutNodesAndLinks

protected void layoutNodesAndLinks(boolean isfinal)
Updates the physical location of "real" nodes and links to reflect the layout. This method can be overridden to customize the layout algorithm. One reason to override this method would be to accomodate an animated layout algorithm. The layoutNodesAndLinks method is called once each iteration and one final time. At a minimum, sub-classes that override this method should perform getNetwork().commitNodesAndLinks() on the final call to layoutNodesAndLinks.

Parameters:
isfinal - true if this is the final call to layoutNodesAndLinks

getMaxIterations

public int getMaxIterations()
Gets the limit on the number of iterations that updatePositions will perform on the network.


setMaxIterations

public void setMaxIterations(int max)
Sets the limit on the number of iterations that updatePositions will perform on the network.


getRandomNumberGenerator

public java.util.Random getRandomNumberGenerator()
Gets the Random number generator used to give an initial push between objects that are located at the same position.

Initially this value is null, which causes a new java.util.Random to be used.


setRandomNumberGenerator

public void setRandomNumberGenerator(java.util.Random value)
Sets the Random number generator used to give an initial push between objects that are located at the same position.

You can set this property so that you can control the seed, to make the results reproducible if the data structures are exactly the same each time.


nodeData

public final JGoForceDirectedAutoLayoutNodeData nodeData(JGoNetworkNode pNode)
Takes in a JGoNetworkNode and returns the node's ForceDirectedAutoLayout data.


linkData

public final JGoForceDirectedAutoLayoutLinkData linkData(JGoNetworkLink pLink)
Takes in a JGoNetworkLink and returns the link's ForceDirectedAutoLayout data.


getDefaultMaxIterations

public static int getDefaultMaxIterations()
Returns the default maximum number of iterations to use in looking for a layout. The default maximum is used whenever a ForceDirectedAutoLayout is created without specifying a maximum number of iterations.


setDefaultMaxIterations

public static void setDefaultMaxIterations(int x)
Sets the default maximum number of iterations to use in looking for a layout to x. The default maximum is used whenever a ForceDirectedAutoLayout is created without specifying a maximum number of iterations.

Parameters:
x - the new default for the maximum number of iterations.