PySwarm Wiki
Register
No edit summary
No edit summary
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[File:PIA_About.jpg|thumb|400px|PIA App Start Screen]]__TOC__
+
[[File:PIA_About.jpg|frame|PIA App Start Screen]]__TOC__
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +
   
 
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.
 
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.
Line 6: Line 16:
   
 
[[File:Process.jpg|frame|left|Sequence to creating a Carrara animation scene]]
 
[[File:Process.jpg|frame|left|Sequence to creating a Carrara animation scene]]
 
 
 
 
   
   
Line 23: Line 29:
   
 
==Installing PIA==
 
==Installing PIA==
<span style="font-size:14px;line-height:22px;">To read about installing the PIA application as part of installing the PySwarm package, click </span>[http://pyswarm.wikia.com/wiki/Download_and_installing_PySwarm#Latest_Version_of_PySwarm here]<span style="font-size:14px;line-height:22px;">.</span>
+
<span style="font-size:14px;line-height:22px;">To read about installing the PIA application as part of installing the PySwarm package, click </span>[http://pyswarm.wikia.com/wiki/PySwarm_Installation_and_Removal_Procedures here]<span style="font-size:14px;line-height:22px;">.</span>
   
 
==Running PIA==
 
==Running PIA==
Line 32: Line 38:
 
When you first run PIA, the following screen will appear:
 
When you first run PIA, the following screen will appear:
   
[[File:PIA_About_old.jpg|frame|left|PIA Start Screen]]
 
   
   
 
[[File:PIA_V2_Initial.jpg|left]]
   
   
Line 99: Line 105:
   
 
==Managing PySwarm Projects==
 
==Managing PySwarm Projects==
  +
You can find information about managing PySwarm projects at the following wiki page: [[Managing PySwarm Projects|link]].
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 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, new projects are always initialized to the default settings.
 
#And second, you can quickly and easily reset a project's parameters back to the default settings (described below).
 
[[File:PIA_Project_Selection.jpg|frame|left|Project Selector]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
You can change the default settings to your personal preferences at any time. For example, suppose you prefer to name the Carrara camera you want PySwarm to manipulate "PySwarm Camera." You can enter this name into the ''Camera Name'' field for the Default project, and that name will automatically be used when you create a new project. (Changing default settings will not affect projects already created.)
 
===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.
 
[[File:New_Project.jpg|frame|left|New Project dialog window]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
I recommend choosing project names that match your Carrara scene files' names.
 
 
Also, PIA will allow you to enter multiple projects with the same name if you choose. It is your responsibility to remember which project goes with what scene.
 
 
===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 load the parameter settings last saved for that project into the form fields.
 
 
===Saving the Parameter Settings===
 
<span style="font-size:14px;">PIA will automatically save all the settings before generating a script or exiting the program. However, </span><span style="font-size:14px;">since there is always the chance of a system error (e.g., "Blue screen of death") or power failure,</span><span style="font-size:14px;"> </span><span style="font-size:14px;">clicking the "Save Project Parameters to File" button will </span><span style="font-size:14px;">force a save of the entire set of projects' parameter settings</span><span style="font-size:14px;">. I suggest periodically clicking this button while you are working in PIA.</span>
 
 
[[File:Save_Project_Parameters_button.jpg|left]]
 
 
 
 
 
===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 your preferred default settings than it is 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.''
 
 
[[File:Reset_Parameters_Button.jpg|left]]
 
 
 
 
 
 
===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==
 
==Working With the Parameters==
 
All of the PySwarm parameters necessary to create BOID animation sequences are accessible through PIA<span style="font-size:14px;">. 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.</span>
 
All of the PySwarm parameters necessary to create BOID animation sequences are accessible through PIA<span style="font-size:14px;">. 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.</span>
===Parameter Tabs===
+
==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 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.
[[File:PIA_Parameter_Tabs.jpg|frame|left|PIA Parameter Tabs]]
 
   
  +
[[File:PIA_V2_Tabs.jpg|left]]
   
   
Line 197: Line 122:
   
   
 
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. 
 
The first three tabs (About, Scene, and BOIDs) provide access to general PySwarm parameters; e.g., those related to animation sequencing, cameras, BOID naming, and BOID initialization. Each of the remaining tabs relate to each of the eight 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.
 
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===
 
===More About The Parameters===
 
*About parameters - PIA's main window, it displays the version number and the pointer to the source script shell file.
 
*About parameters - PIA's main window, it displays the version number and the pointer to the source script shell file.
*[[Scene Parameters|Scene parameters]] - General parameters related to the Carrara scene
+
*[http://pyswarm.wikia.com/wiki/PIA_(V2)_Scene_Parameters Scene parameters] - General parameters related to the Carrara scene
*[[BOIDs Parameters|BOIDs parameters]] - Those related to initial BOID settings and motion operations
+
*[http://pyswarm.wikia.com/wiki/PIA_(V2)_Initialization_Parameters Initialization parameters] - Those related to initial BOID settings and motion operations
  +
*[http://pyswarm.wikia.com/wiki/PIA_(V2)_Movement_Parameters 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
 
*Rules parameters - The remaining tabs are related to each of the eight PySwarm rules
**[[Cohesion Rule|Cohesion]] - BOIDs attempt to group together by moving towards the group’s center of mass (the average of all BOIDs’ positions).
+
**[[PIA (V2) Cohesion Rule|Cohesion]] - BOIDs attempt to group together by moving towards the group’s center of mass (the average of all BOIDs’ positions).
**[[Separation Rule|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.
+
**[[PIA_(V2)_Separation_Rule|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 Rule|Alignment]] - BOIDs attempt to match their velocity (speed and heading) with the others in the group.
+
**[[PIA_(V2)_Alignment_Rule|Alignment]] - BOIDs attempt to match their velocity (speed and heading) with the others in the group.
**[[Containment Rule|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.
+
**[[PIA_(V2)_Containment_Rule|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 Rule|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.
+
**[[PIA_(V2)_Attraction_Rule|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 Rule|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.
+
**[[PIA_(V2)_Landing_Rule|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.
**[[SpeedLimit Rule|Speed Limit]] - BOIDs cannot go less than or exceed a specified speed range.
 
**[[MaxTurn Rule|Max Turn]] - BOIDs are limited in the turning angle that they can make. For example, planes and cars cannot turn completely around instantaneously.
 
 
<span style="font-size:17px;">Active Rule Quick Reference</span>
 
<span style="font-size:17px;">Active Rule Quick Reference</span>
 
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.
 
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.

Latest revision as of 02:49, 26 January 2014

PIA About

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.

Process

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:


PIA V2 Initial
















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.

Selecting the Script Shell

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.

PIA V2 Tabs





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. 

Generate Script button



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.