This plug-in for Softimage|XSI's ICE is a fluid solver for creating fire and smoke effects.

On the emFluid3 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
  • the typical Setup: a Group of Compounds
  • "emFluid3 _ Main" and the typical Setup (cont.)
  • the compound "explode me"
  • the input ports
  • the output ports
    • the first two "execute" ports
    • the following five ports
    • the "Burn Positions (Array)" port
    • the "Grid (Array)" ports (advanced users)
  • "emFluid3 _ Particle Emitter"
  • "emFluid3 __ Behavior"
  • "emFluid3 __ Behavior Advanced"
  • "emFluid3 __ Debug"
  • "emFluid3 ___ Emit Pass Through"
  • "emFluid3 ___ Emit Settings"
  • "emFluid3 ___ Emit Data from SRT"
  • "emFluid3 ___ Emit Data from Points"
• Version History
• Limitations and Remarks
• Epilogue: Thanks

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 emFluid3 and its usage. You might also try to search for "emFluid3" on Vimeo to find some videos made by other people, as for example Oliver's cool "How to setup a flamethrower with emFluid3, emRPC and MR" tutorial.

Important:

• If you have a version 3.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".
• emFluid2 and emFluid3 can co-exist and be used simultaneously. You need not uninstall your emFluid2 version if you still want to use it.

Note: Scenes that were created using versions 3.01 (or higher) of this plug-in will work just fine with this new version.

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.
   Note: this does NOT concern emFluid2. emFluid2 and emFluid3 can co-exist.
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. 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 parameter "Simulation Start Frame" has no effect: the fluid buffer simulation always begins at frame 3.
• The parameter "Cell Size" has no effect: the cell size is always 1.
• After 250 frames the fluid buffer is cleared and not simulated any more, so you must start playback again from frame 1.
• Only up to 10,000 particles simultaneously are allowed. If the number of particles exceeds 10,000 then emFluid3 has no effect on the particles.

Note: when you change some parameters in the demo scenes, i.e. the emission rate, and the particles suddenly explode or something, then you probably reached the limit of 10.000 particles. It is NOT a bug, it's simple the demo version restriction!

This chapter covers all the compounds that belong to emFluid3.

Note: all of the emFluid3 compounds are "public", meaning that you can look inside the compounds to see how things are done. This also means that you have the possibility of modifying the existing compounds, i.e. you could add further functionality to some of the compounds to meet the needs of a special project.

The typical Setup: a Group of Compounds

The typical emFluid3 setup is not just a single compound but rather a group of several compounds that need to be connected in a very specific way.
In the following video an overview of the main setup and its different compounds is given.

The Compound "emFluid3 _ Main" and the typical Setup (cont.)

The main compound of this plug-in is quite a "monster", especially due to all its output ports, and even though it might seem a little intimidating at first sight it is in fact quite easy to use.

This main compound won't work on its own, it requires a few additional compounds to be plugged into it. These additional compounds are

• "emFluid3 Behavior" -> into the "In Behavior" port.
• "emFluid3 Debug" -> into the "In Debug" port.
• "emFluid3 Emit Pass Through" -> into the "In Data 1/2" ports.

Should you be interested in building your setup entirely from scratch then please take a look at the following video tutorial:

The input ports

• Main/Miscellaneous
  • Enable
    Enables/disables the whole plug-in
  • Multi-Processing
    Enables/disables multi-threading for the internal fluid solver.
    This is "off" by default. The reason is that for normal sized fluid boxes the single-threaded version is actually a little faster! But if you are working with Linux or have a big fluid box then enabling this will increase performance.
  • Weight
    Defines the weight (or influence) the fluid box has on the particles inside it.
  • In Fluid Box SRT
    Plug the object that defines your fluid box in here. Please note that the fluid box is not defined by the geometry's bounding box but by the object's global SRT ! So the best thing to do is to get a cube, set its length to "1" and then resize it by scaling it.
  • In Point Velocity
    Plug the particle velocity in here.
• Fluid Solver
  • Cell Size
    This defines the cell size in global SI units. Smaller cells require more memory and more calculations.
  • Viscosity
    The viscosity of the medium. Use values around zero for gases (i.e. air and smoke) and higher values for syrup like mediums.
  • Vorticity
    This parameter lets you add more swirls and "cool movements" to your simulation. Any value is allowed (even negative values) but values between 0 and 15 usually produce the best results.
  • Gravity
    This defines the amount of gravity for the solver. You can also use negative values to inverse the gravity.
  • Gravity Direction
    This 3D vector defines the global direction of the gravity. The direction is not affected by the rotation of the fluid box, so no matter how you rotate your fluid box, the gravity will always point to the same spot.
  • In Behavior
    The compound "emFluid3 Behavior" must be plugged in here.
  • In Debug
    The compound "emFluid3 Debug" must be plugged in here.
• Velocity Mapping
  • Multiplier
    Lets you multiply the amount of velocity that is mapped from the fluid box to the particles.
    Negative values and values greater than one are possible.
    Note: this parameter is "per Object" or "per Point of Point Cloud".
  • Anti-Stratification
    This is the solution to get rid of those ugly "sausage-like" particle clusters that often occur at the border and in the corners of the fluid box.
    Note: this parameter is "per Object" or "per Point of Point Cloud".
• Obstacles
  • Use Obstacles
    Enables/disables the use of obstacles.
  • Static Obstacles (recommended)
    When this is enabled then obstacles are static, meaning that they are set once at the beginning of the simulation and then not updated any more. It is recommended to use this option because non-static obstacles considerably increase calculation time and don't always produce good results.
  • Move Points out of Obstacles
    Moves points that are inside an obstacles back out.
  • Expand/Contract
    This is similar to Softimage|XSI's "push" operator: it allows you to shrink or expand an obstacle (by amount of cells).
  • In Geometry (closed Volume)
    Plug the geometry that is to be used as an obstacle in here.
    The geometry should be "relatively" closed (i.e. a normal cube is good, a cube with a missing polygon is okay and a grid is bad).
    Tip: if you want to use more than one object as obstacle you can combine their geometries using the "Group Geometry" node.
• Border Behavior
  • Falloff
    Defines the thickness, in Softimage Units, of a border surrounding the fluid box in which the influence of the fluid box will gradually become smaller and smaller.
  • Avoidance Strength
    The nearer a particle gets to the outer limit of the fluid box, the more it will want to get away from the border. This helps prevent particles from leaving the fluid box when they have to much velocity.
  • Avoidance Thickness
    The thickness, in Softimage Units, of the border surrounding the fluid box in which the border avoidance will gradually become bigger and bigger.
  • Close Top/Bottom/Left/Right/Front/Back
    Per default all borders of the fluid box are closed. With these parameters you can open one or more borders, thus allowing particles to escape the fluid box.
    In order for this option to work properly you should connect a "Get Particle Velocity" node to the input port "In Point Velocities".
• Data from Emitter
  • In Data 1 / 2
    The compound "emFluid3 Emit Pass Through" must be plugged into these two ports.

The output ports

Introduction for humans (normal users):

The main compound has a whole bunch of output ports, but you can ignore most of them when using emFluid3.
Typical setups will in fact only use 3-4 of them:
- the two execute ports
- the "Burn Positions" port
- the "Heat" port.
For example the setup contained in the "explode me" compound uses exactly those four ports.

Introduction for humanoids (TDs, Geeks, Nerds):

The main compound has a whole bunch of output ports and most of them are not required when using emFluid3 in a "normal" way. There may be cases however when you might want to go beyond the usual set of features and this version of emFluid3 will allow you to do so. The many output ports give you access to all the internal 3D grids (as flat arrays) of the fluid solver, therefore permitting you to eventually create a new plug-in by using emFluid3 as its core.
As a concrete example you might take a look into the main compound: once you are in the compound all the stuff in the lower-right takes care of the "Debug" mode. Latter is a 100% ICE (no hard coded stuff) and a good example of what you can do with the "Grid (Array)" output ports.

The output ports in detail:

• The first two "execute" ports
  • Set Particle Velocity
    This execute port does exactly what it names suggests: it sets the particle velocity.
    Plug this port into an execute port of your ICE Tree.
    Note: Instead of using this execute port you can also use ICE's "Set Particle Velocity" node in which you then simply plug the "Velocity" port of the main emFluid3 compound.
  • Visualize Grid Cells
    This execute port must be connected if you want to use the "debug" mode.
    Plug this port into an execute port of your ICE Tree.
• The following five ports (Fuel, Heat, Oxygen, Density, Velocity)
  • Fuel, Heat, Oxygen and Density
    These four ports can be used to get the value of a certain data type (i.e. fuel, heat, etc.) for each particle depending on the particle's position in the fluid box.
    For example you could use the "Heat" port to drive a color gradient (this is done in most of the demo scenes, as well as in the setup contained in the "explode me" compound).
  • Velocity
    This port does exactly the same thing as the above ports, but for velocity.
    When the port "Set Particle Velocity" is connected (as in the picture below) then you don't need this port.
    
    But instead of using the execute port you can do the same thing using ICE's "Set Particle Velocity" node, as shown in the next picture:
    
    Using the above method you could for example perform some modifications to the velocity before passing it to the "Set Particle Velocity" node:
    
    A further important usage of this port is when it comes to use more than one emFluid3 main compound in the same ICE Tree. emFluid3 is very "dominant" and radically overwrites the particle velocity, so when using more than one emFluid3 setup you must daisy-chain them as illustrated here:
    
    Here's what happens with the velocity in the above picture:
    The current particle velocity is passed to the first emFluid3 compound which will calculate new velocities for all particles contained in the first fluid box (if a particle is not contained in the first fluid box its velocity remains unchanged). The new velocity is then passed from the first to the second emFluid3 compound that will do exactly the same thing as the first compound but use the second fluid box to determine which velocities need to be set.
• The "Burn Positions (Array)" port

  Whenever you are using combustion (= burning fuel with oxygen) this port outputs an array of so-called "burn positions" that you can use with the "emFluid3 _ Particle Emitter" compound.
  So what exactly are "burn positions"? At each frame some of the fuel contained in the fluid box is burned. The positions where fuel is burned are stored in an array of 3D vectors that you can use by connecting this port to whatever you like, typically the "emFluid3 _ Particle Emitter" compound.

  Use the parameter "Amount per cubic SI Unit of Fuel" of the compound emFluid3 __ Behavior to control the amount of positions that are generated.

• The "Grid (Array)" ports (advanced users)

  These ports give you access to the solver's internal data grids which are stored as flat arrays.

  

  Use the values from the ports "Cells in X/Y/Z" to calculate your indices when "peeking and poking" in the arrays:

  Let's say that

  Nx = Cells in X
  Ny = Cells in Y
  Nz = Cells in Z

  then the index of the cell (i,j,k) in the array is calculated as

  index = i + j*Nx + k*Nx*Ny

The Compound "emFluid3 _ Particle Emitter"

This compound can be used to emit particles from the so-called "burn positions".

Aside from the input port called "Burn Positions" this compound is mainly the same as the other particle emitter compounds of ICE as for example "Emit from Surface": You can define the initial values of the particles (size, mass, color, etc.) and perform executions on emission, for example set the particle's age limit.

The input port "Burn Positions":

This input expects an array of positions (as 3D Vectors). This array is automatically generated by emFluid3's main compound whenever fluid is burned. Exactly one particle is emitted per burn position, so in order to control the total amount of particles you need to control the amount of burn positions. This can be done in the compound emFluid3 __ Behavior via the parameter "Amount per cubic SI Unit of Fuel".

The Compound "emFluid3 __ Behavior"

The parameters in this compound let you control the data's so-called "behavior".

This compound is a simplified and more user-friendly version of the compound "emFluid3 __ Behavior Advanced":
only the commonly used parameters are exposed, but you can enter the "Behavior" compound at any time to access the "Behavior Advanced" compound and its parameters.

The input ports:

• Combustion of Fuel (with Oxygen)
  • Enable Combustion
    Enables/disables combustion. If enabled then fuel and oxygen are burned, thus creating heat.
  • Burn Rate
    The overall burn rate. A value of zero disables combustion.
  • Ignition Temperature
    The temperature at which fuel starts burning. Lower values make the fuel easier to ignite.
  • Heat of Combustion
    The amount of heat (=temperature) that results from combustion.
  • Cooling
    The amount of cooling. The higher this value, the faster heat cools down to the ambient temperature of approx. 23 degrees Celsius.
• Generate Velocity from Heat
  • Enable
    Enable/disable the generation of velocity from heat.
  • Expansion
    The expansion strength of the heat. When heat expands it produces velocity. Use high values for things like explosions.
  • Buoyancy
    The buoyancy strength of the heat. Heat rises and produces velocity while it rises.
  • Randomness
    Adds randomness to the velocity generation.
• Generate Emission Positions
  • Amount per cubic SI unit of Fuel
    At each frame a certain amount of fuel is burned together with oxygen.
    This parameter defines how many particles are represented by one cubic unit of fuel. This has influence on the amount of "burn positions" that are outputted by the main compound (for more information go to "emFluid3 _ Particle Emitter").
    In simple words: use higher values to generate more positions and therefore more particles.

The output port "Behavior":

This port must be connected to the input port "In Behavior" of the main compound.

The Compound "emFluid3 __ Behavior Advanced"

This compound has all parameters concerning the behavior of data and is contained in the "emFluid3 __ Behavior" compound.
The normal usage is to connect the "emFluid3 __ Behavior" compound but you can also connect this compound if you wish.

The input ports:

• Combustion of Fuel (with Oxygen)
  • Enable Combustion
    Enables/disables combustion. If enabled then fuel and oxygen are burned, thus creating heat.
  • Burn Rate
    The overall burn rate.
  • Ignition Temperature
    The temperature at which fuel starts burning. Lower values make the fuel easier to ignite.
  • Heat of Combustion
    The amount of heat (=temperature) that results from combustion.
  • Generate Emission Positions for Particles
    • Amount per cubic SI unit of Fuel
      At each frame a certain amount of fuel is burned together with oxygen.
      This parameter defines how many particles are represented by one cubic unit of fuel. This has influence on the amount of "burn positions" that are outputted by the main compound (for more information go to "emFluid3 _ Particle Emitter").
      In simple words: use higher values to generate more positions and therefore more particles.
• Data Behavior of FUEL / HEAT / OXYGEN / DENSITY
  (set of parameters common to each type)
  • Diffusion-Rate
    The strength of the diffusion rate.
    Diffusion means that data will spread in the fluid box over time. The higher this value the faster the data spreads. A value of zero disables diffusion.
  • Follow-Velocity
    This parameter defines how strong data will move along the velocity contained in the fluid box.
    For a value equal zero the data is unaffected by velocity (i.e. fuel typically doesn't follow velocity).
    This is an important parameter to create self-evolving processes, the best example being heat: heat generates velocity and at the same time follows that velocity.
  • Damping-Rate
    The damping rate of the data (you can also think of this parameter as a sort of viscosity). The data "returns" to a certain value (see next parameter) over time.
    For example heat will cool down until it reaches the ambient temperature (=it converges to the ambient temperature)
  • Damping-Target-Value
    The target value when using a damping rate greater than zero.
    Example (heat): let's say this parameter is set to 20. Any heat greater (or smaller) than 20 will converge towards 20 over time.
• Data Behavior of HEAT
  (Generate Velocity from Heat)
  • Enable
    Enables/disables the generation of velocity from heat.
    If enabled then velocity is automatically added to the fluid box wherever there are regional heat differences.
  • Expansion
    Contrary to the buoyancy (see next parameter) that generates velocity in a fixed direction the expansion generates velocity in all directions.
  • Buoyancy
    Defines how much "upward force" is created by heat. The higher this value the more velocity is created.
  • Use inverse Gravity Vector as Buoyancy Direction
    Per default the direction of the buoyancy is equal the inverted gravity direction (the gravity direction is defined in the main compound "emFluid3 _ Main").
    By unchecking this parameter you can use a custom vector for the buoyancy direction (see next parameter).
  • Custom Buoyancy Direction
    The 3D vector that defines the custom buoyancy direction. This is only used if the previous parameter is enabled.
• Data Behavior of DENSITY
  (Generate Velocity from Heat)
  Density has the identical set of parameters as heat and is controlled in the same way, so please check the parameter description of the heat parameters for more information.
  The only difference is the "Use Gravity Vector as Buoyancy Direction". Per default higher density tends to "fall" contrary to heat (heat tends to "rise").

The output port "Behavior":

This port must be connected to the input port "In Behavior" of the main compound.

The Compound "emFluid3 __ Debug"

This interesting compound is in fact a by-product of the development of emFluid3. During development it was important to be able to "see" what the fluid solver is doing, making it easier to find bugs and other annoying stuff. But even now that emFluid3 is (hopefully!) working correctly this compound can come quite handy when dealing with problems concerning the fluid setup.

Important: please be sure that the particle display is set to "automatic" when using this compound!
The content of the grid cells is visualized by particles that have a certain size, color, shape and orientation. Having a particle display of for example "points" would override those properties and corrupt the visualization.

The Compound "emFluid3 __ Emit Pass Through"

This is a special compound that will combine all the data emitters and pass them to the main node.
Both output ports must be connected to the main compound and the compound "emFluid3 ___ Emit Settings" must be connected to the input port "In Settings" (see above picture).

You can plug as many data emitter compounds ("emFluid3 ___ Emit Data from SRT" and "emFluid3 ___ Emit Data from Points") as you wish into this compound.

The Compound "emFluid3 __ Emit Settings"

This compound contains global settings for all data emitters and must be plugged into the "emFluid3 ___ Emit Pass Through" compound.
The available parameters till now are only two global switches to turn on/off all emission from SRT and/or points. More parameters will be available in future releases.

The Compound "emFluid3 __ Emit Data from SRT"

This compound will allow you to add "data" to the fluid box, for example you could add some fuel that will automatically start burning and produce heat and velocity, or you might directly add some velocity to the fluid box.
The data is emitted from the SRT (Scaling/Rotation/Translation) of an object or - in other words - data is emitted at the center of an object. This is a little like painting something in Photoshop using a brush: you choose a type of data (a "color") and "paint" it into the fluid box. Just as in Photoshop you can define a size for the data emitter (= the "brush").

1) "Emitter Settings"

Here you define the position and size of the data emitter. The position is taken directly from the object that is plugged into the "In Name (Position)" port. Some data types as for example velocity will also take the object's rotation.
The data emitter's size is defined by the parameter "Size" (radius). Surplus you can control the emitter's size by checking the parameter "Multiply Size by global Z-Scale", so that the emitter's final size is Size * object's Z-Scale. This way you can control the emitter's size by simply scaling your object in z.

2) "Switches"

These parameters turn on/off the emission of data types.

3) "Rates"

These parameters define the rates at which the different data types are emitted.

• Fuel
  The fuel emission rate (=the amount of fuel to emit in one second).
• Auto Ignition for freshly emitted Fuel
  If checked then fuel that has just been emitted is automatically ignited. In combination with "Single-Frame Fuel" (see next parameter) this lets you easily burn moving objects.
• Single-Frame Fuel
  This emits so-called "single-frame" fuel, meaning that the emitted fuel is only kept for one frame.
  Enable this option when burning moving objects, for example a torch or a rocket.
• Heat
  The heat emission rate (=the amount of heat to emit in one second).
  Emitting heat can be used to ignite fuel.
• Oxygen
  The oxygen emission rate (=the amount of oxygen to emit in one second).
  The settings in the "emFluid3 __ Behavior Advanced" compound concerning oxygen are set in a way that there is always 0.21 oxygen contained in each cell. By emitting additional oxygen you can make an already burning fuel burn even more.
• Density
  The density emission rate (=the amount of density to emit in one second).
• Velocity
  The velocity emission rate (=the amount of velocity to emit in one second).
  Note: in emFluid2 this was called "velocity force".
• Direction of Velocity
  The direction for the emitted velocity. Possible values are either one of the emitter's local axes or a custom vector (see next parameter).
• Custom Direction Vector
  If the previous parameter is set to "Use Custom Direction Vector" then this 3D vector defines the velocity's direction.

The Compound "emFluid3 __ Emit Data from Points"

Use this compound to emit data from the points of geometry. Any type of geometry can be plugged in here as long as it has some points. Polygon meshes, surface meshes, curves and even other point clouds can be used.
You can plug as many of these compounds into the "emFluid3 ___ Emit Pass Through" compound as you wish.

What this compound does is in fact quite simple: for each point it will simple create a little data emitter (=> theoretically you could emulate this compound by placing an "Emit Data from SRT" at each point of the input geometry).

The compound's parameters are more or less identical to the parameters of the compound "emFluid3 ___ Emit Data from SRT", except for:

1) "Use every Nth Point"

Most often you will want every point to emit data (by setting this parameter to 1), but in some cases it can be better to emit data only from let's say every 10th point of the input geometry. For example you might have a heavy mesh with thousands of points you want to emit data from. In this case using only every let's say 50th point will improve performance whereas the result will nearly be the same.
Note: heavy meshes slow down the whole ICE Tree, because large arrays are built and passed to the emFLuid3 node. To get a better overall performance you might consider using a simplified mesh (i.e. a clone with a "polygon reduction" operator) instead of the original heavy mesh.

2) "Multiply size by Point Size"

If this parameter is checked and your input geometry is a point cloud then the parameter "size" will be multiplied by the size of the points (particles).

3) The parameters concerning the "Velocity" data

Below the parameter "Velocity" are several parameters that define how the velocity data's strength and direction shall be generated for each point. You could for example use the point's velocity vector to define the direction of the velocity data or add some randomness to it.

• New in Version 3.01:

  emFluid3 is not only a simple update of emFluid2, it is in fact a whole new program with many new features and an improvement work flow.

Things you should avoid when working with emFluid3:

• Changing the (global) scaling of the Fluid Box over time

  You cannot scale the fluid box during the simulation: The fluid solver works within a container. The size (=the scale) of the container (=fluid box) defines the number of cells for the fluid solver. So, whenever the global size of the container changes the velocity field is reset.

• Modifying the global SRT of the point cloud

  The point cloud should always lay in the world's origin. If this is not the case then particles will probably not behave as expected.

Known issues:

• Concerning XSI 7.01 and 7.5

  Even though this plug-in works well with these XSI versions, unfortunately there are some known issues:
  • there is a memory leak when using obstacles, especially if the parameter "Static Obstacles" is unchecked.
  • there is a memory leak when using the "Debug" mode.
  Please note that these issues do NOT occur with SI 2010 SP1 and above.

Special thanks go to my friend and colleague Oliver Weingarten, who was a great support in creating this plug-in.