Starting with PySwarm V0.5, you no longer need to 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), and PIA builds 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 install the application, simply copy the following two files into the directory of your choice. The application does not need to be registered with WIndows to run. However, I do recommend you create a new directory to hold the application files, so they can be easily updated when new versions become available. There are only two files needed to create your PySwarm scripts.
- PIA.exe - The application executable.
- PySwarm Shell Vxx.txt - A shell or wrapper containing the PySwarm Python script / program, excluding the parameter settings.
Once you have copied these two files to your directory, you can drag and drop the PIA.exe icon to your desktop and/or your taskbar, and launch the application from there.
Note that once you have run the application the first time, two new files will appear in the application's directory.
- Script.pys - Contains the string that points to the current PySwarm shell needed to generate your PySwarm scripts.
- Projects.pys - Contains the parameter settings for your PySwarm projects.
You should not edit or delete these files, as they contain important settings and information PIA uses related to your projects, and how to generate PySwarm scripts. However, if for any reason they are deleted or corrupted, PIA will recreate them.
Running PIA
To run the PIA application, you can:
- 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:
PIA Screen
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 Vxx.txt" should appear in the list. 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 contain the directory sequence and file name needed to generate 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
PIA allows you to maintain up to nine (9) projects at a time. You can think of each project as relating to an unique Carrara animation scene you are working on. Each project contains its own complete set of parameter settings. You can easily switch between projects without loosing work you've done on another.
The Default Settings
The first project in the project list is always called "Default." You will not be able to generate PySwarm scripts from this entry. However, this parameter set is useful for two reasons. First, when you add new projects, they are always initialized to the default settings. And second, you can quickly and easily reset a project's parameters back to the default settings.
PySwarm Project selector
As such, you can change any of the settings to your personal preferences at any time. For example, suppose you always name the Carrara camera object you manipulate with PySwarm "PySwarm Camera." By entering that string into the Camera Name field for the Default project, that name will automatically be entered when you create a new project.
Adding a New Project
To add a project to the PySwarm project list, click the "New" button next to the project drop-down menu. When the "New Project" dialog window appears, enter an unique name for the project and click "Ok." PIA will create a new project entry and initialize all of the parameter settings to their default values.
New Project dialog window
It is recommended you choose project names that closely match the names of the Carrara scene files' names.
Also, note that PIA will allow you to enter multiple projects with the same name if you so desire.
Selecting a Project to Work With
To select a project, click the down arrow to the right of the project drop-down menu, then select the name of the project. PIA will automatically load the parameter settings last saved for that project into the form fields.
Saving the Parameter Settings
At any time while working with PIA, you can force a save of the entire set of projects' parameter settings to the "Projects.pys" file by clicking the "Save Project Parameters to File" button. While PIA will automatically save all the settings before generating a script or exiting the program, this button is useful in case of a system error (e.g., "Blue screen of death") or power failure. I suggest periodically clicking this button while you are working with setting your project parameters.
Resetting Project Settings Back to Default
There might be occasions when it is easier and/or faster to reset your currently selected project parameters back to the default settings than to edit them. You can do this by clicking the "Reset Parameters to Default" button, and then confirm the reset by clicking "OK" in the Confirmation dialog window. Only the currently selected project's parameters are reset.
Deleting a Project
While being able to work with up to 9 projects at a time may seem like a lot, there may be times when you need to do some clean-up. Once you have completed a Carrara project and you no longer need the project entry, you can reclaim the entry in the project list by selecting the project and clicking the "Delete" button. Then confirm the delete action by clicking "OK" in the Confirmation dialog window.
Working With the Parameters
PIA provides the ability to manipulate and modify all of the PySwarm parameters available to create BOID animation sequences. To begin modifying 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" at the bottom of the PIA window.
Context Help
If you are not sure what what a parameter is for, start by sliding your mouse cursor over the field. A short context-sensitive help will pop up providing a brief description. If more details are needed, refer to this Wiki section for further details.
Parameter Organization
All of the PIA parameters are organized into tabs as described below. Click on the hyperlink to bring up more details about the parameters.
- Scene parameters - General parameters related to the Carrara scene
- BOIDs parameters - Those related to initial BOID settings and motion operations
- 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.
- Speed Limit - BOIDs cannot go less than or exceed a specified speed range.
- Max Turn - BOIDs are limited in the turning angle that they can make. For example, planes and cars cannot turn completely around instantaneously.
Note that when a rule is activated, that rule's tab is highlighted. This makes it easy to see which rules are currently active for your project.
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.