physics#

Gazebo Physics : Physics classes and functions for robot applications

Maintainer: scpeters AT openrobotics DOT org

GitHub open issues GitHub open pull requests Discourse topics Hex.pm

Build

Status

Test coverage

codecov

Ubuntu Noble

Build Status

Homebrew

Build Status

Windows

Build Status

Gazebo Physics, a component of Gazebo, provides an abstract physics interface designed to support simulation and rapid development of robot applications.

Table of Contents

Motivation

Features

Install

Usage

Folder Structure

Code of Conduct

Contributing

Versioning

License

Motivation

Many physics simulation software libraries have been designed for different applications (gaming, robotics, science) and with different features (rigid or deformable contact, 2d or 3d). Gazebo Physics is designed on the premise that there is not a single physics engine that is universally best for all simulation contexts. It should be possible to support a different set of features for each physics engine according to its capabilities. A physics engine can then be chosen for each application based on its context.

Features

Gazebo Physics provides the following functionality:

  • Granular definition of physics engine features as optional API’s.

  • Plugin interface for loading physics engines with requested features at runtime.

  • Features for common aspects of rigid body dynamic simulation

    • Construct model from SDFormat file.

    • Collision shapes (such as box, sphere, cylinder, cone, capsule, ellipsoid, mesh, heightmap).

    • Joint types (such as revolute, prismatic, fixed, ball, screw, universal).

    • Step simulation, get/set state, apply inputs.

  • Reference implementation of physics plugin using dartsim.

  • A custom physics engine focused on fast kinematics of large environments, the Trivial Physics Engine.

  • CompositeData structures for efficiently using native types in API.

Install

See the installation tutorial.

Usage

Please refer to the examples directory.

Documentation

API and tutorials can be found at https://gazebosim.org/libs/physics.

On Ubuntu, you can also generate the documentation from a clone of this repository by following these steps.

  1. You will need Doxygen, which can be installed using

    sudo apt-get install doxygen

  2. Install dependencies

    sudo apt-add-repository -s "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -c -s) main"
sudo apt-get build-dep -y libgz-physics8-dev

  3. Clone the repository

    git clone https://github.com/gazebosim/gz-physics -b gz-physics8

  4. Configure and build the documentation.

    cd gz-physics; mkdir build; cd build; cmake ..; make doc

  5. View the documentation by running the following command from the build directory.

    firefox doxygen/html/index.html

Testing

Follow these steps to run tests and static code analysis in your clone of this repository.

  1. Follow the “Source Installation” instructions in the installation tutorial.

  2. Run tests.

    make test

  3. Static code checker.

    make codecheck

Folder Structure

Refer to the following table for information about important directories and files in this repository.

gz-physics
├── bullet                    Files for bullet plugin component.
├── bullet-featherstone       Files for bullet-featherstone plugin component.
├── dartsim                   Files for dartsim plugin component.
├── examples                  Examples about how to use the library.
├── heightmap                 Heightmap related header files.
├── include/gz/physics        Header files.
├── mesh                      Files for mesh component.
├── sdf                       Files for sdf component.
├── src                       Source files and unit tests.
├── test
│    ├── benchmark            Benchmark tests.
│    ├── common_test          Tests common to multiple physics plugins.
│    ├── include              Header files for tests.
│    ├── integration          Integration tests.
│    ├── performance          Performance tests.
│    ├── plugins              Plugins used in tests.
│    ├── regression           Regression tests.
│    ├── resources            Models and mesh resource files.
│    └── static_assert        Tests involving compilation failures.
├── tpe
│    ├── lib                  Implementation of TPE engine.
│    └── plugin               Files for TPE plugin component.
├── tutorials                 Tutorials, written in markdown.
├── Changelog.md              Changelog.
└── CMakeLists.txt            CMake build script.

Contributing

Please see the contribution guide.

Code of Conduct

Please see CODE_OF_CONDUCT.md.

Versioning

This library uses Semantic Versioning. Additionally, this library is part of the Gazebo project which periodically releases a versioned set of compatible and complementary libraries. See the Gazebo website for version and release information.

License

This library is licensed under Apache 2.0. See also the LICENSE file.

Gazebo Physics 8.x

Gazebo Physics 8.0.0 (2024-09-25)

  1. Baseline: this includes all changes from 7.3.0 and earlier.

  2. Miscellaneous documentation fixes

  3. Remove deprecated functions

  4. Enable 24.04 CI, require cmake 3.22.1

  5. bullet-featherstone: Support empty links

  6. Fix CTAD compile warnings

  7. bullet-featherstone: Enforce joint velocity and effort limits for velocity control commands

  8. Add Cone as a collision shape

  9. dartsim: optimize picking contact points with ODE collision detector

  10. Add no gravity link support

  11. bullet-featherstone: Support convex decomposition for meshes

  12. Find python directly instead of using GzPython

  13. Fix unused variable warning

  14. Support setting solver iterations

  15. Define GZ_PHYSICS_VERSION_NAMESPACE in config.hh

  16. Remove HIDE_SYMBOLS_BY_DEFAULT: replace by a default configuration in gz-cmake.

  17. Use HIDE_SYMBOLS_BY_DEFAULT

  18. Bump dependency versions: gz-cmake4, gz-common6, gz-math8, gz-plugin3, gz-utils3, sdformat15

  19. Bump major version to 8

Gazebo Physics 7.x

Gazebo Physics 7.3.0 (2024-06-25)

  1. Backport: Add Cone as a collision shape

  2. [featherstone] Publish JointFeedback forces.

  3. Parse voxel resolution when decomposing meshes

  4. bullet-featherstone: Fix attaching fixed joint between models with inertial pose offset

  5. Ray intersection simulation feature

  6. bullet-featherstone: Fix bounding box for collisions with pose offset

  7. bullet-featherstone: Update fixed constraint behavior

  8. Update InspectFeatures.hh

  9. bullet-featherstone: Fix convex hull shape’s AABB

  10. Add package.xml

  11. bullet-featurestore: Enable auto deactivation

  12. bullet-featherstone: Support convex decomposition for meshes

  13. backport bullet-featherstone solver iters

  14. bullet-featherstone: fix SetWorldPose with off-diagonal moment of inertia

  15. Revert “Disable check in DetachableJointTest, CorrectAttachmentPoints for dartsim plugin on macOS (#613)”

Gazebo Physics 7.2.0 (2024-04-10)

  1. Use relative install paths for plugin shared libraries

  2. Disable test failing due to ODE/libccd

  3. bullet-featherstone: Ignore collision between static objects and objects with world joint

  4. Disable check in DetachableJointTest, CorrectAttachmentPoints for dartsim plugin on macOS

  5. bullet-featherstone: Fix attaching fixed joint

Gazebo Physics 7.1.0 (2024-03-14)

  1. bullet-featherstone: Improve mesh collision stability

  2. bullet-featherstone: Support nested models

  3. Garden test cleanup

  4. Support setting max contacts in dartsim’s ODE collision detector

  5. Get bullet version from cmake instead of API

  6. Update CI badges in README

  7. Reduce error to debug messsage for mesh construction

  8. bullet-featherstone: Set collision spinning friction

  9. Infrastructure

  10. dartsim: fix handling inertia matrix pose rotation

  11. bullet-featherstone: fix setting angular velocity

  12. bullet-featherstone: support off-diagonal inertia

  13. bullet-featherstone: Fix how links are flattened in ConstructSdfModel

  14. Add sample ctest cmds to tutorial

  15. Add a test to verify behavior of detachable joints

  16. Use correct link indicies when constructing fixed constraints

Gazebo Physics 7.0.0 (2023-09-29)

  1. dartsim: Fix sign convention error with contact surface motion velocities

  2. Make dartsim/World.hh header private

  3. Documentation fixes

  4. Mimic constraint feature using bullet-featherstone

  5. ign -> gz

  6. Reduce error to debug messsage for mesh construction

  7. Infrastructure

  8. Bumps in harmonic : sdformat14

  9. EllipsoidShape: use const references in API

  10. Fixed Dartsim SDFFeatures_TEST

  11. ⬆️ Bump main to 7.0.0~pre1

Gazebo Physics 6.x

Gazebo Physics 6.6.0 (2024-06-11)

  1. dartsim: optimize picking contact points with ODE collision detector

  2. Fix windows compiler warning

  3. Disable test failing due to ODE/libccd

  4. bullet-featherstone: Improve mesh collision stability

  5. bullet-featherstone: Support nested models

  6. Revert “bazel: updates for garden (#513)”

  7. Garden test cleanup

  8. Support setting max contacts in dartsim’s ODE collision detector

  9. Get bullet version from cmake instead of API

  10. Reduce error to debug messsage for mesh construction (#581)

  11. bullet-featherstone: Set collision spinning friction

  12. Infrastructure

  13. dartsim: fix handling inertia matrix pose rotation

  14. bullet-featherstone: fix setting angular velocity

  15. bullet-featherstone: support off-diagonal inertia

  16. bullet-featherstone: Fix how links are flattened in ConstructSdfModel

  17. Add sample ctest cmds to tutorial

  18. Add a test to verify behavior of detachable joints

  19. Use correct link indicies when constructing fixed constraints

Gazebo Physics 6.5.1 (2023-09-26)

  1. joint_features test: reduce console spam

  2. Cleaning up bullet memory use issues

Gazebo Physics 6.5.0 (2023-08-30)

  1. Add optional binary relocatability

  2. Unregister collision detectors when the darstim plugin is unloaded

  3. Minor cleanup of dartsim

  4. Fix Github project automation for new project board

  5. Check that plugin exists before adding common test

  6. Clangtidy fixes

Gazebo Physics 6.4.0 (2023-05-22)

  1. dartsim: Add support for joints in worlds

  2. Changed contraint to constraint

  3. Bullet featherstone: Add JointTransmittedWrench for F-T sensor

  4. Reenable AABB tests for ellipsoids

  5. Fix bullet double to float conversion compiler warnings

  6. Disable failing bullet(-featherstone) tests on windows

  7. Support multiple collisions per link in bullet-featherstone

  8. Fix bullet related segfaults on macOS

  9. dartsim: Refactor entity addition logic in the EntityStorage class

  10. Fix a crash due to an invalid pointer

  11. Forward ports

Gazebo Physics 6.3.2 (2023-03-28)

  1. Fix joint index used in bookkeeping

  2. Move joint transmitted wrench test to separate file

Gazebo Physics 6.3.1 (2023-03-22)

  1. Rename COPYING to LICENSE

  2. Remove an extra symlink on all platforms

  3. Fix memory corruption due to faulty refcount tracking

  4. Infrastructure

  5. Forward Ports

Gazebo Physics 6.3.0 (2023-02-02)

  1. Fix windows warnings related to bullet

  2. ign -> gz : Remove redundant namespace references

  3. Resolve joints in nested models

  4. Apply gravity external to dartsim for added mass

  5. Refactor the VectorApprox to a single location

  6. Port: 5 to 6

  7. Simplify “falling” test to not require LinkFrameSemantics

  8. Install the common test executables to libexec

  9. [bullet]: Fix how changed link poses are computed

Gazebo Physics 6.2.0 (2022-11-28)

  1. Reduce error to debug and add notes

  2. Support fluid added mass

  3. Deduplicate common tests part1

Gazebo Physics 6.1.1 (2022-11-07)

  1. Suppress MSVC warning that is not applicable

  2. Fix construction of nested models

Gazebo Physics 6.1.0 (2022-10-27)

  1. Removed GetCollision API it’s redundant

  2. Add bullet-featherstone plugin

  3. Fix bullet cmake, probably bad merge

Gazebo Physics 6.0.0 (2022-09-21)

  1. Improved documentation and instructions

  2. Added common tests

  3. dartsim: fix handling inertia matrix pose rotation

  4. ABI tweaks to help bullet-featherstone

  5. Add code coverage ignore file

  6. Fix bullet classic entity management

  7. Ignition to Gazebo transition

  8. Fixed warning SDFfeatures_TEST - dartsim

  9. Update GoogleTest to latest version

  10. Use new Joint APIs for Parent/Child name

  11. Bullet: Added collision shape to Capsule and Ellipsoid

  12. examples: fix cmake find version variables

  13. Fix ExpectData compiler warnings

  14. Added DEM support to heightmaps

  15. Remove Bionic from future releases (Garden+)

Gazebo Physics 5.x

Gazebo Physics 5.3.2 (2023-09-01)

  1. Fix a crash due to an invalid pointer

  2. Infrastructure

  3. Rename COPYING to LICENSE

Gazebo Physics 5.3.1 (2023-02-16)

  1. Fix memory corruption due to faulty refcount tracking

Gazebo Physics 5.3.0 (2023-01-09)

  1. Fix windows warnings related to bullet

  2. Apply ign-gz after forward merge from ign-physics2

  3. Port: 2 to 5

  4. Fix build errors and warnings for DART 6.13.0

  5. Backport windows fix

  6. dartsim: fix handling inertia matrix pose rotation

  7. Add code coverage ignore file

  8. Change IGN_DESIGNATION to GZ_DESIGNATION

  9. README: Ignition -> Gazebo

Gazebo Physics 5.2.0 (2022-06-29)

  1. dartsim: support non-tree kinematics in AttachFixedJoint

  2. Use SuppressWarning from ign-utils

  3. Make CONFIG a CMake pass-through option for DART

  4. Remove explicitly-defined copy constructor/operator

  5. Fix ExpectData compiler warnings

  6. Fix copying of ExpectData objects

  7. Add Ubuntu Jammy CI

  8. Fix Apache license version

  9. Add project() to examples

Gazebo Physics 5.1.0 (2021-11-12)

  1. Remove unused gz_auto_headers.hh.in

  2. Added DART feature for setting joint limits dynamically.

  3. Allow customization of contact surface properties

  4. Avoid auto usage in Eigen expressions.

  5. Fix cmake script for bullet

  6. Improved README.md folder structure

Gazebo Physics 5.0.0 (2021-09-30)

  1. Add GetJointTransmittedWrench feature

  2. [dartsim] Add support for joint frame semantics

  3. Fix TPE Link velocity not being updated and Model velocity not having any effect.

  4. Make gz-physics CMake config files relocatable

  5. Added DART feature for setting joint limits dynamically.

  6. Remove use of deprecated function sdf::JointAxis::InitialPosition

  7. Clean up functions that trigger GCC9 warnings

  8. Forward merges

  9. Infrastructure

Gazebo Physics 4.x

Gazebo Physics 4.x.x (20XX-XX-XX)

Gazebo Physics 4.3.0 (2021-11-11)

  1. Remove unused gz_auto_headers.hh.in

  2. Added DART feature for setting joint limits dynamically.

  3. Allow customization of contact surface properties

  4. Avoid auto usage in Eigen expressions.

  5. [dartsim] Add support for joint frame semantics

  6. Fix TPE Link velocity not being updated and Model velocity not having any effect.

  7. Infrastructure

  8. Make gz-physics CMake config files relocatable

Gazebo Physics 4.2.0 (2021-07-16)

  1. Support FreeGroup features for nested models

  2. Add Gravity Feature, fix LinkFeatures_TEST

  3. Heightmaps 🏔️

  4. Added Ellipsoid and Capsule shapes to TPE

  5. Fix collision detection issue when using joints across nested models

  6. Use slip compliance APIs available in upstream dartsim release

  7. Fix DART deprecation warning

  8. Integrate Bullet engine

  9. Remove tools/code_check and update codecov

  10. [Citadel] Update tutorials

Gazebo Physics 4.1.0 (2021-05-01)

  1. [TPE] Update link pose and velocity

  2. Infrastructure

Gazebo Physics 4.0.0 (2021-03-30)

  1. Remove nested models

  2. Add dart-bullet dependency to CI

  3. [tpe] Add empty nested model construction and nested model entity management

  4. dartsim: fdir1 expressed_in frame from SDFormat

  5. Set collision detector and solver for DART

  6. Added ellipsoid and capsule to dartsim

  7. Add “ChangedWorldPose” to ForwardStep::Output’s expected data

  8. [dartsim] Add empty nested model construction and nested model entity management

  9. Rename CanonicalLink to RootLink

  10. write modified link data to output in physics step

  11. [dartsim] Ensure Link and Model APIs continue to work after joint creation in DART

  12. [dartsim] Fix joint construction errors due to link name duplication or BodyNodes moving to other skeletons

  13. Infrastructure

  14. Bump in edifice: gz-common4

  15. Constructing nested models for dartsim

  16. Depend on ignition-utils1 cli component

  17. Bump in edifice: sdformat11

  18. Documentation

Gazebo Physics 3.x

Gazebo Physics 3.x.x (20XX-XX-XX)

Gazebo Physics 3.3.0 (2021-07-12)

  1. Use slip compliance API’s available in upstream dartsim release

  2. Fix DART deprecation warning

  3. Integrate Bullet engine

  4. Remove tools/code_check and update codecov

  5. [Citadel] Update tutorials

Gazebo Physics 3.2.0 (2021-04-28)

  1. Infrastructure

  2. Linters

  3. Documentation

  4. Add Windows installation

  5. dartsim-plugin windows build fixes

  6. [TPE] Skip computing collisions for static objects

  7. [TPE] Update link pose and velocity

  8. [TPE] Fix poseDirty getter

  9. Add restitution coefficient support for bouncing

  10. Fix compilation with gcc 10.2.0

  11. Support setting canonical link

  12. Ignore invalid joint commands

  13. Fix CONFIG arg in gz_find_package(DART) call

Gazebo Physics 3.1.0 (2020-10-18)

  1. Support for slip compliance in the dartsim-plugin.

  2. Enforce joint effort limit in dartsim-plugin

  3. Support nested models in TPE

  4. Fix CONFIG arg in gz_find_package(DART) call

  5. Fix getting model bounding box in world frame in TPE

  6. Improve fork experience

Gazebo Physics 3.0.0 (2020-09-30)

  1. Upgrade to libsdformat10

  2. Update examples and tutorials

Gazebo Physics 2.x

Gazebo Physics 2.6.2 (2024-01-05)

  1. dartsim: fix handling inertia matrix pose rotation

  2. Fix a crash due to an invalid pointer

  3. Infrastructure

Gazebo Physics 2.6.1 (2023-01-09)

  1. Fix build errors and warnings for DART 6.13.0

  2. Don’t install CMakeLists.txt files

Gazebo Physics 2.6.0 (2022-11-30)

  1. Migrate Ignition headers

Gazebo Physics 2.5.1 (2022-08-16)

  1. Remove redundant namespace references

  2. Add code coverage ignore file

  3. Change IGN_DESIGNATION to GZ_DESIGNATION

  4. Ignition -> Gazebo

  5. Make CONFIG a CMake pass-through option for DART

  6. Remove explicitly-defined copy constructor/operator for Shape

  7. Fix ExpectData compiler warnings

  8. Fix copying of ExpectData objects

  9. Fix Apache license version

  10. Tutorial fixes

  11. Add project() to examples

Gazebo Physics 2.5.0 (2021-11-09)

  1. Remove unused gz_auto_headers.hh.in

  2. Added DART feature for setting joint limits dynamically.

  3. Allow customization of contact surface properties

  4. [dartsim] Add support for joint frame semantics

  5. Use slip compliance API’s available in upstream dartsim release

  6. Fix dart deprecation warning

  7. [Citadel] Update tutorials

  8. Infrastructure

Gazebo Physics 2.4.0 (2021-04-14)

  1. [TPE] Update link pose and velocity

  2. Infrastructure

  3. Documentation

  4. TPE: Skip computing collisions for static objects

  5. Add restitution coefficient support for bouncing

  6. Fix compilation with gcc 10.2.0

  7. Fix TPE poseDirty getter

  8. Support setting canonical link

  9. Resolved codecheck issues

  10. Ignore invalid joint commands

  11. Support getting shape AABB in world frame

  12. Fix CONFIG arg in gz_find_package(DART) call

Gazebo Physics 2.3.0 (2020-09-29)

  1. Support for slip compliance in the dartsim-plugin.

  2. Enforce joint effort limit in dartsim-plugin

  3. Support nested models in TPE

Gazebo Physics 2.2.0 (2020-07-30)

  1. Add Base and EntityManagement to tpeplugin

  2. Add all features to tpeplugin

  3. Fix TPE codecheck errors

  4. [TPE] Add function to get an Entity’s bounding box

  5. [TPE] Add collision detector

  6. [TPE] Add GetContactsFromLastStepFeature

  7. [TPE] Implement collision filtering using collide bitmasks and add CollisionFilterMaskFeature

  8. Fix copying SpecifyData objects

  9. Extend contact data with force, normal, and penetration depth

  10. Add offset to link and collision pose

  11. Add link offset to simulation

Gazebo Physics 2.1.0 (2020-05-07)

  1. Add RequestFeatures API for casting the features of an entity to a new feature set when possible.

  2. Add Get Bounding Box features

  3. Install plugins to unversioned files

  4. Add DetachJointFeature feature.

  5. Added support for collision bitmasks for collision filtering

  6. Clean up internal resources when a model gets removed

  7. Trivial Physics Engine - partial implementation

  8. Add simple example of physics plugin and loader

  9. Update BitBucket links, add .gitignore, CODEOWNERS, workflow

  10. Physics Plugin Documentation

  11. Reduce the symbol load caused by feature templates

  12. Fix collision issue with detachable joints

  13. Add PlaneShape feature and implement in dartsim with test.

  14. Restore detached BodyNodes to original skeleton

Gazebo Physics 2.0.0 (2019-12-10)

  1. Support compiling against dart 6.9.

  2. Support sdformat 1.7 frame semantics.

  3. Upgrade to libsdformat9

  4. Improve compile time by reducing length of symbol names

Gazebo Physics 1.x

Gazebo Physics 1.10.0 (2020-11-04)

  1. Resolved codecheck issues

  2. Ignore invalid joint commands in the dartsim-plugin

  3. Fix CONFIG arg in gz_find_package(DART) call

Gazebo Physics 1.9.0 (2020-09-17)

  1. Support for slip compliance in the dartsim-plugin.

  2. Enforce joint effort limit in dartsim-plugin

Gazebo Physics 1.8.0 (2020-05-08)

  1. Restore detached BodyNodes to original skeleton

  2. Fix collision issue with detachable joints

  3. Add PlaneShape feature and implement in dartsim with test.

Gazebo Physics 1.7.0 (2020-04-13)

  1. Add RequestFeatures API for casting the features of an entity to a new feature set when possible.

Gazebo Physics 1.6.0 (2020-03-18)

  1. Add Get Bounding Box features

  2. Install plugins to unversioned files

Gazebo Physics 1.5.0 (2020-02-10)

  1. Clean up internal resources when a model gets removed

  2. Add DetachJointFeature feature.

Gazebo Physics 1.4.0 (2019-08-27)

  1. Add SetJointVelocityCommand feature.

  2. Add IGN_PROFILER_ENABLE cmake option for enabling the gz-common profiler.

Gazebo Physics 1.3.1 (2019-07-19)

  1. Set the time step from ForwardStep::Input in dartsim.

Gazebo Physics 1.3.0 (2019-07-18)

  1. Support for more friction pyramid parameters in dartsim.

  2. Skip compilation of test plugins if BUILD_TESTING is false

Gazebo Physics 1.2.0 (2019-05-29)

  1. Change DART dependency to look for 6.9.0 instead of 6.7.2

Gazebo Physics 1.1.0 (2019-05-20)

  1. Simple port of existing PERFORMANCE test as BENCHMARK

  2. Add prototype of FreeGroup features

  3. Feature for adding external forces and torques to a link

  4. Assign friction coefficients from collision elements

  5. Added axis-aligned bounding box feature

  6. Add introduction and installation tutorials

  7. Remove workaround for console_bridge linking on macOS

Gazebo Physics 1.0.1 (2019-03-05)

  1. Don’t link core to ignition-common3, just the test plugin that uses it

Gazebo Physics 1.0.0 (2019-03-01)

  1. Initial release