PySwarm Wiki

Back to PIA's main page


This tab of parameters relate to general BOID settings - initial positioning, initial heading, initial speed, and some animation settings such as banking.

BOID Naming and Numbers[]

Two important parameters for animation are the BOIDs' base name and the number of BOIDs to be animated.

BOIDs Name[]

This parameter contains the base name of the BOIDs in your Carrara scene. The base name is the name without the numbers that follow. Click here to learn more about naming your BOID objects.

Number of BOIDs[]

Set this to the number of BOIDs you want PySwarm to manipulate. The number must be at least 1 and cannot exceed the number of BOIDs you have created in your scene.

Tips and Limitations[]

  1. There are no restrictions on the base name you can use for the BOIDs that make up the BOID group. However, a sequential number must be appended to each BOID object’s name in your Carrara scene, so that PySwarm can correctly identify the BOIDs. For example, you would define the names of the BOIDs in your Carrara scene as: ‘Spider1’, ‘Spider2’, ‘Spider3’, …, ‘Spider10’, ‘Spider11’, etc. Note there is no ‘0’ between ‘Spider’ and ‘1’ in the first BOID’s name.
  2. BOID names are not case sensitive. In the example above, PySwarm would find the same BOIDs if you used the text ‘spider1’ or ‘SPIDER1’ in the field.
  3. You must have at least 1 BOID to animate.
  4. You don't have to animate all BOIDs during an import. For example, you could have 50 BOIDs defined in your Carrara scene. But if you select 10 for Number of BOIDs, only the first 10 will be animated.
  5. The number of BOIDs PySwarm can handle is limited to your computer's memory and the complexity of BOID objects. There is nothing in PIA or in the PySwarm script that sets a maximum number. So far, I have tested PySwarm to up to 225 BOIDs. 

Initial Position Parameters[]

Positioning Options[]

Starting with PySwarm V0.4, there are three options available to initialize the starting positions of the BOIDs in the scene:

  1. Use the current placement of the BOIDs (don’t move them)
  2. Place them randomly inside containment zone #1
  3. Place them randomly inside a sphere with a predefined center and radius flat surface)

Sphere's Radius[]

The radius of the sphere (in feet) when the third positioning option is selected.

Sphere's Center[]

The center of the sphere (x,y,z coordinates in feet) when the third positioning option is selected.

Tips and Limitations[]

  1. If you are creating a multiple segment animation, you will probably want to use the "Current BOID Position" option after the first segment has been imported. This will force PySwarm to use the current position for animating the next segment.
  2. The Containment Rule does not have to be activate to use the "Inside Containment Zone #1" option; however, you will still need to check Zone #1's "Active Zone" checkbox (in the Containment tab).

Initial Heading Parameters[]

Heading Options[]

There are now three options to initialize the heading of BOIDs at the start of the animation sequence.

  1. Use the BOIDs' current heading
  2. Randomly set the heading of each BOID
  3. Use a predefined heading (described using the "Initial Heading" and "Initial Pitch" parameters below).

Initial Heading[]

When the third option is selected, all BOIDs' heading begins with this value (in degrees). A value of 0.0 degrees points in the +x axis; 90.0 degrees in the +y axis; etc.

Initial Pitch[]

You can also specify the angle (in degrees) that all BOIDs will move in (up and down). A positive angle positions the BOIDs moving upwards; a negative angle points the BOIDs downwards. This angle cannot exceed +/- 90.0 degrees.

Tips and Limitations[]

  1. BOIDs' speed is set using the "Initial Speed" parameter described below.

Motion Parameters[]

Initial Speed[]

This parameter is used to initialize all BOIDs' speed (in feet per second).

Use Banking[]

Starting with V0.4, PySwarm calculates banking angles for BOIDs, tilting the BOIDs to simulating banking or rolling. However, in some situations, you don’t want banking – for example, people walking do not bank when they turn. Check this parameter to turn ON banking effects.

Localize Rules[]

When checked, this will force PySwarm to only allow each BOID to be affected by other BOIDs in close proximity.


If Localize Rules is checked, this value is the radius (in feet) that affects each BOID's Cohesion and Alignment rules.

Limit to 2D (x,y) Motion[]

Checking this parameter tells PySwarm you want to limit all BOID motion to the x,y plane.

2D Height[]

If the Limit 2D Motion parameter is checked, PySwarm will use this value to set the height (Z axis) for all BOIDs during the animation sequence. 

Tips and Limitations[]

  1. PySwarm will warn you if Speed Limit Rule is activated and Initial Speed is not between the Min and Max Speed settings. If you choose to continue, PySwarm will immediately clip BOIDs' speed to be within the Min and Max Speed settings.
  2. Initial Speed is also used to initialize the speed of BOIDs that are exiting LANDED mode.
  3. If Cohesion and Alignment Rules are not activated, the "Localize Rules" parameter will not have any effect.
  4. If you use Limit 2D Motion while initializing the BOIDs using current location, PySwarm will reset the BOIDs’ z-axis value with Initial Height (but will not adjust the x- or y-axes).