Maritime tutorials 💧 - Part 1 of 4 (gazebosim#2257)

* 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]>
BooCreator · Dec 22, 2023 · 66ae42c · 66ae42c
1 parent f8b1a46
commit 66ae42c
Show file tree

Hide file tree

Showing 11 changed files with 6,731 additions and 0 deletions.
diff --git a/tutorials.md.in b/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).

diff --git a/tutorials/adding_system_plugins.md b/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.
diff --git a/tutorials/adding_visuals.md b/tutorials/adding_visuals.md
@@ -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
diff --git a/tutorials/create_vehicle.md b/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