Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Particle Emitter tutorial #860

Merged
merged 5 commits into from
Jun 16, 2021
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions tutorials.md.in
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
* \subpage triggeredpublisher "Triggered Publisher": Using the TriggeredPublisher system to orchestrate actions in simulation.
* \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation.
* \subpage videorecorder "Video Recorder": Record videos from the 3D render window.
* \subpage collada_world_exporter "Collada World Exporter": Export an entire
world to a single Collada mesh.
* \subpage collada_world_exporter "Collada World Exporter": Export an entire world to a single Collada mesh.
* \subpage particle_mitter "Particle emitter": Using particle emitters in simulation

**Migration from Gazebo classic**

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
116 changes: 116 additions & 0 deletions tutorials/particle_tutorial.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
\page particle_mitter Particle Emitter

This tutorial shows how to use the particle emitter system to add and configure particle effects like smoke and fog in simulation. It also shows the effects that particles have on different types of sensors in Ignition Gazebo.

## Particle Emitter System

We will demonstrate the particle emitter system by using the [examples/worlds/particle_emitter2.sdf](
https://github.com/ignitionrobotics/ign-gazebo/blob/ign-gazebo4/examples/worlds/particle_emitter2.sdf) world.

To be able to spawn particle emitters, first you will need to include the particle emitter system as a plugin to the world in your SDF. The system does not take any arguments.

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
<plugin
filename="ignition-gazebo-particle-emitter2-system"
name="ignition::gazebo::systems::ParticleEmitter2">
</plugin>
```

iche033 marked this conversation as resolved.
Show resolved Hide resolved

Next, we can start adding particle emitter models into the world. In our example world, we include a [Fog Generator](https://app.ignitionrobotics.org/OpenRobotics/fuel/models/Fog%20Generator) model from Ignition Fuel:

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
<include>
<uri>https://fuel.ignitionrobotics.org/1.0/openrobotics/models/fog generator</uri>
</include>
```

Here is the content of the Fog Generator [model.sdf](https://fuel.ignitionrobotics.org/1.0/OpenRobotics/models/Fog%20Generator/1/files/model.sdf) file.

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
<model name="fog_generator">
<pose>0 0 0 0 -1.5707 0</pose>
<static>true</static>
<link name="fog_link">
<particle_emitter name="emitter" type="box">
<emitting>true</emitting>
<size>10 10 0</size>
<particle_size>1 1 1</particle_size>
<lifetime>25</lifetime>
<min_velocity>0.1</min_velocity>
<max_velocity>0.2</max_velocity>
<scale_rate>0.5</scale_rate>
<rate>5</rate>
<material>
<diffuse>0.7 0.7 0.7</diffuse>
<specular>1.0 1.0 1.0</specular>
<pbr>
<metal>
<albedo_map>materials/textures/fog.png</albedo_map>
</metal>
</pbr>
</material>
<color_range_image>materials/textures/fogcolors.png</color_range_image>
</particle_emitter>
</link>
</model>
```

The SDF 1.6+ specification supports having a `<particle_emitter>` SDF element as a child of `<link>`. The particle emitter itself has several properties that can be configured, see Ignition Rendering's [particles tutorial](https://ignitionrobotics.org/api/rendering/4.0/particles.html) for more details on these properties. In our Fog Generator model, we are using a box type particle emitter that covers a region size of 10 by 10m. By default, the particles are emitted in the `+x` direction, hence the model as a pitch rotation of -90 degrees to rotate the particle emitter so that the particles are emitted upwards in `+z`.

iche033 marked this conversation as resolved.
Show resolved Hide resolved

Let's launch the example world to see what it looks like.

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
ign gazebo -v 4 -r particle_emitter2.sdf
```

You should see the fog slowly starting to appear from the ground plane in the world:

@image html files/particle_emitter/fog_generator.png

iche033 marked this conversation as resolved.
Show resolved Hide resolved

Next, try changing some properties of the particle emitter while the simulation is running. You can do this by publishing messages over Ignition Transport. Try turning off the particle emitter by setting the `emitting` property to `false`. Make sure the simulation is running in order for this command to take effect.

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
ign topic -t /model/fog_generator/link/fog_link/particle_emitter/emitter/cmd -m ignition.msgs.ParticleEmitter -p 'emitting: {data: false}'
```

Note the above command tells the particle emitter to stop emitting. It does not make all the particles disappear immediately. The particles that have already been emitted will naturally fade and disappear over the specified `lifetime`.

Turn particle emitter back on by setting the `emitting` property to `true`:

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
ign topic -t /model/fog_generator/link/fog_link/particle_emitter/emitter/cmd -m ignition.msgs.ParticleEmitter -p 'emitting: {data: true}'
```

Here is an example command for changing the `rate` property of the particle emitter. This should make the particle emitter emit more particles per second, causing it to visually appear more dense.

```
iche033 marked this conversation as resolved.
Show resolved Hide resolved
ign topic -t /model/fog_generator/link/fog_link/particle_emitter/emitter/cmd -m ignition.msgs.ParticleEmitter -p 'rate: {data: 100}'
```

## Particle Effects on Sensors

The particles are not only a visual effect in simulation, they also have an effect on sensors in simulation. Here are the sensor types and the effects the particle emitter have on them:

* `camera`: The particles are visible to a regular camera sensor
* `depth_camera`: The particles have a scattering effect on the depth data.
* `rgbd_camera`: The particles are visible in the RGB image and have a scattering effect on the depth data.
* `gpu_lidar`: The particles have a scattering effect on the lidar range readings.
* `thermal_camera`: The particles are not visible in the thermal camera image.

iche033 marked this conversation as resolved.
Show resolved Hide resolved

The gif below shows an [example world](https://gist.github.com/iche033/bcd3b7d3f4874e1e707e392d6dbb0aa0) with six different sensors looking at the fog generator with a rescue randy model inside the fog.

iche033 marked this conversation as resolved.
Show resolved Hide resolved

@image html files/particle_emitter/sensor_scatter_tutorial.gif

The two image displays on the left show the images from a regular camera sensor and RGB output of a RGBD camera. The two have very similar color image output that shows the fog in the camera view. To their right are the depth images produced by a depth camera and the depth output of the RGBD camera. The depth readings are noisy due to the particle scattering effect. You can also see that these sensors can partially see through the fog and detect the rescue randy inside it. The bottom left of the gif shows the lidar visualization; the range data are also affected by the scattering effect. Finally, the thermal camera image display on the bottom right shows that thermal cameras do not detect particles.

The sensor scattering effect can be configured by adding `<particle_scatter_ratio>` to the `<particle_emitter>` SDF element. This property determines the ratio of particles that will be detected by sensors. Increasing the ratio means there is a higher chance of particles reflecting and interfering with depth sensing, making the emitter appear more dense. Decreasing the ratio decreases the chance of particles reflecting and interfering with depth sensing, making it appear less dense.

See image below that reduces the particle scatter ratio to 0.1. The depth camera image, RGBD camera's depth image, and lidar's range data are noticeably less noisy than the gif above.

iche033 marked this conversation as resolved.
Show resolved Hide resolved

@image html files/particle_emitter/particle_scatter_ratio.png