Skip to content

Commit

Permalink
Maritime tutorials 💧 - Part 1 of 4 (#2257)
Browse files Browse the repository at this point in the history 
* Adding maritime tutorials.

Signed-off-by: Carlos Agüero <[email protected]>
Co-authored-by: Alejandro Hernández Cordero <[email protected]>
Co-authored-by: crvogt <[email protected]>
Co-authored-by: Ian Chen <[email protected]>
  • Loading branch information
@caguero @ahcorde
@crvogt @iche033
4 people committed Dec 22, 2023
1 parent f8b1a46 commit 66ae42c
Show file tree
Hide file tree
Showing 11 changed files with 6,731 additions and 0 deletions.
11 changes: 11 additions & 0 deletions tutorials.md.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,17 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
* \subpage blender_distort_meshes "Blender mesh distortion": Use a Blender Python script to programmatically deform and distort meshes to customized extents.
* \subpage blender_procedural_datasets "Generation of Procedural Datasets with Blender": Use Blender with a Python script to generate procedural datasets of SDF models.

## Maritime

* \subpage create_vehicle "Create a maritime vehicle:" How to design a maritime
model.
* \subpage adding_visuals "Adding visuals:" How to import 3D meshes into Gazebo
to increase the visual fidelity of your model.
* \subpage frame_reference "Frame of reference:" Decide the frame of reference
for your model.
* \subpage adding_system_plugins "Adding system plugins:" How to add plugins to
your model to provide extra capabilities to it.

## License

The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
Expand Down
139 changes: 139 additions & 0 deletions tutorials/adding_system_plugins.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
\page adding_system_plugins

# Overview

This tutorial explains how to add plugins to your model to provide extra
capabilities to it.

## Prerequisites

Make sure to go through the following tutorial first, where you'll learn how
to create the vehicle used in this tutorial.

https://gazebosim.org/api/sim/8/create_vehicle.html

## Related tutorials

https://gazebosim.org/api/sim/8/createsystemplugins.html

# Adding a system plugin

[This Gazebo tutorial](https://gazebosim.org/api/sim/8/createsystemplugins.html)
describes what is a system plugin in depth. Intuitively, you can envision a
system plugin as a piece of code that modifies the behavior of the simulation
when the general physics engine does not exactly capture your needs.
In our example, our turtle does not move because it's configured as a static
model. Let's see what happens if you remove that tag.

Modify your `~/gazebo_maritime/models/my_turtle/model.sdf` and remove the line
`<static>true</static>`. Then launch the simulation:

```bash
gz sim ~/gazebo_maritime/models/my_turtle/model.sdf
```

Hit the play button and you'll see how your turtle falls into the void. Perhaps
not what you expected but this is completely normal. Gazebo thinks that your
turtle is in the air without any support underneath. Then, gravity makes your
turtle to free fall forever.

If we want to simulate that our turtle floats like if it was in the water,
we'll need to attach a custom buoyancy plugin to our world. This buoyancy plugin
already exists in Gazebo, we only need to load it.

Now, run Gazebo with the provided `buoyant_turtle.sdf` world and you'll see how
your turtle does not sink anymore.

```bash
mkdir -p ~/gazebo_maritime/worlds
wget https://raw.githubusercontent.com/gazebosim/gz-sim/gz-sim8/tutorials/files/adding_system_plugins/buoyant_turtle.sdf -o ~/gazebo_maritime/worlds/buoyant_turtle.sdf
export GZ_SIM_RESOURCE_PATH=:$HOME/gazebo_maritime/models
gz sim -r ~/gazebo_maritime/worlds/buoyant_turtle.sdf
```

The turtle now stays floating with an oscillating movement up and down.

You just added buoyancy to your model! As a general rule, a maritime model will
need at least two system plugins:

1. Buoyancy
2. Hydrodynamics

As you have experienced, the buoyancy plugin generates an upthrust opposing some
weight of the model. Your model could have positive, neutral or negative
buoyancy. You'll be able to tune that aspect of your model later.

The hydrodynamics plugin models the force and torque that the vehicle
experiences when moving within a fluid. Intuitively, the hydrodynamics plugin
generates drag opposing the movement of the vehicle. If your model does not have
hydrodynamics, it will behave as if there's no resistance.

For the sake of illustrating the effect of hydrodynamics, let's attach a simple
controller to our turtle and move it without hydrodynamics. Keep in mind that
the goal is to move the model one meter and stop it.

Uncomment the following block from `buoyant_turtle.sdf`:

```xml
<plugin filename="gz-sim-trajectory-follower-system"
name="gz::sim::systems::TrajectoryFollower">
<link_name>base_link</link_name>
<force>0.2</force>
<torque>0.01</torque>
<range_tolerance>0.1</range_tolerance>
<waypoints>
<waypoint>1 0</waypoint>
</waypoints>
</plugin>
```

And run Gazebo:

```bash
gz sim -r ~/gazebo_maritime/worlds/buoyant_turtle.sdf
```

As you just observed, we failed in our goal and the turtle behaved as if it was
moving on ice. Now, let's add hydrodynamics.

Uncomment the following block from `buoyant_turtle.sdf`:

```xml
<plugin
filename="gz-sim-hydrodynamics-system"
name="gz::sim::systems::Hydrodynamics">
<link_name>base_link</link_name>
<xDotU>-0.04876161</xDotU>
<yDotV>-1.26324739</yDotV>
<zDotW>-1.26324739</zDotW>
<kDotP>0</kDotP>
<mDotQ>-0.3346</mDotQ>
<nDotR>-0.3346</nDotR>
<xUabsU>-0.62282</xUabsU>
<xU>-5</xU>
<yVabsV>-60.127</yVabsV>
<yV>-5</yV>
<zWabsW>-6.0127</zWabsW>
<zW>-100</zW>
<kPabsP>-0.001916</kPabsP>
<kP>-1</kP>
<mQabsQ>-6.32698957</mQabsQ>
<mQ>-1</mQ>
<nRabsR>-6.32698957</nRabsR>
<nR>-1</nR>
</plugin>
```

And run Gazebo:

```bash
gz sim -r ~/gazebo_maritime/worlds/buoyant_turtle.sdf
```

Now, when our simple trajectory controller reaches its target and stops appling
force, the turtle stops moving acting like the fluid decelerates its motion.
Additionally you can notice how the up and down oscillations are also damped by
the effect of the hydrodynamics.

The hydrodynamics are also configurable with its SDF parameters but we'll talk
about configuration in a separate tutorial.
122 changes: 122 additions & 0 deletions tutorials/adding_visuals.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
\page adding_visuals

# Overview

This tutorial describes how to import 3D meshes into Gazebo to increase the
visual fidelity of your model. Continuing with our example, we'll attach a 3D
mesh to our turtle, making it look much better.

## Related tutorials

https://gazebosim.org/api/sim/8/meshtofuel.html

The next tutorials, although still relevant, are from an older version of Gazebo
and some details might be different than the current versions:

https://classic.gazebosim.org/tutorials?tut=import_mesh&cat=build_robot
https://classic.gazebosim.org/tutorials?cat=guided_i&tut=guided_i2

## What is a visual?

The visual element specifies the shape used by the rendering engine. For most
use cases the collision and visual elements are the same. The most common use
for different collision and visual elements is to have a simplified collision
element paired with a visual element that uses a complex mesh. This will help
improve performance.

SDF supports the notion of visual as described
[here](http://sdformat.org/spec?ver=1.10&elem=visual).

From our
[previous tutorial](https://gazebosim.org/api/sim/8/create_vehicle.html),
the turtle visual is a cylinder. Let's use a COLLADA mesh instead.

## Model directory structure

Gazebo has defined a model directory structure that supports stand-alone models,
and the ability to share models via an online model database. Review
[this tutorial](https://gazebosim.org/api/sim/8/meshtofuel.html) for more
information.

Another benefit of Gazebo's model structure is that it conveniently organizes
resources, such as mesh files, required by the model.

```bash
my_turtle
├── materials Directory for textures
└── textures
├── meshes Directory for mesh files such as COLLADA, STL, and Wavefront OBJ files
├── thumbnails Directory for preview images on Fuel
├── model.config Meta data about the model
└── model.sdf SDF description of the model
```

Create the directories to add the mesh and its texture:

```bash
mkdir -p ~/gazebo_maritime/models/my_turtle/meshes
mkdir -p ~/gazebo_maritime/models/my_turtle/materials/textures
```

Next, download the COLLADA mesh and its texture.

```bash
wget https://raw.githubusercontent.com/gazebosim/gz-sim/gz-sim8/tutorials/files/adding_visuals/turtle.dae -o ~/gazebo_maritime/models/my_turtle/meshes/turtle.dae
wget https://raw.githubusercontent.com/gazebosim/gz-sim/gz-sim8/tutorials/files/adding_visuals/Turtle_BaseColor.png -o ~/gazebo_maritime/models/my_turtle/materials/textures/Turtle_BaseColor.png
```

Now, let's edit our `model.sdf` to use the new mesh as our visual.

```xml
<?xml version="1.0" ?>
<sdf version="1.6">
<model name="turtle">
<static>true</static>
<link name="base_link">

<inertial>
<pose>0 0 0 0 0 0</pose>
<mass>10</mass>
<inertia>
<ixx>0.35032999999999995</ixx>
<ixy>0</ixy>
<ixz>0</ixz>
<iyy>0.35032999999999995</iyy>
<iyz>0</iyz>
<izz>0.61250000000000006</izz>
</inertia>
</inertial>

<collision name='collision'>
<pose>0 0 0 0 0 0</pose>
<geometry>
<box>
<size>1 1 0.009948450858321252</size>
</box>
</geometry>
</collision>

<visual name="visual">
<geometry>
<mesh>
<uri>meshes/turtle.dae</uri>
</mesh>
</geometry>
</visual>

</link>
</model>
</sdf>
```

# Load your model in Gazebo

Launch Gazebo and load our model:

```bash
gz sim ~/gazebo_maritime/models/my_turtle/model.sdf
```

You should see your model visualized as a mesh now!

@image html files/adding_visuals/basic_visual_model.png
104 changes: 104 additions & 0 deletions tutorials/create_vehicle.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
\page create_vehicle

# Overview

This tutorial goes through the process of designing a maritime model to be used
in Gazebo. Our basic model will be a turtle. First, we'll start simple and will
add more features as we progress in the tutorials.

## Related tutorials

https://gazebosim.org/docs/harmonic/building_robot

# Design a basic SDF model

Create a workspace to store your brand new model named `my_turtle`.

```bash
mkdir -p ~/gazebo_maritime/models/my_turtle && cd ~/gazebo_maritime/models/my_turtle
```

Each model must have a `model.config` file in the model's root directory that
contains meta information about the model. Create a `model.config` file:

```xml
<?xml version="1.0"?>
<model>
<name>my_turtle</name>
<version>1.0</version>
<sdf version="1.6">model.sdf</sdf>

<author>
<name>Carlos Agüero</name>
<email>[email protected]</email>
</author>

<description>
My 3D turtle.
</description>
</model>
```

You can find a description of the allowed elements in `model.config` in
[this Gazebo Classic tutorial](https://classic.gazebosim.org/tutorials?tut=model_structure&cat=build_robot).

Create a `model.sdf` file that contains the Simulator Description Format of the
model. You can find more information on the [SDF website](http://sdformat.org/).

```xml
<?xml version='1.0'?>
<sdf version='1.6'>
<model name="my_turtle">
<static>true</static>
<link name='base_link'>

<inertial>
<pose>0 0 0 0 0 0</pose>
<mass>10</mass>
<inertia>
<ixx>0.35032999999999995</ixx>
<ixy>0</ixy>
<ixz>0</ixz>
<iyy>0.35032999999999995</iyy>
<iyz>0</iyz>
<izz>0.61250000000000006</izz>
</inertia>
</inertial>

<collision name='collision'>
<geometry>
<box>
<size>1 1 0.009948450858321252</size>
</box>
</geometry>
</collision>

<visual name='visual'>
<pose>0.08 0 0.05 0 0 0</pose>
<geometry>
<cylinder>
<radius>0.35</radius>
<length>0.23</length>
</cylinder>
</geometry>
</visual>
</link>
</model>
</sdf>
```

The `model.sdf` file contains the necessary tags to instantiate a very minimal
model named `my_turtle` using SDF version 1.6.

# Load your model in Gazebo

Launch Gazebo and load our model:

```bash
gz sim ~/gazebo_maritime/models/my_turtle/model.sdf
```

You should see your model visualized as a cylinder and the Gazebo `Entity Tree`
should capture its structure.

@image html files/create_vehicle/basic_model.png
Loading

0 comments on commit 66ae42c

Please sign in to comment.