Maritime tutorials 💧 - Part 1 of 4

tutorials.md.in

@@ -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).

tutorials/adding_system_plugins.md

@@ -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.

tutorials/adding_visuals.md

@@ -0,0 +1,118 @@
+\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
+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

tutorials/create_vehicle.md

@@ -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