This plug-in for Softimage|XSI's ICE is a basic flocking solver.

On the emFlock web page you can:

• Download the demo version of this plug-in.
• Purchase the full version of this plug-in.
• Download demo and tutorial scenes.

This documentation has the following chapters:

• Chapter 1: Introduction
• Chapter 2: Installation (Windows/Linux)
• Chapter 3: Demo Version Restrictions
• Chapter 4: The Compounds
  • "emFlock __ Flocking"
  • "emFlock __ Speed Control"
  • "emFlock __ Align Orientation"
  • "emFlock __ Align Velocity on Plane"
  • "emFlock __ Fly towards Area"
  • "emFlock __ Asteroids"
• Version History
• Limitations and Remarks

If you feel that something is not well explained (or not explained at all) then please write me a short e-mail.
I will then update the documentation and/or make a demo scene as quickly as possible.

On my Vimeo page are many video tutorials in which I show and explain different aspects and techniques concerning emFlock and its usage.

Important:

• If you have a version 1.0 or higher already installed then you need to uninstall it.
  To do that go into Softimage|XSI's "Plug-in Manager", right-click on the plug-in and choose "Uninstall Addon".

This plug-in comes as a so called "Add-On", here's how to install it:

1. Open the "Plug-in Manager". It is located under the "File" menu: "File ->Plug-in Manager":



2. As mentioned above: please remove / uninstall any previous version of this plug-in. This is really important, because if Softimage|XSI finds two times the same plug-in then one (maybe even both) might not work.
3. To install the plug-in into the user directory simply right-click onto the folder "User Root" and choose "Install .xsiaddon...":



4. A browser dialogue will be displayed: go to where you copied the .xsiaddon file, select it and click on "OK". The Add-on is automatically installed.
5. Entering the license code (If you do not have a license code then you can skip this step):
   1. in the Plug-in Manager you should see the addon "emFlock (Addon)".
   2. expand "emFlock (Addon)" by clicking on the little '+' sign on its left.
   3. expand "Plug-ins".
   4. expand "emFlock Plugin".
   5. right-click on "emFlock_EnterLicenseCode" and choose "Invoke ..".
   6. a little input dialogue appears: copy your license code in here and press OK.
   7. you're done!

   

6. Close Softimage|XSI. The plug-in is now installed and ready to be used.
   For more information concerning Add-ons and how to install / uninstall them please check the chapter "Working with Add-ons" in the XSI Guides.

If you are using the full version of this plug-in then you can skip this chapter. If not, please read the following list of restrictions of the demo version:

• The flocking solver only works between frame 1 and frame 300.
• Only up to 5,000 particles simultaneously are allowed. If the number of particles exceeds 5,000 then emFlock outputs a null velocity.

Note: when you change some parameters in the demo scenes, e.g. the emission rate, and the particles suddenly stop moving or something, then you probably reached the limit of 5.000 particles or exceeded frame 300. It is NOT a bug, it's simple the demo version restriction!

The Compound "emFlock __ Flocking"

The main node of this plugin and its core is a compiled C++ node.
It calculates the flocking behavior for the particles based on their current position and velocity and then outputs a new velocity.
First a brief description of the parameters as seen in the picture of the node's PPG on the right:

• Enable
  Enables/disables the node.
• Strength
  The amount of influence this node has on the particles.
• View Cone - Distance
  The view distance. A particle will only "see" another particle if its distance is less than this value.
• View Cone - Angle
  The view angle (in degrees). A particle will only "see" another particle if it is contained in the view cone.
• View Cone - Angle Falloff
  Falloff (in degrees) for the view cone.
  The picture below illustrates the view parameters.
• Behavior - Maximum_Number_of_Neighbors
  Defines the maximum number of neighbors that will be used to calculate the flocking behavior. Using larger values results in longer calculation times and more memory usage!
• Behavior -Size Mode
  Defines how the particles size will be used when calculating the flocking. "Consider Size (Medium)" is the default value and has a good quality/performance ratio.
• Behavior - Ignore _smaller_Neighbors
  This can be used to make big particles ignore smaller particles, just as a "big fish" will probably more or less ignore a "small fish". The value defines at what point a particle is considered to be "small". Example:
  a particle of size 4 would ignore all particles of size 1 or lower if "Ignore_smaller_Neighbors" is set to 0.25.
• Behavior - Desired Distance to Neighbors
  Defines the distance a particle wants to have to the other particles. Small values will produce more dense flocks.
• Behavior - Privacy_Distance
  This distance defines the so-called "privacy distance". If particles are closer than this value they will really want to separate!
• Behavior - Privacy_Strength
  The strength of the privacy behavior.
• Behavior - Velocity Alignment
  Defines how much a particles aligns its velocity to its neighbor particles.
• Behavior - Cohesion Strength
  Defines how much a particle wants to join its neighbors.
• Miscellaneous - Multi-Processing
  Enables multi-processing (multithreading).
• Miscellaneous - Sort Neighbors by Distance -
  Sort the arrays per distance. Closest come first.
• Miscellaneous - Keep-in-Memory
  This lets you specify how data that has been calculated is cached into memory. This is only important if you are using several of the output ports.
  Tip: If you are dealing with many, many particles then set this to "Nothing". That way RAM consumption will be much smaller and should you be using only one of the output ports then the performance will remain the same.

The following picture illustrates how the view cone, the view cone falloff and the view distance are to be understood.
The view cone and view distance are very similar to a spot light, anything contained in the cone is visible for the particle.

The Input Ports

Many of the input ports have a "per object or point of point cloud" context, so that you can create complex setups by giving each particle a different behavior.

The Output Ports

In most cases you will probably only use the port "Set Flocking Velocities". It will simply set the particle velocity to the new flocking velocity that have been calculated.

But aside from the velocity the emFlock node also calculates the neighbor particles' positions, distances, etc. This data can be used to perform additional tasks, like for example:

• set the particle's color depending on the distance of the nearest neighbor.
• give particles that have no neighbors an additional behavior.
• implement an alternative flocking behavior with ICE.

The output ports and their data in detail:

• No Error
  A boolean value that indicates whether everything went fine (=true) or if an error occurred (false).
• Number of Neighbors
  The amount of neighbors for each particle.
• Neighbor IDs
  An array of integers per particle that contains the IDs of the neighbor particles.
• Neighbor Positions
  An array of 3D vectors per particle that contains the positions of the neighbor particles.
• Point->Neighbor Vectors
  An array of 3D vectors per particle that contains the vectors going from the particle to its neighbors.
• Neighbor Distances
  An array of scalars per particle that contains the distances of the neighbor particles. These values are equal the lengths of the vectors Point->Neighbor.
• Neighbor Angles
  An array of scalars per particle that contains the angles between the particles velocity vector and the vectors Point->Neighbors.
• Flocking Velocities
  The new velocities (per point) that were calculated by emFlock.

The Compound "emFlock __ Speed Control"

This node let's you control the speed of particles.

You can define a so-called "Cruising Speed". This is the speed the particle would like to have (but not necessarily have!). Depending on the value of the parameter "Strength" the particle will slowly try to reach its cruising speed.
A typical example would be a fish that accelerates in order to avoid another fish. Once the fish is avoided it will slowly return to its normal cruising speed.

The "Speed Clamp Interval" defines a velocity range for the particles, so that the speed will never drop below the minimum nor exceed the maximum speed interval.

The "Simple Drag Force" is exactly what its name suggests.

The Compound "emFlock __ Align Orientation"

A "all in one" orientation alignment node.

Use this node to align the orientation of particles. You can choose one of the six particle's local axes that shall be used. Furthermore you can specify either the velocity vector or a custom point in space to that the orientation is to be aligned.

The additional parameters "Rotational Velocity", "Up Vector", "Reduce Flipping", etc. let you create a soft orientation alignement that won't have any hard flipping.
So basically this node aligns the orientation slowly so that the animation always looks nice.

The Compound "emFlock __ Align Velocity on Plane"

This node affects the alignement of the velocity vector.

For a given plane (defined by its normal vector) the velocity of the particles will slowly be modified in order to be parallel to the plane. The parameter "Strength" controls how fast the velocity is aligned.
This node is can be very handy because even though it modifies the velocity it still gives other effects enough room to operate.

A typical example:
You have a flock of fish that, most of the time, swim parallel to the ground. Sometimes a fish needs to avoid another fish so it might swim up to avoid it. Once that is done this node will make the fish slowly go back to its "normal" swimming direction.

The Compound "emFlock __ Fly towards Area"

This node modifies the direction (not the speed) of particles so that they fly towards a goal defined by a position as well as a radius, similar to a Disc Area Light.

The parameters:

• Active
  Enables/disables the compound.
• Strength
  The strength of the goal. Note that you can use values greater than 1 as well as negative values.
• Disc - Position and Radius
  The position and radius of the sphere/disc.
• Distance Falloff
  If enabled then the goal has less effect when far away.
  When the particle is further away than "Length" then the goal has no effect.
• Cone Falloff
  This defines the view cone of the goal: a particle only "sees" the goal if latter is inside the view cone.
• Rotational Velocity
  Let's you limit the rotational velocity so that the particles turn more smoothly towards the goal.

Thanks to its radius the goal has an area so that particles do not fly towards the center of the goal but rather to the closest point of the area. The picture below shows the trajectories of particles that move towards a point goal (top) and an area goal (bottom).

The Compound "emFlock __ Asteroids"

This little node lets you define what I call a "playfield" for the particles. It is simply a bounding volume described by two points. Whenever particles leave the playfield they will try to go back in, depending on the "mode".

• New in Version 1.0:

  everything is new because this is version 1.0.

• New in Version 1.1:

  • The octree and the multithreading have been entirely re-programmed resulting in better performance and more accurate calculations.
  • The main flocking compound has been cleaned up.
  • A few minor bug fixes.
  • This version is compatible with older emFlock versions => Scenes that were created with emFlock 1.0 and 1.02 will work fine with this new version.

Things you should avoid when working with emFlock:

• nothing.

Known issues:

• "sorry, but there currently is no license available
  this can occur even when there are enough licenses available. The most probable cause is that you do not have write permission for the current project.

• "sorry, but there currently is no license available
  if you are working with the full version of emFlock and your current project is "XSI_SAMPLES" then emFlock might not evaluate properly and display the above message.