PySwarm Interface Application (Main Page)

PIA App Start Screen

Starting with PySwarm V0.5, you no longer need to directly edit the PySwarm Python script to generate your animation sequences. Instead, you now select the rules and enter parameters through the "PySwarm Interface Application" (PIA). PIA will build the PySwarm script for you. Once the script is built, you import the resulting file into Carrara scene.

How PIA Works

PIA build a Python Script file using a PySwarm Shell (a text file) with the Python language commands, along with the rules and parameters you have set. Using the "Import" command in Carrara, you import the PySwarm Script file into your Carrara scene. PyCarrara, a plug-in for Carrara, reads the script you are importing, and inserts keyframes that animate the BOID objects in your scene, ready to render.

Sequence to creating a Carrara animation scene

Installing PIA

To read about installing the PIA application as part of installing the PySwarm package, click here.

Running PIA

To run the PIA application, you can either:

• Use WIndows Explorer to navigate to the folder containing PIA.exe, and clicking (or double-clicking) on the icon.
• Drag and drop the PIA.exe icon to your desktop and/or your taskbar, and launch the application from there.

Getting Started with PIA

When you first run PIA, the following screen will appear:

Selecting the Script Shell

The first thing you will want to do is to tell PIA where to find the PySwarm Source Script Shell. This text file contains the shell (or wrapper) Python script text PIA will need to generate the PySwarm script. The reason the PySwarm script is generated this way is to simplify updating the shell file ("PySwarm Shell Vxx.txt") without having to update the application.

To set this field, click the "Browse..." button next to the Script Shell field. This will cause the "Open" dialog window to appear. If you followed the installation instructions above, the file named "PySwarm Shell V__.txt" should appear in the list. (The "__" refers to the PySwarm script version number.) If not, you will need to navigate to the folder containing the shell file. Select the shell file from the list and click the "Open" button.

Browsing for the PySwarm Script shell file

The PySwarm Source Script Shell field should now show the directory and file name for generating PySwarm scripts. Once this field points to the shell text file, you won't need to update this again until you update the shell file with a new version (e.g., a new release).

Managing PySwarm Projects

You can find information about managing PySwarm projects at the following wiki page: link.

Working With the Parameters

All of the PySwarm parameters necessary to create BOID animation sequences are accessible through PIA. Before beginning to set the parameters, make sure you have selected the right project you want to work with (as described above). The currently selected project name always appears in drop-down menu under "PySwarm Projects" near the bottom of the PIA window.

Parameter Tabs

The PySwarm parameters have been organized into areas accessible via a number of tabs at the top of the PIA window. Click on a tab to display the parameters related to that area.

The first five tabs (About, Scene, and BOIDs) provide access to general PySwarm parameters; e.g., those related to animation sequencing, cameras, BOID naming, BOID initialization, and movement and motion animation settings. Each of the remaining six tabs relate to each of the six PySwarm rules.  You may note some of the rule tabs are highlighted in a dark color (as in the image above). This allows you to quickly note which rules are currently active for your project.

More About The Parameters

• About parameters - PIA's main window, it displays the version number and the pointer to the source script shell file.
• Scene parameters - General parameters related to the Carrara scene
• Initialization parameters - Those related to initial BOID settings and motion operations
• Movement parameters - Parameters regarding how to control BOID movement
• Motion parameters - This tab is currently not activated.
• Rules parameters - The remaining tabs are related to each of the eight PySwarm rules
  • Cohesion - BOIDs attempt to group together by moving towards the group’s center of mass (the average of all BOIDs’ positions).
  • Separation - BOIDs attempt to keep some predefined safe distance between themselves and all other BOIDs. You can think of this like BOIDs attempting to keep some personal space. This works to counteract too much COHESION.
  • Alignment - BOIDs attempt to match their velocity (speed and heading) with the others in the group.
  • Containment - BOIDs attempt to stay inside (safe) or outside (restricted) specified regions of space. When BOIDs venture outside safe regions or inside restricted regions, they will naturally try to alter their course to go back inside the closest safe region.
  • Attraction - BOIDs attempt to move towards a specified object in the Carrara scene. Like “moths to a flame,” use an attractor to draw BOIDs towards a specific location in your scene. Also, when attractor objects move around in the scene, the BOIDs will attempt to follow. So you can use an attractor to draw BOIDs along a specified path or route.
  • Landing - BOIDs land on the ground if they fly to (strike) it. When BOIDs land, they will remain there for some random period of time, as determined by the rule's parameters.

Active Rule Quick Reference You will note some of the tabs may be shaded in a dark color. Tabs are shaded when you activate that PySwarm rule. This gives you a quick reference to know which rules you currently have turned on before generating your script.

Context Help Features

If you are not sure what a parameter is for, slide your cursor over the form field. A short context-sensitive help will pop up with a brief description.  If you need more information about a parameter, you can click the "Online Help" button at the bottom of the PIA window. PIA will launch your default internet browser and bring up the wiki page related to the tab you have currently selected.

Generating the PySwarm Script

Once you have set all of your project's parameters, you are ready to generate the PySwarm script. Click the "Generate Script..." to the start the process. 

Remember you cannot generate scripts from the default settings.

To read details about generating the PySwarm script, click here.

Quitting PIA

To exit the program, click the "Exit" button or the Close "X" icon in the top right corner of the window. PIA will ask you to confirm exiting, and then automatically save the project parameter settings to the "Projects.pys" file before closing.