org.gicentre.utils.network
Class ParticleViewer

java.lang.Object
  extended by org.gicentre.utils.network.ParticleViewer

public class ParticleViewer
extends java.lang.Object

Allows particles to be viewed and animated. Suitable for spring embedded / force directed layouts for arranging networks and other collections of interacting objects. Note this class relies on the traer physics library for particle management and the traer animation library for smooth camera movement.

Version:
3.1, 18th February, 2011.
Author:
Jo Wood, giCentre, City University London.

Constructor Summary
ParticleViewer(processing.core.PApplet parent, int width, int height)
          Initialises the particle viewer.
 
Method Summary
 boolean addEdge(Edge edge)
          Adds the given edge to those to be displayed in the viewer.
 boolean addForce(Node node1, Node node2, float force)
          Creates a attractive or repulsive force between the two given nodes.
 boolean addForce(Node node1, Node node2, float force, float minDistance)
          Creates a attractive or repulsive force between the two given nodes.
 void addNode(Node node)
          Adds a node to those to be displayed in the viewer.
 boolean addSpring(Node node1, Node node2, float length)
          Creates a spring between the two given nodes.
 void draw()
          Updates the particle view.
 void dropSelected()
          Releases the mouse-selected node so that it readjusts in response to other node positions.
 traer.physics.Particle getParticle(Node node)
          Provides the particle associated with the given node.
 void resetView()
          Resets the zoomed view to show the entire network.
 void selectNearestWithMouse()
          Allows a node to be selected with the mouse.
 void setDrag(float drag)
          Sets the drag on all particles in the system.
 boolean tether(Node node, float strength)
          Tethers the given node to its location with the given strength.
 void updateParticles()
          Updates the positions of nodes and edges in the viewer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ParticleViewer

public ParticleViewer(processing.core.PApplet parent,
                      int width,
                      int height)
Initialises the particle viewer.

Parameters:
parent - Parent sketch in which this viewer is to be drawn.
Method Detail

draw

public void draw()
Updates the particle view. This should be called on each draw cycle in order to update the positions of all nodes and edges in the viewer. If you need to update the positions of particles without drawing it (e.g. to speed up movement, call updateParticles() instead.


updateParticles

public void updateParticles()
Updates the positions of nodes and edges in the viewer. This method does not normally need to be called as update happens every time draw() is called. Calling this method can be useful if you wish to speed up the movement of nodes and edges by updating their position more than once every draw cycle.


setDrag

public void setDrag(float drag)
Sets the drag on all particles in the system. By default drag is set to 0.75 which is enough to allow particles to move smoothly.

Parameters:
drag - Drag effect (larger numbers slow down movement).

addForce

public boolean addForce(Node node1,
                        Node node2,
                        float force)
Creates a attractive or repulsive force between the two given nodes. If the two nodes already have a force between them, it will be replaced by this one.

Parameters:
node1 - First of the two nodes to have a force between them.
node2 - Second of the two nodes to have a force between them.
force - Force to create between the two nodes. If positive, the nodes will attract each other, if negative they will repulse. The larger the magnitude the stronger the force.
Returns:
True if the viewer contains the two nodes and a force between them has been created.

addForce

public boolean addForce(Node node1,
                        Node node2,
                        float force,
                        float minDistance)
Creates a attractive or repulsive force between the two given nodes. If the two nodes already have a force between them, it will be replaced by this one.

Parameters:
node1 - First of the two nodes to have a force between them.
node2 - Second of the two nodes to have a force between them.
force - Force to create between the two nodes. If positive, the nodes will attract each other, if negative they will repulse. The larger the magnitude the stronger the force.
minDistance - Minimum distance within which no force is applied.
Returns:
True if the viewer contains the two nodes and a force between them has been created.

addSpring

public boolean addSpring(Node node1,
                         Node node2,
                         float length)
Creates a spring between the two given nodes. If the two nodes not directly connected by an edge already have a spring between them, it will be replaced by this one. The strength of the spring will be less than that of connected edges.

Parameters:
node1 - First of the two nodes to have a spring between them.
node2 - Second of the two nodes to have a spring between them.
length - The length of this spring (natural rest distance at which the two nodes would sit).
Returns:
True if the viewer contains the two nodes and a spring between them has been created.

tether

public boolean tether(Node node,
                      float strength)
Tethers the given node to its location with the given strength.

Parameters:
node - The node to be tethered.
strength - Strength of the tether.
Returns:
True if the viewer contains the given node and it was tethered successfully.

getParticle

public traer.physics.Particle getParticle(Node node)
Provides the particle associated with the given node. This can be used for advanced configuration of the node's behaviour in a force-directed layout.

Parameters:
node - The node for which the associated particle is to be retrieved.
Returns:
The particle representing the given node or null if it is not found.

addNode

public void addNode(Node node)
Adds a node to those to be displayed in the viewer.

Parameters:
node - Node to add to the viewer.

addEdge

public boolean addEdge(Edge edge)
Adds the given edge to those to be displayed in the viewer. Note that the edge must connect nodes that have already been added to the viewer.

Parameters:
edge - Edge to add to the display.
Returns:
True if edge was added successfully. False if edge contains nodes that have not been added to the viewer.

selectNearestWithMouse

public void selectNearestWithMouse()
Allows a node to be selected with the mouse.


dropSelected

public void dropSelected()
Releases the mouse-selected node so that it readjusts in response to other node positions.


resetView

public void resetView()
Resets the zoomed view to show the entire network.



gicentreUtils V.3.1, API documentation generated 18th February, 2011