Reference

CAUTION: DRAFT

System

The particle system stores your nodes and edges and handles updating their coordinates as the simulation progresses.

CREATION

To create an empty simulation with default parameters simply allocate and initialise the object.

system_ = [[[ATSystem alloc] init] retain];

Parameters for the physics simulation can be set at creation-time by calling the constructor with the arguments:

system_ = [[[ATSystem alloc] initWithState:(ATSystemState *) parameters:(ATSystemParams *)] retain];

The parameters object contains a number of values and their defaults are:

• repulsion 1,000 the force repelling nodes from each other
• stiffness 600 the rigidity of the edges
• friction 0.5 the amount of damping in the system
• gravity NO an additional force attracting nodes to the origin
• deltaTime 0.02 timestep to use for stepping the simulation
• precision 0.6 accuracy vs. speed in force calculations (zero is fast but jittery, one is smooth but cpu-intensive)

Parameters can also be tweaked by setting the .parameters property. Note that if you take a copy of the current system parameters, the changes to your copy do not take effect on the system until you pass them back.

    // Create our particle system
    system_ = [[[ATSystem alloc] init] retain];
    
    // Take a copy of the current simulation parameters
    ATSystemParams *params = system_.parameters;
    
    // Modify the attributes we are interested in
    params.repulsion = 1000.0;
    params.stiffness = 600.0;
    params.friction  = 0.5;
    params.precision = 0.4;
    
    // Update the system
    system_.parameters = params;

RENDERING

The particle system doesn’t do any drawing on its own; you need to provide those routines in a separate object that will be triggered by the system when it’s time to redraw the screen. To set this up, create an object with two methods (.init and .redraw), then set the particle system’s renderer attribute to your new object:

var myRenderer = {
    init:  function(system){ console.log("starting",system) },
    redraw:function(){ console.log("redraw") }
}
var sys = arbor.ParticleSystem()
sys.renderer = myRenderer

The .init method will be called once before the first pass through the draw loop. Then the .redraw method will be called each time the screen needs to be re-plotted. Take a look at the sample project for a slightly more elaborated example of how this works.

NODES

addNode:(name) withData:(data)
getNode(name)
removeNode(node)

EDGES

addEdgeFromNode:(source) toNode:(target) withData:(data)
getEdgesFromNode:(source) toNode:(target)
getEdgesFromNode:(node)
getEdgesToNode:(node)
removeEdge:(edge)

ITERATION

eachNode(callback)
eachEdge(callback)

MODIFICATION

graft(branch)
merge(branch)
prune(callback)

SYSTEM SETTINGS

parameters( ) or (params)
fps( ) or (fps)
bounds( )
energy( )
start( )
stop( )

VIEWPORT MANAGEMENT

viewBounds(rect)
viewPadding(top, right, bottom, left)
viewTweenStep(stepsize)
viewMode( )

VIEWPORT TRANSLATION

toViewRect:(systemRect)
toViewSize:(systemSize)
toViewPoint:(systemPoint)
fromViewPoint:(screenPoint)

NODE SELECTION

nearestNodeToPoint:(screenPoint)
nearestNodeToPoint:(screenPoint) withinRadius:(radius)

Node

Node objects encapsulate the current physics state of a point in the particle system as well as giving you a place to attach associated non-physics metadata.

CREATION

New nodes are created through the system’s addNode:withData: method. For example:

    system_ = [[[ATSystem alloc] init] retain];
    myNode = [system_ addNode:@"myNode" withData:nil];

This will create a new Node object with an empty .userData field. You can then modify the attributes of the node by setting values for its properties:

• mass 1.0 the node’s resistance to movement and repulsive power
• fixed NO if YES, the node will be unaffected by other particles
• position CGPointZero the starting position (in system coordinates)

USING NODES

With each update of the simulation the values in .position will be updated based on the repulsion and spring forces in the system. To alter the node’s properties (in response to, say, a mouse click), simply reset its values and the system will use the new values.

Each node contains an property called .userData whose contents and use are entirely up to you. Typically it is used for storing metadata about the node so your rendering code can know how to draw it, what its label text should be, which url to go to on click, etc.

SYSTEM VALUES

name String (read only)
mass Number
fixed Boolean
position Point

USER VALUES

data { … }

Edge

Edge objects hold references to the source and target nodes they connect and have a preferred ‘resting’ length. They will apply forces on their endpoint nodes in an attempt to attain this optimal distance.

CREATION

New edges are created through the particle system’s .addEdge method. For example:

sys = arbor.ParticleSystem()
node1 = sys.addNode("one node")
node2 = sys.addNode("another")
edge = sys.addEdge(node1, node2, {length:.75, pointSize:3})

This creates a pair of Node objects then creates an Edge from the first to the second. The length key is a special variable that will be used for setting the edge’s resting length. Any other keys in the object passed to .addEdge will be placed in the resulting Edge’s .data attribute.

Note that .addEdge can be called with either actual Node objects or simply their .names as arguments. If a name is used but a node with that identifier does not yet exist, the system will automatically create one before creating the edge. For instance, the above code could be simplified to:

sys = arbor.ParticleSystem()
edge = sys.addEdge("one node", "another", {length:.75, pointSize:3})

SYSTEM VALUES

source Node
target Node
length Number

USER VALUES

data { … }

CGPoint

CGPoint objects are simple containers for x/y coordinates defined in the Core Graphics framework. This library includes handy methods for doing vector calculations with CGPoints. Typically, we create points by calling CGPointMake(x, y). In addition, two additional methods have been added to create points within the simulation coordinate space and near a particular point.

CREATION

CGPointRandom(radius)
CGPointNearPoint(center_pt, radius)

COORDINATE DATA

x Number
y Number

VECTOR MATH

CGPointAdd(pt) → Point
CGPointSubtract(pt) → Point
CGPointMultiply(pt) → Point
CGPointScale(number) → Point
CGPointDivideFloat(number) → Point
CGPointDistance( ) → Number
CGPointMagnitude( ) → Number
CGPointNormal( ) → Point
CGPointNormalize( ) → Point

RANDOM NUMBERS

RANDOM_0_1 - a random number between 0 and 1 inclusive

SANITY CHECKING

CGPointExploded( ) → Boolean