Skip to content

Commit 924e13f

Browse files
andreihaiduandreihaidu
committed
fluids tutorial added
1 parent b6d782e commit 924e13f

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎fluids/tutorial.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Gazebo Fluid Simulation Plugin using the Fluidix library #
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+
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`). The interaction includes collision detection and the application of forces and torques from the fluid on the rigid objects.
7+
8+
The core of the fluid simulation is written in the `src/FluidEngine.cu` cuda file, it is built upon the [basic SPH example](http://onezero.ca/sample/?id=general_sph).
9+
10+
The package contains two plugins, one world plugin for updating the fluid and its interactions (`FluidWorldPlugin.cc`). And one client based system plugin for visualizing the fluid particles(`FluidVisPlugin.cc`).
11+
12+
### Installation requirements:
13+
14+
* Install [Gazebo](http://gazebosim.org/)
15+
* Install [CUDA](https://developer.nvidia.com/cuda-downloads) (recommended 6.0)
16+
* Install [Fluidix](http://onezero.ca/documentation/)
17+
18+
### Buid instructions:
19+
20+
* $ mkdir build
21+
* $ cd build
22+
* $ cmake ..
23+
* $ make
24+
25+
26+
### Running the plugin:
27+
28+
* set the gazebo plugin paths
29+
* add the plugin to your world file (e.g worlds/fluid.world), or use one of the world examples from the package
30+
* run gazebo server with the world plugin $ gzserver worlds/fluid.world
31+
* run gazebo client with the system plugin $ gzclient -g build/libFluidVisPlugin.so
32+
33+
34+
### Changing simulation:
35+
36+
* change fluid plugin parameters from the sdf tags:
37+
* `<world_position>` and `<world_size>` set the fluid worlds center position and its size
38+
* `<fluid_position>` and `<fluid_volume>` set the center position of the fluid and its volume to be filled with particles
39+
* `<particle_nr>` if set to `0`, the given volume will be filled with fluid particles, otherwise the given particle number will be spawned.
40+
41+
* by changing the source code from FluidWorldPlugin.cc
42+
43+
44+
45+
46+
### TODOs:
47+
48+
* 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.
49+
50+
* 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.
51+
52+
* the force and torque interaction is done via the particle collisions, pressure force from the liquid is not taken into account.
53+
54+
### To know:
55+
56+
* in order for the fluid simulation to detect collisions gazebo needs to use `.stl` files for collision.
57+
58+
59+
### Possible issues:
60+
61+
* in CMakeLists.txt, the cuda compiler might need graphics card specific flags:
62+
63+
`SET(CUDA_NVCC_FLAGS "-arch;sm_30 -use_fast_math -lm -ldl -lrt -Xcompiler \"-fPIC\"")`
64+
65+
### Some code explanation:
66+
67+
* The world plugin `FluidWorldPlugin.cc`:
68+
* in the constructor the fluid engine is initialized
69+
* 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)
70+
* in `FluidWorldPlugin::Init` the publishers of the objects and fluids particles positions are initialized
71+
* `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.
72+
73+
* The system plugin `FluidVisPlugin.cc`, used for rendering the fluid:
74+
* 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.
75+
* in `FluidVisPlugin::Init` the subscribes for the fluid particle positions are loaded.
76+
* 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.
77+
78+
* The fluid simulation engine `FluidEngine.cc`:
79+
80+
81+
82+
83+
84+
85+
86+
87+
88+
89+
90+
91+
92+
# Overview
93+
94+
**Prerequisites:** [Attach a Mesh as Visual](http://gazebosim.org/tutorials/?tut=attach_meshes)
95+
96+
This tutorials demonstrates how the user can create composite models directly from other models in the [Gazebo Model Database](http://gazebosim.org/user_guide/started__models__database.html) by using the `<include>` tags and [`<joint>`](http://gazebosim.org/sdf/1.4.html#joint309) to connect different components of a composite model.
97+
98+
## Adding a Laser
99+
100+
Adding a laser to a robot, or any model, is simply a matter of including the sensor in the model.
101+
102+
1. Go into your model directory from the previous tutorial:
103+
104+
cd ~/.gazebo/models/my_robot
105+
106+
1. Open `model.sdf` in your favorite editor.
107+
108+
1. Add the following lines directly before the `</model>` tag near the end of the file.
109+
110+
~~~
111+
<include>
112+
<uri>model://hokuyo</uri>
113+
<pose>0.2 0 0.2 0 0 0</pose>
114+
</include>
115+
<joint name="hokuyo_joint" type="revolute">
116+
<child>hokuyo::link</child>
117+
<parent>chassis</parent>
118+
<axis>
119+
<xyz>0 0 1</xyz>
120+
<limit>
121+
<upper>0</upper>
122+
<lower>0</lower>
123+
</limit>
124+
</axis>
125+
</joint>
126+
~~~
127+
128+
The `<include>` block tells Gazebo to find a model, and insert it at a given `<pose>` relative to the parent model. In this case we place the hokuyo laser forward and above the robot. The `<uri>` block tells gazebo where to find the model inside its model database (note, you can see a listing of the model database uri used by these tutorials at [here](http://gazebosim.org/models/), and the corresponding [mercurial repository](https://bitbucket.org/osrf/gazebo_models).
129+
130+
The new `<joint>` connects the inserted hokuyo laser onto the chassis of the robot. The joint has and `<upper>` and `<lower>` limit of zero to prevent it from moving.
131+
132+
The `<child>` name in the joint is derived from the [hokuyo model's SDF](https://bitbucket.org/osrf/gazebo_models/src/6cd587c0a30e/hokuyo/model.sdf?at=default), which begins with:
133+
134+
~~~
135+
<?xml version="1.0" ?>
136+
<sdf version="1.4">
137+
<model name="hokuyo">
138+
<link name="link">
139+
~~~
140+
141+
When the hokuyo model is inserted, the hokuyo's links are namespaced with their model name. In this case the model name is `hokuyo`, so each link in the hokuyo model is prefaced with `hokuyo::`.
142+
143+
1. Now start gazebo, and add the robot to the simulation using the Insert tab on the GUI. You should see the robot with a laser attached.
144+
145+
[[file:files/Add_laser_pioneer.png|640px]]
146+
147+
1. (Optional) Try adding a camera to the robot. The camera's model URI is `model://camera`, it should have been locally caches for you in:
148+
149+
ls ~/.gazebo/models/camera/
150+
151+
152+
For reference, the SDF documentation can be found [here](http://gazebosim.org/sdf/).
153+
154+
## Next
155+
156+
[Next: Make a Simple Gripper](http://gazebosim.org/tutorials/?tut=simple_gripper)

‎manifest.xml

Lines changed: 8 additions & 0 deletions
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>
@@ -420,6 +427,7 @@
420427
<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>
421428
<tutorials>
422429
<tutorial>friction</tutorial>
430+
<tutorial>fluids</tutorial>
423431
</tutorials>
424432
</category>
425433

0 commit comments

Comments
 (0)