Skip to content

Commit 779e9c9

Browse files
nkoenignkoenig
committed
Merged in ahaidu/gazebo_tutorials_gz_fluid (pull request #63)
Fluids tutorial
2 parents 752cf0b + 84098ce commit 779e9c9

File tree

2 files changed

+128
-0
lines changed

2 files changed

+128
-0
lines changed

‎fluids/tutorial.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Introduction
2+
3+
The package allows the simulation of fluids in Gazebo. The fluid particle interactions are computed on the GPU
4+
using the [Fluidix](http://onezero.ca/documentation/) library (if a nvidia GPU is not available the simulation will run in CPU mode).
5+
6+
**Prerequisites:**
7+
8+
* Get the package from [bitbucket](https://bitbucket.org/ahaidu/gz_fluid).
9+
* Install [CUDA](https://developer.nvidia.com/cuda-downloads) (recommended 6.0).
10+
* Install [Fluidix](http://onezero.ca/documentation/).
11+
* Go through the basic Gazebo tutorials, especially through [world plugins](http://gazebosim.org/tutorials?tut=plugins_world), [system plugins](http://gazebosim.org/tutorials?tut=system_plugin), [transport library](http://gazebosim.org/tutorials?cat=transport) examples.
12+
* For deeper understanding of the particle simulation look through some [Fluidix examples](http://onezero.ca/sample/?id=general_basic).
13+
14+
# How the package works
15+
16+
The fluid simulation runs as a separate physics engine which interacts with the rigid body physics engine of Gazebo through an interface (`include/FluidEngine.hh`).
17+
18+
The interaction includes:
19+
* collision detection
20+
* forces / torques application on the rigid objects
21+
* visualization of the particles
22+
23+
The core of the fluid simulation is written in the `src/FluidEngine.cu` cuda file and it is built upon the [basic SPH example](http://onezero.ca/sample/?id=general_sph).
24+
25+
The package contains two plugins, one world plugin for updating the fluid and its interactions (`FluidWorldPlugin.cc`). And one GUI system plugin for visualizing the fluid particles(`FluidVisPlugin.cc`).
26+
27+
## Build instructions
28+
29+
In a terminal go to the downloaded `gz_fluid` folder and run the following commands:
30+
31+
~~~
32+
mkdir build
33+
cd build
34+
cmake ..
35+
make
36+
~~~
37+
38+
## Running the plugin:
39+
40+
* Set the gazebo plugin and model paths
41+
~~~
42+
echo "export GAZEBO_PLUGIN_PATH=<install_path>/gz_fluid/build:${GAZEBO_PLUGIN_PATH}" >> ~/.bashrc
43+
echo "export GAZEBO_MODEL_PATH=<path>/gz_fluid/models:${GAZEBO_MODEL_PATH}" >> ~/.bashrc
44+
source ~/.bashrc
45+
~~~
46+
* Add the plugin to your custom world file, or use one of the examples from the package
47+
~~~
48+
<?xml version="1.0"?>
49+
<sdf version="1.5">
50+
<world name="fluid_world">
51+
...
52+
<plugin name="FluidWorldPlugin" filename="libFluidWorldPlugin.so">
53+
<world_position>0 0 5.01</world_position>
54+
<world_size>1.5 1 10</world_size>
55+
<fluid_position>-0.5 0.0 0.8</fluid_position>
56+
<fluid_volume>0.4 0.95 0.5</fluid_volume>
57+
<particle_nr>0</particle_nr>
58+
</plugin>
59+
60+
</world>
61+
</sdf>
62+
~~~
63+
Where:
64+
* `<world_position>` and `<world_size>` set the fluid world center position and its size
65+
* `<fluid_position>` and `<fluid_volume>` set the center position of the fluid and its volume to be filled with particles
66+
* `<particle_nr>` if set to `0`, the given volume will be filled with fluid particles, otherwise the given particle number will be spawned.
67+
68+
69+
* Run gazebo server with the world plugin:
70+
~~~
71+
gzserver worlds/fluid.world
72+
~~~
73+
* Run gazebo client with the system plugin:
74+
~~~
75+
gzclient -g build/libFluidVisPlugin.so
76+
~~~
77+
78+
79+
# To know:
80+
81+
### Collisions meshes
82+
83+
In order for the fluid simulation to detect collisions gazebo needs to use `.stl` files for collision meshes.
84+
85+
86+
### Possible issues:
87+
88+
In CMakeLists.txt, the cuda compiler might need graphics card specific flags:
89+
90+
`SET(CUDA_NVCC_FLAGS "-arch;sm_30 -use_fast_math -lm -ldl -lrt -Xcompiler \"-fPIC\"")`
91+
92+
### Fluidix CMake include path
93+
94+
For a default install the fluidix headers are located in `/opt/fluidix/include`, if the paths differ make sure to change them accordingly in the `src/CMakeLists.txt` file.
95+
96+
### Some code explanation:
97+
98+
* The world plugin `FluidWorldPlugin.cc`:
99+
* in the constructor the fluid engine is initialized
100+
* in `FluidWorldPlugin::Load` the sdf parameters are loaded, the fluid world is created, fluid is added, the objects from the environment are recreated in the fluid environment (when possible)
101+
* in `FluidWorldPlugin::Init` the publishers of the objects and fluids particles positions are initialized
102+
* `FluidWorldPlugin::OnUpdate` is called every world update event, there the fluid engine is updated one timestamp, a msg is sent for the rendering plugin with all the new particles position, and computed forces and torques are applied on the rigid objects.
103+
104+
* The system plugin `FluidVisPlugin.cc`, used for rendering the fluid:
105+
* in `FluidVisPlugin::Load` the arguments (if given) are loaded for the type of rendering, `sphere` or default `point`. When sphere is selected the rendering gets slower if many particles are loaded.
106+
* in `FluidVisPlugin::Init` the subscribes for the fluid particle positions are loaded.
107+
* in `FluidVisPlugin::RenderAsPointsUpdate` or `FluidVisPlugin::RenderAsSpheresUpdate`, (depending on the rendering type) if a new message with the particle positions is available, these will be rendered.
108+
109+
* The fluid simulation engine `FluidEngine.cu` is similar to the SPH example from Fluidix.
110+
111+
112+
113+
# Unfinished parts, TODOs:
114+
If somebody is interested in further contributing to the package, many features still need work:
115+
116+
* Implementing a newer SPH: [PCISPH](https://sph-sjtu-f06.googlecode.com/files/a40-solenthaler.pdf) or [IISPH](http://cg.informatik.uni-freiburg.de/publications/2013_TVCG_IISPH.pdf) for faster simulation and no compression of the fluid. This can be done in the `src/FluidEngine.cu` file by changing the algorithm.
117+
118+
* Currently the simulation only has the box implemented as a standard shape, see `FluidEngine::AddMovableBox` from `src/FluidEngine.cu`, it is implemented similarly to this [example](http://onezero.ca/sample/?id=init_manual). Using the same idea the rest of the collision types can be implemented as well: cylinder, sphere, plane. After implementation these need to be added in the `FluidWorldPlugin::CreateFluidCollision` method, similarly to the `box` type.
119+
120+
* The force and torque interaction is done via the particles surface collisions, pressure force from the liquid is not taken into account. A fancier algorithm would greatly increase realism.

‎manifest.xml

+8
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,13 @@
138138
<skill>beginner</skill>
139139
</tutorial>
140140

141+
<tutorial title="Fluids" ref='fluids'>
142+
<markdown version="3.0+">fluids/tutorial.md</markdown>
143+
<description>Fluid simulation on the GPU using Fluidix library.</description>
144+
<skill>advanced</skill>
145+
</tutorial>
146+
147+
141148
<tutorial title="Log filtering" ref='log_filtering'>
142149
<markdown version="1.9">log_filtering/tutorial.md</markdown>
143150
<markdown version="4.0+">log_filtering/tutorial_4-0.md</markdown>
@@ -457,6 +464,7 @@
457464
<description>A core component of Gazebo are the physics engines. These tutorials describe how to use the physics engines in order to acheive desired behavior.</description>
458465
<tutorials>
459466
<tutorial>friction</tutorial>
467+
<tutorial>fluids</tutorial>
460468
</tutorials>
461469
</category>
462470

0 commit comments

Comments
 (0)