org.gicentre.utils.network

Class ParticleViewer<N extends Node,E extends Edge>

java.lang.Object

org.gicentre.utils.network.ParticleViewer<N,E>

Type Parameters:

N - Type of node to be stored in the particle viewer. This can be a Node or any specialised subclass of it.

E - Type of edge to be stored in the particle viewer. This can be an Edge or any specialised subclass of it.

public class ParticleViewer<N extends Node,E extends Edge>
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. Uses the physics engine and animation smoothers developed by Jeffrey Traer Bernstein.

Version:

3.4, 5th February, 2016.

Author:

Jo Wood, giCentre, City University London.

Field Summary

Fields

Modifier and Type	Field and Description
static float	DAMPING Default damping for all particle movements.
static float	EDGE_STRENGTH Default strength for all edges.
static float	SPRING_STRENGTH Default strength for all springs.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
boolean	addEdge(E edge) Adds the given edge to those to be displayed in the viewer.
boolean	addEdge(E edge, float distance) Adds the given edge to those to be displayed in the viewer.
boolean	addForce(N node1, N node2, float force) Creates a attractive or repulsive force between the two given nodes.
boolean	addForce(N node1, N node2, float force, float minDistance) Creates a attractive or repulsive force between the two given nodes.
void	addNode(N node) Adds a node to those to be displayed in the viewer.
boolean	addSpring(N node1, N node2, float length) Creates a spring between the two given nodes.
boolean	addSpring(N node1, N node2, float length, float strength) Creates a spring between the two given nodes with the given strength.
void	draw() Updates the particle view.
void	dropSelected() Releases the mouse-selected node so that it readjusts in response to other node positions.
N	getNearest(float x, float y) Reports the node nearest to the given screen coordinates.
N	getNearest(float x, float y, float radius) Reports the node nearest to the given screen coordinates but within the given radius.
Particle	getParticle(N node) Provides the particle associated with the given node.
N	getSelectedNode() Reports the currently selected node of null if no nodes selected.
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.
void	spaceNodes() Attempts to space out non-connected nodes from one another.
boolean	tether(N 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

Field Detail

EDGE_STRENGTH

public static final float EDGE_STRENGTH

Default strength for all edges.

See Also:

Constant Field Values

SPRING_STRENGTH

public static final float SPRING_STRENGTH

Default strength for all springs.

See Also:

Constant Field Values

DAMPING

public static final float DAMPING

Default damping for all particle movements.

See Also:

Constant Field Values

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.

width - Width of the particle viewer in pixel units.

height - Height of the particle viewer in pixel units.

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(N node1,
                        N 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(N node1,
                        N 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(N node1,
                         N 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.

addSpring

public boolean addSpring(N node1,
                         N node2,
                         float length,
                         float strength)

Creates a spring between the two given nodes with the given strength. If the two nodes not directly connected by an edge already have a spring between them, it will be replaced by this one.

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

strength - The strength of this new spring.

Returns:

True if the viewer contains the two nodes and a spring between them has been created.

tether

public boolean tether(N 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 Particle getParticle(N 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.

getSelectedNode

public N getSelectedNode()

Reports the currently selected node of null if no nodes selected. A selected node is one that has been clicked with the mouse and can be dragged once selected. This method can be useful when you wish to display some extra characteristics associated with a user-chosen node. Note that a node can only be selected while the mouse button is down and isn't masked with a shift key used for zooming the display.

Returns:

The selected node or null if no node is currently selected.

getNearest

public N getNearest(float x,
                    float y)

Reports the node nearest to the given screen coordinates.

Parameters:

x - x screen coordinate to query

y - y screen coordinate to query

Returns:

Node nearest to the given screen coordinates or null if no nodes in the particle viewer.

getNearest

public N getNearest(float x,
                    float y,
                    float radius)

Reports the node nearest to the given screen coordinates but within the given radius.

Parameters:

x - x screen coordinate to query

y - y screen coordinate to query

radius - Radius within which to search for nodes. If negative, all nodes are searched.

Returns:

Node nearest to the given screen coordinates or null if no nodes found within the given radius of the coordinates.

addNode

public void addNode(N node)

Adds a node to those to be displayed in the viewer.

Parameters:

node - Node to add to the viewer.

addEdge

public boolean addEdge(E 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. This version will use the locations of the two nodes to calculate their distance of separation.

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.

addEdge

public boolean addEdge(E edge,
                       float distance)

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. This version will fix the distance of separation between nodes to the given value

Parameters:

edge - Edge to add to the display.

distance - Distance of separation between the nodes.

Returns:

True if edge was added successfully. False if edge contains nodes that have not been added to the viewer.

spaceNodes

public void spaceNodes()

Attempts to space out non-connected nodes from one another. This is achieved by adding a strong repulsive force between non-connected nodes. Note that this produces n-squared forces so can be slow for large networks where many nodes are not connected to each other.

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.