PIA (V2) Scene Parameters

Back to PIA's Main Page

Scene parameters are those that relate to the general animation of your Carrara scene.

BOID Naming and Numbers

Two important parameters for animation are the BOIDs' base name and the number of BOIDs to be animated. These parameters are needed so PySwarm can find all of the BOIDs in the scene to be manipulated.

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 (though it can be less).

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. 

Time Parameters

Time parameters relate to the timeframe you want PySwarm to insert keyframes for BOID animation.

Start Time

Set this parameter to the time in the animation (in seconds) to start inserting keyframes.

End Time

Set this parameter to the time in the animation (in seconds) to stop inserting keyframes.

Tips and Limitations

1. You can start and end the PySwarm sequence anytime in your Carrara scene. It is up to you to make sure the sequence is within your render start-end sequence.
2. You can create more complex PySwarm sequences by segmenting your animation, changing the parameter settings between each one. For example, you could create a script for time 0.0 to 2.0 seconds with one set of parameter settings, then create another script for time 2.0 to 4.0 seconds with different settings. This will cause the BOIDs to suddenly change behavior in the middle of the animation.

Keyframe Parameters

Keyframe parameters relate to how PySwarm is to insert keyframes in the BOIDs' sequencer.

Rate

This value is used to tell PySwarm the frequency of inserting keyframes into the animation sequence. The value is in frames per second. A value of 10.0 will insert 10 keyframes per second for each BOID. For an animation set to render at 30 frames per second, then 1 keyframe will be inserted for every 3 frames of rendering.

Clear Keyframes at Start

Starting with V0.4, it is possible to run multiple PySwarm scripts for different timeframes within a single simulation. As such, you don’t want PySwarm to clear keyframes inserted in previous imports. Check this box if you want PySwarm to clear the existing keyframes before inserting new ones. If you are importing a PySwarm script multiple times (performing test runs), you will probably want to clear the keyframes.

​Tips and Limitations

1. I generally recommend that you set the keyframe insertion rate to be a multiple of the animation rate, though this is not necessary. For example, if you are rendering your animation at 24 frames per second, I suggest you use insertion rates of 1, 2, 3, 4, 8, 12, or 24 keyframes per second. Some BOID animations may not flow smoothly if you do not do this.
2. You can generate keyframes greater than your animation rate (frames per second); however, I have not found this to be of any value and it consumes more memory.
3. The keyframe rate can be any positive number - 1, 2, 3, etc. or it can be 2.5, 3.1214, or 8.66666. 
4. To insert keyframes at a rate less than 1 per second, use a fractional number. For example, using a value of 0.25 will insert a keyframe every 4 seconds.
5. The Clear Keyframes parameter will wipe out ALL keyframes for all BOIDs if this field is checked. If you are creating your animation in segments, be sure to uncheck this parameter after the first segment.
6. If you activate camera and camera focus manipulation (see below) and you have Clear Keyframes checked, all previously inserted keyframes for these objects will be wiped as well.
7. Keep in mind that if are are re-running a script for an animation sequence, and you have not changed the keyframe insertion rate, PySwarm will overwrite the previous keyframes, so in such cases, it is not necessary to check the Clear Keyframes parameter.

Camera Parameters

Camera parameters relate to having PySwarm insert keyframes for a camera in your Carrara scene. Camera manipulation is currently limited to moving the camera relative to the BOIDs' center of mass.

Manipulate Camera

Check this box to activate camera manipulation.

Camera Name

Enter the name of your Carrara scene's camera object you wish PySwarm to track with the BOID group.

Camera Offset

This 3-D (x,y,z) value determines where to place the camera relative to the BOIDs' center of mass. For each keyframe inserted, the camera is repositioned (x,y,z) feet from the computed group center. The result is a camera that tracks the movement of the group. 

Tips and Limitations

1. Currently, only one Carrara camera can be manipulated by PySwarm.
2. Use larger (x,y,z) values for the Camera Offset to position the camera farther from the BOIDs' center.

Camera Focus Parameters

The camera focus parameters tell PySwarm to move (manipulate) a specific object in your Carrara scene. Focus manipulatin is currently limited to keeping the focus positioned at the BOIDs' center of mass. By setting your scene cameras to focus on this object, they will (generally) keep the BOIDs in the screen area. Examples of objects that make good focii are target helpers and basic (invisible) primitives.

Manipulate Focus

Check this box to activate focus manipulation.

Focus Name

Enter the name of the object that will be used to point the camera at the group.

Tips and Limitation​

1. A Target Helper makes a good camera focus object, though any object in your scene will work (e.g., a primitive ball). 
2. I recommend the Carrara object you select as the camera focus not be used for any other purpose, and that you set your focus object to invisible.
3. Add a “Point At” modifier to the camera(s) you wish to use to track the group, and select this focus object in the “Towards” list.

Randomness

You can alter the randomness of the simulation by changing the simulation seed value.

Simulation Seed

Changing this value alters the randomization effects when importing the PySwarm script. If a specific seed value does not provide a good animation sequence, you can always try a different seed.

Tips and Limitations

1. Currently, randomization is limited to Initial positioning of BOIDs for "Inside Container" and "Inside a Sphere" options and Initial velocity of BOIDs for "Random speed and heading" option
2. Later versions of PySwarm will use randomization more extensively.