docs: Add comprehensive friction parameters tutorial (fixes #258)#886
Conversation
…#258) Signed-off-by: Pavan C N <p0073100@gmail.com>
strangerwhoisharborofdoom
requested review from
azeey and
scpeters
as code owners
There was a problem hiding this comment.
Pull request overview
Adds a new Tutorial 10 intended to document SDF friction parameters and how they map to the Gazebo Physics engine plugins, addressing issue #258 by providing a single reference for friction tuning and engine differences.
Changes:
- Added
tutorials/10_friction_parameters.mdfriction-parameters tutorial with explanations, SDF snippets, and troubleshooting guidance. - Included an engine support comparison table (DART / Bullet / TPE) and a “complete” example.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | mu | ✓ Full | ✓ Full | ✓ Full | | ||
| | mu2 | ✓ Full | ✓ Full | ⚠ Approx | | ||
| | slip1 | ✓ Full | ✓ Full | ⚠ Limited | | ||
| | slip2 | ✓ Full | ✓ Full | ⚠ Limited | | ||
| | fdir1 | ✓ Full | ⚠ Partial | ✗ None | |
There was a problem hiding this comment.
The engine support claims for friction parameters appear incorrect vs the plugins in this repo. The Bullet plugin currently only supports mu / mu2 (see comment in bullet/src/SDFFeatures.cc), and TPE doesn’t appear to parse <surface><friction> at all, so marking slip1, slip2, and fdir1 as supported by Bullet/TPE is misleading. Please align the per-parameter “Engine Support” sections and the comparison table with what the DART/Bullet/TPE implementations actually read from SDF.
| | mu | ✓ Full | ✓ Full | ✓ Full | | |
| | mu2 | ✓ Full | ✓ Full | ⚠ Approx | | |
| | slip1 | ✓ Full | ✓ Full | ⚠ Limited | | |
| | slip2 | ✓ Full | ✓ Full | ⚠ Limited | | |
| | fdir1 | ✓ Full | ⚠ Partial | ✗ None | | |
| | mu | ✓ Full | ✓ Full | ✗ None | | |
| | mu2 | ✓ Full | ✓ Full | ✗ None | | |
| | slip1 | ✓ Full | ✗ None | ✗ None | | |
| | slip2 | ✓ Full | ✗ None | ✗ None | | |
| | fdir1 | ✓ Full | ✗ None | ✗ None | |
|
|
||
| ### mu2 (Secondary Friction Coefficient) | ||
|
|
||
| The `mu2` parameter defines friction in the second friction direction (typically the y-axis of the contact surface). When `mu2` is 0, it defaults to the value of `mu`. |
There was a problem hiding this comment.
This sentence is likely incorrect: setting mu2 to 0 will be treated as an explicit 0 secondary friction, not “default to mu”. In the DART plugin, mu2 is only applied when the element exists; if present (even 0), it’s used as-is. Recommend rewording to clarify that the defaulting behavior (if any) is about the element being omitted, not its value being 0.
| The `mu2` parameter defines friction in the second friction direction (typically the y-axis of the contact surface). When `mu2` is 0, it defaults to the value of `mu`. | |
| The `mu2` parameter defines friction in the second friction direction (typically the y-axis of the contact surface). If the `<mu2>` element is omitted, some engines may fall back to using the `mu` value; if `<mu2>` is present, its value (including `0`) is treated as the explicit secondary friction coefficient. |
| **Common Frame Values:** | ||
| - `__model__`: Model frame | ||
| - `__world__`: World frame | ||
| - Link name: Specific link frame | ||
|
|
There was a problem hiding this comment.
The “Common Frame Values” list (__model__, __world__) doesn’t appear to be supported by the current DART parsing logic, which looks up a BodyNode by the attribute value. To avoid users copying non-working examples, consider changing this section to state that the value must match a link/body node name in the model (and document what happens if it can’t be found).
| **Engine Support:** | ||
| - DART: ✓ Fully supported | ||
| - Bullet: ✓ Supported | ||
| - TPE: ⚠ Limited support | ||
|
|
||
| ### slip2 (Lateral Slip) | ||
|
|
||
| The `slip2` parameter defines slip in the secondary friction direction. | ||
|
|
There was a problem hiding this comment.
DART’s support for mu2 / slip1 / slip2 / fdir1 is guarded by DART_VERSION_AT_LEAST(6, 10, 0) in dartsim/src/SDFFeatures.cc. The tutorial currently presents these as unconditionally available in DART; please document the minimum DART version requirement (or note the fallback behavior for older DART versions) so readers don’t assume these parameters will work everywhere.
| - [SDF Specification - Surface](https://sdformat.org/spec) | ||
| - [DART Physics Engine Documentation](https://dartsim.github.io/) | ||
| - [Bullet Physics Documentation](https://pybullet.org/) | ||
| - [Gazebo Physics Tutorial 04: Physics Engines](04_physics_engines.md) | ||
|
|
||
| ## Contributing | ||
|
|
||
| If you find discrepancies in friction behavior across engines, please report them as issues in the [gz-physics repository](https://github.com/gazebosim/gz-physics/issues). | ||
|
|
||
| --- | ||
|
|
||
| *This tutorial is part of the Gazebo Physics tutorial series. For installation instructions, see [Tutorial 02](02_installation.md).* |
There was a problem hiding this comment.
The references at the end use direct relative markdown links to other tutorials. In this repo, tutorials are usually cross-linked with Doxygen \ref / \subpage ids (e.g. \ref physicsengine), which makes links stable even if filenames change. Consider switching these links to the corresponding \ref ids to match the rest of the tutorial set.
| # Tutorial 10: Friction Parameters for Physics Engines | ||
|
|
||
| This tutorial provides comprehensive documentation on friction parameters supported by Gazebo Physics engines. Understanding these parameters is crucial for creating realistic robot simulations with accurate contact behavior. | ||
|
|
||
| ## Overview | ||
|
|
||
| Friction modeling in physics simulation is essential for realistic robot behavior, especially for: | ||
| - Wheeled and legged locomotion | ||
| - Manipulation and grasping | ||
| - Surface interactions | ||
| - Stability analysis | ||
|
|
||
| Gazebo Physics supports multiple physics engines (DART, Bullet, TPE), each with slightly different friction parameter implementations. |
There was a problem hiding this comment.
This tutorial doesn’t follow the repository’s Doxygen tutorial format (e.g., \page <id> <title> at the top), so it likely won’t be picked up / cross-referenced consistently with the rest of the tutorial set. Consider converting the header to a \page with a stable id (and using \ref / \subpage style links), and add it to tutorials.md.in’s Contents list so it appears in the generated docs navigation.
| **Note:** In DART, `fdir1` can be expressed in different frames using the `expressed_in` attribute (see below). | ||
|
|
||
| ### expressed_in (Frame Specification) | ||
|
|
||
| The `expressed_in` attribute (DART-specific) specifies the reference frame in which `fdir1` is expressed. | ||
|
|
||
| **SDF Example:** | ||
| ```xml | ||
| <surface> | ||
| <friction> | ||
| <dart> | ||
| <fdir1 expressed_in="__model__">1 0 0</fdir1> | ||
| </dart> | ||
| </friction> | ||
| </surface> | ||
| ``` |
There was a problem hiding this comment.
The DART expressed_in documentation/examples here don’t match the implementation in this repo. In dartsim/src/SDFFeatures.cc, the attribute checked is gz:expressed_in (namespaced) on the <ode><fdir1 ...> element, and the value is treated as a skeleton BodyNode name (typically a link name), not __model__ / __world__ or a separate <dart> block. Please update the text and XML examples to reflect the actual supported syntax and values.
Summary
This PR addresses issue #258 by adding a comprehensive tutorial (Tutorial 10) documenting friction parameters for Gazebo Physics engines.
Changes
tutorials/10_friction_parameters.mdwith detailed documentation on:Tutorial Contents
The tutorial includes:
Engine Support Documentation
Related Issue
Fixes #258
Checklist