Maritime tutorials 💧 - Part 4 of 4

src/systems/lift_drag/LiftDrag.cc

@@ -280,7 +280,9 @@ void LiftDragPrivate::Update(EntityComponentManager &_ecm)
   }
 
   if (!worldLinVel || !worldAngVel || !worldPose)
+  {
     return;
+  }
 
   const auto &pose = worldPose->Data();
   const auto cpWorld = pose.Rot().RotateVector(this->cp);
@@ -292,7 +294,9 @@ void LiftDragPrivate::Update(EntityComponentManager &_ecm)
   }
 
   if (vel.Length() <= 0.01)
+  {
     return;
+  }
 
   const auto velI = vel.Normalized();
 

tutorials.md.in

@@ -51,7 +51,6 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 * \subpage battery "Battery": Keep track of battery charge on robot models.
 * \subpage particle_emitter "Particle emitter": Using particle emitters in simulation
 * \subpage spherical_coordinates "Spherical coordinates": Working with latitude and longitude
-* \subpage underwater_vehicles "Underwater Vehicles": Understand how to simulate underwater vehicles.
 * \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation.
 * \subpage auto_inertia_calculation "Automatic Inertia Calculation": Automatically compute inertia values(mass, mass matrix, center of mass) for SDFormat links.
 
@@ -81,6 +80,26 @@ 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 theory_buoyancy "Buoyancy: " Describe the theory of operation of the
+buoyancy plugin.
+* \subpage theory_hydrodynamics "Hydrodynamics:" Describe the theory of
+operation of the hydrodynamics plugin.
+* \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.
+* \subpage lander "Create a lander vehicle:" How to create a lander robot.
+* \subpage underwater_vehicles "Create an underwater vehicle:" How to create an
+underwater robot.
+* \subpage surface_vehicles "Create a surface vehicle:" How to create a maritime
+surface robot.
+
 ## 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