PySwarm Wiki

Animation is the comprehensive set of keyframes PySwarm inserts within a Carrara scene to create realistic object animation. This page offers some practical knowledge of how PySwarm manipulates BOIDs so that you know how to set the various parameters that control BOID animation. PySwarm animates BOIDs in two fundamental ways:

  • Movement Animation involves translating and rotating BOID objects (as a whole entity) in your Carrara scene.
  • Motion Animation (starting with V0.6.2) involves cyclic transformation of components of BOID objects - translating, rotating, and resizing child objects or bones within each BOID. 

Movement Animation[]

First, PySwarm inserts keyframes into a Carrara scene to translate (reposition) and rotate (turn, bank, and pitch) BOIDs. Start and end times set the time boundaries for where to insert keyframes; keyframe rate sets the frequency of keyframe insertion. The tweener used between each keyframe inserted is the default tweener type set in your system's Preferences.

BOID movement animation was introduced in PySwarm V0.3 and will continue to evolve with each version.

BOID Translation[]

Translating BOIDs is moving BOIDs' position about your Carrara scene's 3D space over time. With each keyframe insertion, each BOID's position is updated by extrapolating the position based on the BOID's current velocity and the amount of time between keyframes. In other words, the BOID new position is the old position + new velocity x time interval. The resulting animation (driven by the tweeners) creates smooth BOID movement.

Parameters that affect BOID translation include speed controls (initial, minimum, and maximum speed), and 2D movement which limits translation to be only in the XY plane.

BOID Rotation[]

Each BOID's rotation settings are also updated with each keyframe insertion. 

Bank Pitch Heading.jpg

These rotational values are set as follows:

BOID X Rotation represents the BOID's bank (or roll). The banking angle is determined by measuring the BOID's change in heading. The greater the change in heading, the greater the banking angle. With V0.6, banking can be controlled with the following parameters:

  • Banking Factor - A multiplier to exaggerate or reduce banking effects. A value of 0.0 will force no banking.
  • Max Bank Angle - A limiter on how much a BOID will bank.
  • Max Bank Rate - This parameter limits how much a BOID can change its banking angle (in degrees) each second.

BOID Y Rotation represents the BOID's pitch (or elevation). Pitch is determined by measuring the difference in altitude between the BOID's previous z value and the current z value. With V0.6, pitching can be controlled with the following parameters:

  • Pitching Factor - A multiplier to exaggerate or reduce pitching effects. A value of 0.0 will force no pitching.
  • Min Pitch Angle - A lower angle limiter on a BOID's pitch.
  • Max Pitch Angle - An upper angle limiter on a BOID's pitch.
  • Max Pitch Rate - How much a BOID can change its pitch angle (in degrees) each second.

BOID Z Rotation represents the BOID's heading. Headings are based on the +X axis being 0 (zero) degrees heading, with rotations being counter-clockwise. The heading angle is determined by measuring the BOID's change in position in the XY plane. Heading can be controlled with the following parameters:

  • Max Turning - How much a BOID's heading can change (in degrees) each second.

Default Orientation[]

The assignments of bank, pitch, and heading to Carrara's rotational x,y,z values are not universal in all cases. These assignments change based on the BOIDs' default orientation (which direction the BOID is facing when all orientation and rotation values are cleared). A BOID whose default orientation is in the +Y axis will fly sideways using the default rotation settings. With V0.6, a new parameter (Default BOID Orientation) is used to tell PySwarm the BOIDs' default orientation. PySwarm will adjust its rotational assignments accordingly.

Motion Animation[]

PySwarm’s insertion of keyframes within each BOID to create realistic body motion (flapping wings, wiggling tail, walking, etc.) BOID motion animation will be introduced in PySwarm V0.6.2, and evolve through later versions.

Movement information, such as speed, are used to adjust motion animation.

Phase 1[]

New to V0.6.2, Motion Animation involves altering a BOID's shape or structure to simulate locomotion. The first phase of motion animation provides basic motion cycles for many natural and mechanical BOIDs.

Examples of motion animation possible with Phase 1:

  • Birds and insects flapping their wings
  • Fish moving their tails, fins, and gills
  • Car wheels rotating
  • Helicopter rotors and propellers rotating

While this phase is being designed to manipulate BOID riggings (bones), any child object of a BOID should be animateable.

Bone and child object motion animation include the ability to:

  • Manipulate the component by translation, rotation, and scaling
  • Apply the manipulation to any combination of the X, Y, and Z axes

Motion animation control - You will be able to control:

  • Animation cycle type by selecting sinusoidal, square, sawtooth, and triangle wave forms
  • Amplitude of animation: min and max values
  • Motion (cycle) frequency: duration of a cycle
  • Keyframe insertion rate

Up to 10 different motion animation “channels” can be defined, each manipulating different bones/child objects. Phase 1 animation will work with ERC and other Carrara plug-ins to enhance animation further.

You will also be able to set different amplitude and frequency values for various BOID speeds (stationary, min and max). PySwarm will adjust the motion animation based on these settings and each BOID’s current speed. This is useful in the following kinds of scenarios (examples only):

  • Car wheels spin consistent with the car’s speed
  • Fishes’ tails move faster at higher speeds, or stop when landed (stationary)
  • Bird wing motion can be more exaggerated (greater amplitude) when flying faster

Phase 2[]

Phase 2 (in PySwarm V0.7) will enhance motion animation by focusing on creating more complex banking (left/right motion) and pitching (up/down motion) animation. Motion variations can also be controlled by BOID size.

Examples of motion animation that will be possible with Phase 2:

  • Wheels that turn (steer) when a car is turning left or right (change of heading)
  • Birds flap their wings harder when in a climb versus a dive
  • VTOL jet engines that adjust side-to-side to handle banking and pitch
  • Smaller BOIDs’ wings/tails/fins that move faster than larger BOIDs

Phase 3[]

The final phase will provide human walk cycles via BVH files. PySwarm will import BVH motion animation sequences to create motion.