Description
Boids3D is an implementation of the Reynolds boids algorithm, optimized for three 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:
| 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 Boids3D.
Instance Methods
.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 Boids3D
.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 BoidUnit3D's.
.bounds
The bounds of the space in which the flock moves in meters.
Arguments:
| dim |
The new dimensions in a three element array. [1000, 1000, 1000] is a cube with 1000 meters on each side such that the range and domain are both +/-500. When using the getter, bounds() would return [[-500,500], [-500,500],[-500,500]]. |
Returns:
An Array (getter) or a Boids3D (setter)
.wrap
Boolean on whether or not to wrap the agents in the space. Defaults to false.
Arguments:
| boolean |
Returns:
A Boolean (getter) or a Boids3D (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 Boids3D (setter)
.sd
The standard deviation in decimal percent for the agents in the flock. Defaults to 0.05 (5%).
Returns:
A Float (getter) or a Boids2D (setter)
Discussion:
Flocking Rules and Moving the Flock
.centerInstinct
The weight of the center-seeking rule, Gaussian-distributed.
Returns:
A Boids3D
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 Boids3D
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 Boids3D
Discussion:
The velocity matching rule moves each agent causes each agent to align in terms of direction and speed with its six nearest neighbors, regardless of their absolute distance. Setting this to 0 causes the agents to ignore one another, resulting in something that more closely resembles a swarm of insects.
.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 Boids3D
.minSpace
The minimum space between agents in meters, Gaussian-distributed.
Arguments:
| val |
The minimum space between agents in meters. |
Returns:
A Boids3D
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 Boids3D. |
Returns:
A Boids3D
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 RealVector3D of the x, y, and z positions) and \strength (a Float of the strength of the target).
Arguments:
| pos |
An Array that describes the position of the target in (x,y, z). This is converted internally to a RealVector3D. |
| gravity |
A Float describing the strength of the target. |
Returns:
A Boids3D
pos must be a three-element array.
The field of the gravity falls off at a rate of 1/r where r is the radius in meters.
Discussion:
Gravity can also be applied along a line. By giving the gravity argument as an Array of two elements, gravity will be applied to different degrees in those dimensions. For instance, [0,1,2] will apply a gravity of 1 along the y-dimension, a gravity of 0 along the x-dimension, and a gravity of 2 along the z-dimension.
.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 Boids3D
.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 Boids3D
.obstacles
An array of the obstacles. Each target is a Dictionary of two elements: \pos and \strength.
Returns:
An Array of Dictionaries
.addObstacle
Add a target. Each target is a Dictionary containing two elements: \pos (A RealVector3D of the x, y, and z positions) and \strength (a Float of the strength of the target).
Arguments:
| pos |
An Array that describes the position of the target in (x,y, z). This is converted internally to a RealVector3D. |
| repulsion |
A Float describing the repulsion of the obstacle. |
Returns:
A Boids3D
pos must be a three-element array.
The field of repulsion falls off at a rate of 1/r^2 where r is the radius in meters.
Discussion:
Repulsion can also be applied along a line. By giving the repulsion argument as an Array of two elements, repulsion will be applied to different degrees in those dimensions. For instance, [0,1,2] will apply a repulsion of 1 along the y-dimension, a repulsion of 0 along the x-dimension, and a repulsion of 2 along the z-axis. Note that because the way movement is calculated, it is possible for the agents to penetrate the barrier with sufficient momentum.
.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 Boids3D
.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 Boids3D
Attributes of the flock
.centerOfMass
The position of the center of mass of the flock.
Returns:
A RealVector3D
.centerOfVel
The average velocity of the flock.
Returns:
A RealVector3D
.boids
The array of BoidUnits; i.e. an array of the agents in the flock.
Returns:
An Array
.getPanVals
A convenience method that returns an array of three-element arrays of values useful for use as a panner in the form [dist, azi, angle] where dist is the distance from the origin in meters, angle is the angle about the origin in radians, and azi is the elevation in radians with the horizon at x=0 Likewise, 0 radians is at 3 o'clock..
Also see BoidUnit3D.getPanVals.
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 Boids3D or a Window.
.info
Print some basic info about the flock. Will probably be removed in the future.
Returns:
A Boids3D