Add tutorials for ApplyForceTorque and MouseDrag plugins (#2083)

Adds tutorials for the new ApplyForceTorque plugin (including the features added in #2051 and #2056) and for the new MouseDrag plugin. --------- Signed-off-by: Henrique-BO <[email protected]>
gazebosim · Aug 29, 2023 · 6f4bcca · 6f4bcca
1 parent bfe5836
commit 6f4bcca
Show file tree

Hide file tree

Showing 11 changed files with 184 additions and 0 deletions.
diff --git a/tutorials.md.in b/tutorials.md.in
@@ -21,6 +21,8 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively.
 * \subpage model_photo_shoot "Model Photo Shoot" Taking perspective, top, front, and side pictures of a model.
 * \subpage videorecorder "Video Recorder": Record videos from the 3D render window.
 * \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server.
+* \subpage apply_force_torque "Apply Force and Torque": Applying forces and/or torques to models during simulation through the GUI.
+* \subpage mouse_drag "Mouse Drag": Move models by dragging them in the scene using forces and torques.
 
 ### Migration from Gazebo classic
 

diff --git a/tutorials/apply_force_torque.md b/tutorials/apply_force_torque.md
@@ -0,0 +1,116 @@
+\page apply_force_torque Apply Force and Torque
+
+The Apply Force Torque plugin allows users to apply forces and/or torques to
+links in the simulation through the graphical user interface.
+
+## Examples
+
+Let's go through an example of applying force and torque to simple models. Open
+the `shapes.sdf` world with
+
+```bash
+gz sim shapes.sdf
+```
+
+From the plugin dropdown, select the `Apply Force Torque` plugin. Make sure the
+simulation isn't paused.
+
+![Interface](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/apply_force_torque/Interface.png)
+
+### Apply force to a link
+
+We want to apply force to the `cylinder` model. Select the model, either by
+clicking on it in the scene or through the Entity Tree. If the model had
+multiple links, we could select through the interface which one to apply the
+force to (in this case, `cylinder_link`).
+
+On the dialog, write `10000` on the `X` field under `Force` and click on
+`Apply Force`. The cylinder will be pushed on the X direction. The force was
+applied in the link's `X` direction for a single time-step, which is in the
+order of milliseconds, thus the need for such a large force.
+
+![Apply Force](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/apply_force_torque/Force.png)
+
+### Apply torque to a link
+
+On the dialog, write `2000` on the `X` field under `Torque` and click on
+`Apply Torque` to see the cylinder rotate slightly.
+
+![Apply Torque](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/apply_force_torque/Torque.png)
+
+### Apply force with an offset
+
+By default, the force is applied to the link's center of mass, but this can be
+modified through the `Offset` fields. On the dialog, write `1000` on the `X`
+field under `Force` and `1` under the `Z` field under `Offset`. Press
+`Apply Force` to see the model move slightly in the `X` direction while also
+rotating around the `Y` direction.
+
+![Apply Force Offset](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/apply_force_torque/ForceOffset.png)
+
+### Rotation tool
+
+On the dialog, write `10000` on the `X` field under `Force`. Click on the force
+vector to make the rotation tool appear. Drag the blue circle to rotate the
+force around the `Z` axis so that it is aligned with the `Y` direction. Notice
+how the XYZ fields changed, but not the magnitude. Press `Apply Force` to see
+the model move in the `Y` direction.
+
+![Rotation tool](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/apply_force_torque/RotationTool.png)
+
+## The interface explained
+
+> **Note**: If you apply force and/or torque while the simulation is paused,
+they will accumulate and be applied all at once when the simulation is
+unpaused.
+
+### Force
+
+- **Force X, Y, Z**: Each field specifies how much force will be applied on that
+direction, in Newtons (N). The frame is fixed to the link.
+
+- **Mag**: The total magnitude of the force which will be applied, which is the
+Euclidean norm of the 3 forces above. Changing the magnitude changes the XYZ
+fields proportionally, maintaining the force direction.
+
+- **Offset X, Y, Z**: By default, force is applied to the link's center of mass,
+in meters. Here you can edit the X, Y and Z fields to give the force an offset
+with respect to the center of mass expressed in the link's frame.
+
+  - **Tip**: Right-click the model and choose `View` -> `Center of Mass` to see
+    its position. You will want to also make the model transparent to see the
+    center of mass visual (`View` -> `Transparent`).
+
+- **Apply Force**: Click this to apply only force for one time step. Keep in
+mind that time steps are typically in the order of milliseconds, so relatively large
+forces are needed in order to apply a significant impulse.
+
+### Torque
+
+- **X, Y, Z**: Each field specifies how much torque will be applied about that
+axis, in Newton-meters (N.m). The frame is fixed to the link.
+
+- **Mag**: The total magnitude of the torque which will be applied, which is the
+Euclidean norm of the 3 torques above. Changing the magnitude changes the XYZ
+fields proportionally, maintaining the torque direction.
+
+- **Apply Torque**: Click this to apply only torque for one time step. Keep in
+mind that time steps are typically in the order of milliseconds, so relatively large
+torques are needed in order to apply a significant angular impulse.
+
+  - **Note**: Torque is always applied about the center of mass.
+
+### Apply All
+
+Force and torque are applied at the same time, i.e. apply a wrench.
+
+### Rotation Tool
+
+The vector (force or torque) directions will always match the directions
+specified in the dialog. From the dialog, the direction can be changed by
+editing the numbers on the XYZ fields.
+
+From the scene, select a vector to enable the rotation tool, then drag the
+handles. This changes the direction of the vector, updating the XYZ fields
+accordingly without modifying its magnitude. You may click again on the vector
+to unselect the rotation tool.
diff --git a/tutorials/files/apply_force_torque/Force.png b/tutorials/files/apply_force_torque/Force.png
diff --git a/tutorials/files/apply_force_torque/ForceOffset.png b/tutorials/files/apply_force_torque/ForceOffset.png
diff --git a/tutorials/files/apply_force_torque/Interface.png b/tutorials/files/apply_force_torque/Interface.png
diff --git a/tutorials/files/apply_force_torque/RotationTool.png b/tutorials/files/apply_force_torque/RotationTool.png
diff --git a/tutorials/files/apply_force_torque/Torque.png b/tutorials/files/apply_force_torque/Torque.png
diff --git a/tutorials/files/mouse_drag/Interface.png b/tutorials/files/mouse_drag/Interface.png
diff --git a/tutorials/files/mouse_drag/Rotation.png b/tutorials/files/mouse_drag/Rotation.png
diff --git a/tutorials/files/mouse_drag/Translation.png b/tutorials/files/mouse_drag/Translation.png
diff --git a/tutorials/mouse_drag.md b/tutorials/mouse_drag.md
@@ -0,0 +1,66 @@
+\page mouse_drag Mouse Drag
+
+The Mouse Drag plugin allows the user to exert forces and/or torques by dragging
+objects in the scene with the mouse cursor. It has two modes: rotation and
+translation.
+
+To use it, open any world (such as `shapes.sdf`) and select `Mouse Drag` from
+the plugin dropdown to load the plugin.
+
+![Interface](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/mouse_drag/Interface.png)
+
+## Rotation mode
+
+The rotation mode is activated by Ctrl+Left-clicking and holding a link in the
+scene. Dragging the mouse causes a pure torque to be applied, contained in a
+plane parallel to the camera. The transparent red bounding box displays the
+desired orientation of the link corresponding to the current mouse position.
+
+The magnitude of the torque is calculated by a spring-damper system with a
+constant stiffness and critical damping. It is also proportional to the link's
+inertia, so that the same stiffness causes similar effects on different links.
+The rotational stiffness can be modified through the interface.
+
+![Rotation mode](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/mouse_drag/Rotation.png)
+
+## Translation mode
+
+The translation mode is activated by Ctrl+Right-clicking and holding a link in
+the scene. Dragging the mouse will then move the link towards the mouse
+position. On the interface, you may select whether the force should be applied
+to the link's center of mass or to the point where the mouse click occured.
+
+If center of mass is selected, only a force is applied, with a magnitude given
+by a constant stiffness and critical damping, scaled by the mass of the link.
+The force is always contained in a plane parallel to the camera and passing
+through the application point, represented by a transparent gray plane. The
+visualization also shows an arrow from the application point to the target
+position under the mouse cursor.
+
+If center of mass is not selected, an additional torque is applied to account
+for the offset in the force application point. In this case, the rotation of
+the object is also slightly damped (according to the rotational stiffness).
+The position stiffness can be modified through the interface.
+
+![Translation mode](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/mouse_drag/Translation.png)
+
+## SDF configuration
+
+The rotation and position stiffness may also be configured in the SDF file.
+To do this, add the `<rotation_stiffness>` and/or `<position_stiffness>` to the
+plugin element under `<gui>`.
+
+```xml
+<sdf version="1.6">
+  <world name="mouse_drag">
+    <gui>
+      <plugin filename="MouseDrag">
+        <rotation_stiffness>100.0</rotation_stiffness>
+        <position_stiffness>100.0</position_stiffness>
+      </plugin>
+      ...
+    </gui>
+    ...
+  </world>
+</sdf>
+```