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

    All Methods Instance Methods Concrete Methods
    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.