First iteration

Docs/index.md

@@ -143,10 +143,12 @@ CARLA forum</a>
         — Add new content to CARLA.  
     [__Create a sensor__](tuto_D_create_sensor.md)
         — Develop a new sensor to be used in CARLA.  
+    [__Customize vehicle suspension__](tuto_D_customize_vehicle_suspension.md)
+        — Modify the suspension system of a vehicle.  
     [__Make a release__](tuto_D_make_release.md)
         — For developers who want to publish a release.  
     [__Generate detailed colliders__](tuto_D_generate_colliders.md)
-        — Created detailed colliders for vehicles.  
+        — Create detailed colliders for vehicles.  
     [__Generate pedestrian navigation__](tuto_D_generate_pedestrian_navigation.md)
         — Obtain the information needed for walkers to move around.  
     </p>

Docs/tuto_D_customize_vehicle_suspension.md

@@ -0,0 +1,224 @@
+# Customize vehicle suspension
+
+This tutorial covers the basics of the suspension system for CARLA vehicles, and how are these implemented for the different vehicles available. Use this information to access the suspension parameterization of a vehicle in Unreal Engine, and customize it at will.  
+
+*   [__Basics of the suspension system__](#basics-of-the-suspension-system)  
+*   [__Suspension groups__](#suspension-groups)  
+
+
+---
+## Basics of the suspension system
+
+The suspension system of a vehicle is defined by the wheels of said vehicle. Each wheel has an independent blueprint with some parameterization, which includes the suspension system. 
+
+These blueprints can be found in `Content/Carla/Blueprints/Vehicles/<vehicle_name>`. They are named such as: `BP_<vehicle_name>_<F/B><R/L>W`.  
+
+*   `F` or `B` is used for front or back wheels correspondingly.  
+*   `R` or `L` is used for right or left wheels correspondingly.  
+
+![tuto_suspension_blueprints](img/tuto_suspension_blueprints.jpg)
+<div style="text-align: right"><i>In this example, the blueprint of the front left wheel of the Audi A2 is named as <code>BP_AudiA2_FLW</code>.</i></div>
+
+`shape_radius` for the wheel to rest over the road, neither hovering nor inside of it. 
+
+Inside the blueprint, there is a section with some parameterization regarding the suspension of the wheel. Here are their definitions as described in Unreal Engine.  
+
+*   `Suspension Force Offset` — Vertical offset from where suspension forces are applied (along Z axis). 
+*   `Suspension Max Raise` — How far the wheel can go above the resting position. 
+*   `Suspension Max Drop` — How far the wheel can drop below the resting position. 
+*   `Suspension Natural Frequency` — Oscillation frequency of the suspension. Standard cars have values between 5 and 10. 
+*   `Suspension Damping Ratio` — The rate at which energy is dissipated from the spring. Standard cars have values between 0.8 and 1.2. Values < 1 are more sluggish, values > 1 are more twitchy.  
+*   `Sweep Type` — Wether wheel suspension considers simple, complex or both.  
+
+![tuto_suspension_parameterization](img/tuto_suspension_parameterization.jpg)
+<div style="text-align: right"><i>The Suspension panel inside a wheel blueprint.</i></div>
+
+!!! Note
+    By default, all the wheels of a vehicle have the same parameterization in CARLA. The following explanations will be covered per vehicle, instead of per wheel.  
+
+---
+## Suspension groups
+
+According to their system suspension, vehicles in CARLA can be classified in five groups. All the vehicles in a group have the same parameterization, as they are expected to have a similar behaviour on the road. The suspension of a vehicle can be modified at will, and is no subject to these five groups. However understanding these, and observing their behaviour in the simulation can be of great use to define a custom suspension.  
+
+The five groups are: *Coupé*, *Off-road*, *Truck*, *Urban*, and *Van*. In closer observation, the parameterization of these groups follows a specific pattern.  
+
+<table class ="defTable">
+<tbody>
+<td><b>Stiff suspension</b></td>
+<td>Coupé</td>
+<td>Urban</td>
+<td>Van</td>
+<td>Off-road</td>
+<td>Truck</td>
+<td><b>Soft suspension</b></td>
+</tbody>
+</table>
+<br>
+
+The closer a vehicle is to a stiff suspension, its parameterization changes.  
+
+*   __Decrease__ of `Suspension Max Raise` and `Suspension Max Drop` — Stiff vehicles are meant to drive over plane roads with no bumps. For the sake of aerodynamics, the chassis is not supposed to move greatly, but remain constantly close to the ground.  
+*   __Decrease__ of `Suspension Natural Frequency` — Stiff vehicles tend to be lighter, so the amount of bounces for the same joggle is expected to be lower.  
+*   __Increase__ of `Suspension Damping Ratio` — The absortion of the bouncing by the dampers is greater for stiff vehicles.  
+
+> TO BE DISCUSSED: Suspension natural frequency increases for stiff vehicles instead?? !!
+
+!!! Note
+    `Suspension Force Offset` and `Sweep Type` remain constant for every group. No offset is intended to be applied on forces, and the sweep tests for detecting collisions should be the same for all vehicles.  
+
+
+*   __Coupé__ — Vehicles with the stiffest suspension.  
+<table class ="defTable">
+<thead>
+<th>Parameterization</th>
+<th>Vehicles</th>
+</thead>
+<tbody>
+<td>
+<code>Suspension Force Offset</code> — <code>0.0</code><br>
+<code>Suspension Max Raise</code> — <code>7.5</code><br>
+<code>Suspension Max Drop</code> — <code>7.5</code><br>
+<code>Suspension Natural Frequency</code> — <code>10.0</code><br>
+<code>Suspension Damping Ratio</code> — <code>1.0</code><br>
+<code>Sweep Type</code> — <code>SimpleAndComplex</code><br>
+</td>
+<td>
+<code>vehicle.seat.leon</code><br>
+<code>vehicle.audi.a2</code><br>
+<code>vehicle.audi.tt</code><br>
+<code>vehicle.tesla.model3</code><br>
+<code>vehicle.lincoln.mkz2017</code><br>
+<code>vehicle.mercedes-benz.coupe</code><br>
+</td>
+</tbody>
+</table>
+<br>
+
+
+*   __Off-road__ — Vehicles with a soft suspension.  
+<table class ="defTable">
+<thead>
+<th>Parameterization</th>
+<th>Vehicles</th>
+</thead>
+<tbody>
+<td>
+<code>Suspension Force Offset</code> — <code>0.0</code><br>
+<code>Suspension Max Raise</code> — <code>15.0</code><br>
+<code>Suspension Max Drop</code> — <code>15.0</code><br>
+<code>Suspension Natural Frequency</code> — <code>7.0</code><br>
+<code>Suspension Damping Ratio</code> — <code>0.5</code><br>
+<code>Sweep Type</code> — <code>SimpleAndComplex</code><br>
+</td>
+<td>
+<code>vehicle.audi.etron</code><br>
+<code>vehicle.nissan.patrol</code><br>
+<code>vehicle.tesla.cybertruck</code><br>
+<code>vehicle.jeep.wrangler_rubicon</code><br>
+</td>
+</tbody>
+</table>
+<br>
+
+*   __Truck__ — Vehicles with the softest suspension.  
+<table class ="defTable">
+<thead>
+<th>Parameterization</th>
+<th>Vehicles</th>
+</thead>
+<tbody>
+<td>
+<code>Suspension Force Offset</code> — <code>0.0</code><br>
+<code>Suspension Max Raise</code> — <code>17.0</code><br>
+<code>Suspension Max Drop</code> — <code>17.0</code><br>
+<code>Suspension Natural Frequency</code> — <code>6.0</code><br>
+<code>Suspension Damping Ratio</code> — <code>0.4</code><br>
+<code>Sweep Type</code> — <code>SimpleAndComplex</code><br>
+</td>
+<td>
+<code>vehicle.carlamotors.carlacola</code><br>
+</td>
+</tbody>
+</table>
+<br>
+
+*   __Urban__ —  Vehicles with a soft suspension.  
+<table class ="defTable">
+<thead>
+<th>Parameterization</th>
+<th>Vehicles</th>
+</thead>
+<tbody>
+<td>
+<code>Suspension Force Offset</code> — <code>0.0</code><br>
+<code>Suspension Max Raise</code> — <code>8.0</code><br>
+<code>Suspension Max Drop</code> — <code>8.0</code><br>
+<code>Suspension Natural Frequency</code> — <code>9.0</code><br>
+<code>Suspension Damping Ratio</code> — <code>0.8</code><br>
+<code>Sweep Type</code> — <code>SimpleAndComplex</code><br>
+</td>
+<td>
+<code>vehicle.nissan.micra</code><br>
+<code>vehicle.mustang.mustang</code><br>
+<code>vehicle.mini.cooperst</code><br>
+<code>vehicle.citroen.c3</code><br>
+<code>vehicle.chevrolet.impala</code><br>
+<code>vehicle.toyota.prius</code><br>
+<code>vehicle.dodge_charger.police</code><br>
+<code>vehicle.bmw.grandtourer</code><br>
+</td>
+</tbody>
+</table>
+<br>
+
+*   __Van__ —  Vehicles with a middle-ground suspension.  
+<table class ="defTable">
+<thead>
+<th>Parameterization</th>
+<th>Vehicles</th>
+</thead>
+<tbody>
+<td>
+<code>Suspension Force Offset</code> — <code>0.0</code><br>
+<code>Suspension Max Raise</code> — <code>9.0</code><br>
+<code>Suspension Max Drop</code> — <code>9.0</code><br>
+<code>Suspension Natural Frequency</code> — <code>9.0</code><br>
+<code>Suspension Damping Ratio</code> — <code>0.9</code><br>
+<code>Sweep Type</code> — <code>SimpleAndComplex</code><br>
+</td>
+<td>
+<code>vehicle.volkswagen.t2</code><br>
+</td>
+</tbody>
+</table>
+<br>
+
+
+---
+
+Use the forum to post any doubts, issues or suggestions regarding this topic.  
+
+<div class="build-buttons">
+<p>
+<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
+CARLA forum</a>
+</p>
+</div>
+
+Here are some advised readings after this one.  
+
+<div class="build-buttons">
+<p>
+<a href="../tuto_G_control_vehicle_physics" target="_blank" class="btn btn-neutral" title= "Set runtime changes on a vehicle physics.">
+Control vehicle physics</a>
+</p>
+<p>
+<a href="../tuto_G_add_friction_triggers" target="_blank" class="btn btn-neutral" title= "Define dynamic box triggers for wheels.">
+Add friction triggers</a>
+</p>
+<p>
+<a href="../tuto_D_generate_colliders" target="_blank" class="btn btn-neutral" title="Create detailed colliders for vehicles">
+Generate detailed colliders</a>
+</p>
+</div>

mkdocs.yml

@@ -62,6 +62,7 @@ nav:
 - Tutorials (developers):
   - 'Contribute with assets': 'tuto_D_contribute_assets.md'
   - 'Create a sensor': 'tuto_D_create_sensor.md'
+  - 'Customize vehicle suspension': 'tuto_D_customize_vehicle_suspension.md'
   - 'Generate detailed colliders': 'tuto_D_generate_colliders.md'
   - 'Make a release': 'tuto_D_make_release.md'
   - 'Generate pedestrian navigation': 'tuto_D_generate_pedestrian_navigation.md'