BoidsND
Extension
ExtensionDescription
BoidsND is an implementation of the Reynolds boids algorithm for an arbitrary number of dimensions. Flock-properties, such as maximum velocity or the weights for the three rules, are Gaussian-distributed such that the mean is the value provided and the standard deviation is that 5% of the mean.
Class Methods
.new
Create a new flock.
Arguments:
| dim |
The number of dimensions of the flock-space. If 2 or 3 is passed, a warning is thrown that one ought to use Boids2D or Boids3D. |
| numBoids |
Number of members of the flock. |
| timestep |
The timestep of each calculation, used internally to calculate a working maximum velocity. When running moveFlock() in a loop, this is the interval of waiting to get movement at speed. If this is set lower than the wait interval in a loop, the flock appears to move in slow motion and visa versa. |
| centerInstinct |
The weight of the center instinct rule. The center instinct is the amount of weight each boid gives to moving toward the center of mass of the entire flock. Making this negative makes the boids move away from the center of mass. Often works best at 0 for a bounded system. |
| innerDistance |
The weight of the inner distance rule. The inner distance rule moves each boid away from one another such that they maintain some distance from one another. Making this negative attracts the boids to each other. |
| matchVelocity |
The weight of the velocity matching rule. The velocity matching rule applies to thee velocity vector, both magnitude (speed) and angle (direction). |
Returns:
A BoidsND.
Instance Methods
.dim
The number of dimensions of the flock-space. Not modulable.
Returns:
An Integer
.addBoid
Add a new member to the flock.
Arguments:
| initPos |
The initial position. If nil, the boid is added at the center of mass of all the agents. |
Returns:
A BoidsND
.removeBoid
Remove an agent from the flock
Arguments:
| index |
The index of the agent to remove. If nil, the last agent in the list is removed. |
.boids
The list of BoidUnits (agents) in the flock.
Returns:
An Array of BoidUnitND's.
.bounds
The bounds of the space in which the flock moves in meters.
Returns:
An Array
.setAllBoundLengths
Set all bound sides in all dimensions equal to the argument.
Arguments:
| size |
The size in meters of the bounds. |
Returns:
A BoidsND
.setBoundLength
Set the size of the bound in a single dimension.
Arguments:
| dim |
The dimension that one wants to change. |
| size |
The size in meters of the bounds. |
Returns:
A BoidsND
.wrap
Boolean on whether or not to wrap the agents in the space. Defaults to false.
Arguments:
| boolean |
Returns:
A Boolean (getter) or a BoidsND (setter)
.timestep
The timestep used in calculating positions relative the maximum velocity.
Arguments:
| time |
A Float describing the interval of time with which to calculate the movement of the flock. This can be different than the interval at which moveFlock() is looped such that momentum is preserved when moving in "slow motion". |
Returns:
A Float (getter) or a BoidsND (setter)
Flocking Rules and Moving the Flock
.centerInstinct
The weight of the center-seeking rule, Gaussian-distributed.
Returns:
A BoidsND
Discussion:
The center instinct is the amount of weight each agent gives to moving toward the center of mass of the six nearest members, regardless of their absolute distance. Making this negative causes the agents move away from the center of mass of their neighbors. Often works best close to 0 for a bounded system. When this is set high in an unbounded (wrapped) system, the agents have a tendency to oscillate at the extremes of the space.
.innerDistance
The weight of the inner distance rule, Gaussian-distributed.
Returns:
A BoidsND
Discussion:
The inner distance rule moves each agent away from one another such that they maintain some distance from one another. Making this negative attracts the agents to each other.
.matchVelocity
The weight of the velocity-matching rule, Gaussian-distributed. The velocity is matched in both speed and direction.
Returns:
A BoidsND
Discussion:
The inner distance rule moves each agent away from one another such that they maintain some distance from one another. Making this negative attracts the agents to each other.
.maxVelocity
The maximum velocity of the agents in meters per second; defaults to 100 m/s. This is adjusted internally to a working maximum velocity and is Gaussian-distributed.
Arguments:
| val |
Speed in meters per second. |
Returns:
A BoidsND
.minSpace
The minimum space between agents in meters, Gaussian-distributed.
Arguments:
| val |
The minimum space between agents in meters. |
Returns:
A BoidsND
Discussion:
Neighboring agents within this distance from one another will move away from each other; agents outside of this radius have no effect. Note that this amount can be overcome by other forces, for instance if a very strong attractor is present.
.moveFlock
The method that, when called, calculates the new velocity vectors and adds them to the positions. The func argument is evaluated after all other operations and the boids have been moved.
Arguments:
| func |
A Function that is called after evaluation of the new positions. It is passed this instance of BoidsND. |
Returns:
A BoidsND
Targets and Obstacles
gravity and repulsion, to strength so that they are consistent..targets
An array of the targets. Each target is a Dictionary of two elements: \pos and \strength.
Returns:
An Array of Dictionaries
.addTarget
Add a target. Each target is a Dictionary containing two elements: \pos (a RealVector of the coordinates in the dimensions) and \strength (a Float of the strength of the target).
Arguments:
| pos |
An Array that describes the position of the target. The array must be equal to the number of dimensions. |
| gravity |
A Float or Array of Floats (same size as number of dimensions) describing the strength of the target. NOTE: In BoidsND, it is possible to specify unique gravities in dimensions by passing an array the same size as the number of dimensions. For instance, in a 5-dimensional space the gravity could be specified as [3,2,0,0,6] where the gravity is 3 in dimension 0, 2 in dimension 1, etc. Using this it is possible to specify gravity along a line. Unfortunately, this is not yet reflected in the visualizer. |
Returns:
A BoidsND
pos must be an Array of equal size to the number of dimensions.
The field of the gravity falls off at a rate of 1/r where r is the radius in meters.
.editTarget
Edit a target at an index.
Arguments:
| index |
The index of the target one wishes to edit. If this is nil, nothing happens and a warning is thrown. |
| pos |
The position of the target. If this is nil, the position remains the same. |
| gravity |
The gravity of the target. If this is nil, the gravity remains the same. |
Returns:
A BoidsND
.removeTarget
Remove a target
Arguments:
| index |
The index of the target in the list of targets to remove. If index is nil, remove the last target in the list. |
.clearTargets
Clear the list of targets.
Returns:
a BoidsND
.obstacles
An array of the obstacles. Each obstacle is a Dictionary of two elements: \pos and \strength.
Returns:
An Array of Dictionaries
.addObstacle
Add an obstacle. Each obstacle is a Dictionary containing two elements: \pos (a RealVector of the coordinates in the dimensions) and \strength (a Float of the repulsion of the obstacle).
Arguments:
| pos |
An Array that describes the position of the obstacle. The array must be equal to the number of dimensions. |
| repulsion |
A Float or Array of Floats (same size as number of dimensions) describing the repulsion of the obstacle. NOTE: In BoidsND, it is possible to specify unique repulsions in dimensions by passing an array the same size as the number of dimensions. For instance, in a 5-dimensional space the repulsion could be specified as [3,2,0,0,6] where the gravity is 3 in dimension 0, 2 in dimension 1, etc. Using this it is possible to specify repulsion along a line (but not a wall, yet). Unfortunately, this is not yet reflected in the visualizer. It is also much harder to work with obstacles in higher dimensional spaces due to the degrees of freedom possible. |
Returns:
A BoidsND
pos must be an Array of equal size to the number of dimensions.
The field of repulsion falls off at a rate of 1/r^2 where r is the radius in meters.
.editObstacle
Edit an obstacle at an index.
Arguments:
| index |
The index of the obstacle one wishes to edit. If this is nil, nothing happens and a warning is thrown. |
| pos |
The position of the obstacle. If this is nil, the position remains the same. |
| repulsion |
The gravity of the obstacle. If this is nil, the gravity remains the same. |
Returns:
A BoidsND
.removeObstacle
Remove a obstacle.
Arguments:
| index |
The index of the obstacle in the list of obstacles to remove. If index is nil, remove the last obstacle in the list. |
.clearObstacles
Clear the list of obstacles.
Returns:
a BoidsND
Attributes of the flock
.centerOfMass
The position of the center of mass of the flock.
Returns:
A RealVector
.centerOfVel
The average velocity of the flock.
Returns:
A RealVector
.boids
The array of BoidUnits; i.e. an array of the agents in the flock.
Returns:
An Array
.sizeOfFlock
A convenience method to return the size of the flock. Identical to numBoids().
Returns:
an Integer
.numBoids
The number of members in the flock. Identical to sizeOfFlock().
Returns:
An Integer
.visualizer
Show a visualization of the flock. The agents are shown as wedges with the point being the position and the angle being the angle of the velocity. Targets are shown as blue circles and obstacles as red circles.
Arguments:
| whichDimensions |
A two-element array specifying which dimensions to project. |
| showLabels |
A Boolean, defaults to false. If true, the index of the agent/target/obstacle is positioned along with the wedge or circle. |
| returnWindow |
A Boolean, defaults to false. If true, return the Window instead of the instance. |
Returns:
A BoidsND or a Window.
.info
Print some basic info about the flock. Will probably be removed in the future.
Returns:
A BoidsND