Fluid Simulation - Developer Documentation

Integration into the Blender code

The main interface to the fluid solver is in the file source/blender/src/fluidsim.c. In a first version the simulation will only support meshes. As the code needs to modify the meshes, it is added as a DerivedMesh. Depending on the setting, the objects are either displayed as

original mesh - for setting up the simulation
preview surface - for quick preview of the fluid animation in the GUI
final surface - for rendering the simulated fluid surface.

A fluidsimDerivedMesh interface is implemented, to handle displaying the correct mesh (hence it makes use of the [BlenderDev/MeshDerivedMesh|MeshDerivedMesh] implementation). For standard objects a =fluidsimFlag= is added that indicates whether the object stores additional settings for the fluid simulation. If yes, these will be stored in a fluidsimSettings struct defined in =DNA_object_fluidsim.h=. The object thus also needs a pointer to the settings struct. Currently all objects participating in the fluid simulation store the same data, this could however be reduced, as objects representing fluid or obstacles require fewer information than a domain object. The solver itself is added as an internal library in the intern/elbeem/intern directory. El'Beem is the admittedly stupid name of the solver, and is derived from LBM :) .
http://www10.informatik.uni-erlangen.de/~sinithue/img/fssc_imploverview.jpg

Dependencies

The code relies on the [BlenderDev/DerivedMesh|DerivedMesh] interface, which is currently being developed. For im- and export of the fluid surface meshes, a binary object file format is used (.bobj), that basically represents a binary version of the wavefront object file format, that can be zipped (.bobj.gz) to require less disk space. It currently stores all vertices, their normals and all triangles with single precision flaoting point values for a single mesh. Manual reading and writing of these files is currently done with python scripts. Overall, the fluid simulation requires additional data to be stored for participating objects, which have a modified display mechanism based on the [BlenderDev/DerivedMesh|DerivedMeshes]. The main work of the fluid simulation will is done by the solver in intern/elbeem/intern.

There used to be a standalone version of the Blender fluid solver on elbeem.sourceforge.net. It is, however, currently not updated. So it is advisable to use the Blender version of the solver and its API if it should be used in another program.

Challenges & Fixes

Time - the fluid simulation can take minutes to hours, so unlike e.g. a physics rigid body simulation with ODE, the fluid simulation is not suitable for realtime (unless very small grids are used). Thus, it may be useful to use multiple cores in the future.
Memory for the Simulation - the LBM simulations can require huge amounts of memory. Thus the maximum resolution for the simulation is usually limited be the main memory of the computer.
Memory for the Animation - for typical problem sizes and longer animations the fluid surface meshes can require lots of memory as well. It is not feasible to keep the whole animation of the final fluid surface in memory, hence it is stored on the hard disk with the bobj-format described above. For preview a low resolution surface mesh is generated, that can be loaded quickly.

The Fluid-Control Branch

In order to create effects like these Magic Fluid Control, control forces are necessary. This is a part of the solver that was implemented, but so far not properly integrated into Blender. The goal of this branch is to finally include it. The following section gives a short overview of the changes of this branch, and how to get started with the integration.

The new files handling control are:

solver_control.cpp/h - main functions for control, solver related
elbeem_control.cpp/h - external interface to control functions, not yet implemented...
controlparticles.cpp/h - control particle handling
mvmcoords.cpp/h - mean value mesh coordinates (control particle creation from animated meshes)

The general idea for controlling the fluid is: there is a set of particles with a given size that add attraction and velocity forces to the fluid. Attraction pulls the fluid within the influence radius of the particle toward it, while the velocity force makes the fluid follow the movement of the particle. When compiling, make sure LBM_INCLUDE_CONTROL is defined, otherwise the control functions won't be available.

The code is organized as follows: - the class LbmControlData is mainly a storage class, it handles the different sets of control particels - the class LbmControlSet stores a set of control particles, and their influence parameters (strength of control, influence radii etc.). This makes it somewhat easier to animate individual sets, e.g., turn them on/off etc. - the class ControlParticles stores the actual particles at different times (for each time there's a list of particles also called set in the code). The particles can again be offset, scaled and have their own timestep. - finally, the class ControlParticle stores a single particle. The input values are most importantly its position, but each particle also has a size parameter to modify the force radii and an individual influence parameter - both can probably be left at 1 most of the time. The velocity of the particle is computed from its motion!

Currently, the ControlParticles class has various loading methods (from text-file, binary, mesh), but for Blender, a function should be added the gets the positions e.g. from a particle object. The ideal way would probably be to create a new fluid object type, and then channel the animated positions of the vertices or the particle position through the elbeem_control interface into the ControlParticle classes.

The current version initializes a fixed test with a single large control particle that moves diagonally through the domain with strong attraction and velocity forces. It can be found in solver_control.cpp, LbmFsgrSolver::initCpdata() (the first if(1){ ... } block). This code calls the function initBlenderTest() in controlparticles.cpp to add two sets of controlparticles (with a single particle at two positions). The corresponding example .blend file can be found here (this is how it should look). One importatn thing to note is that elbeem has something like IPOs called "channels", which contain animated values. So for the control particles, don't try to directly set values, e.g., by calling setRadiusAtt(1.5);, but initialize the corresponding channel mcForceAtt with a constant value 1.5 (as it is done in the source code example).

So for a start, I'd suggest to add the following parameters:

Attraction force strength
Attraction force radius
Velocity force strength
Velocity force radius

Then extract the positions of the objects vertices (or its particles) over time, and pass them to the solver. This could probably be done similar to the way deforming objects are handled during the export right now. On the solver side, it should be enough to set the parameters (as in the example above), and init the control particle positions...

Todolist / Open Problems

The fluid simulator is currently not capable of simulating interaction with rigid bodies, or, e.g., the cloth simulations.
Motion blur is handled by storing the per vertex velocities for the image based motion blur computations.
Currently the fluid simulator only handles free surface fluids, but with relatively small changes, effects such as smoke or blowing leaves could also be simulated. Unforunately, volumetric effects currently can't be rendered in Blender.

References

A single-phase free-surface Lattice-Boltzmann Method, Erlangen/Germany, master-thesis (Pdf-Document)
Interactive Free Surface Fluids with the Lattice Boltzmann Method , (N. Thuerey, C. Koerner, U. Ruede), Technical Report 05-4 (Pdf-Document)
Optimized Free Surface Fluids on Adaptive Grids with the Lattice Boltzmann Method, (N. Thuerey, U. Ruede), SIGGRAPH 2005 Poster (Pdf-Document)
Web page with more papers & animations: http://www.ntoken.com/p_fluid.html

Back to the Fluid Simulation Chapter

利用者:N t/SummerOfCode2005/Fluid Animation/Development