From f9135f3466696cefb764f6e8054be410fac128f6 Mon Sep 17 00:00:00 2001 From: shameekganguly Date: Mon, 16 Sep 2024 04:03:34 -0700 Subject: [PATCH 1/5] Update readme (#688) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Shameek Ganguly Co-authored-by: Alejandro Hernández Cordero --- README.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b3e96fd53..21fae3ff6 100644 --- a/README.md +++ b/README.md @@ -79,27 +79,33 @@ Please refer to the [examples directory](https://github.com/gazebosim/gz-physics API and tutorials can be found at [https://gazebosim.org/libs/physics](https://gazebosim.org/libs/physics). -You can also generate the documentation from a clone of this repository by following these steps. +On Ubuntu, you can also generate the documentation from a clone of this repository by following these steps. -1. You will need Doxygen. On Ubuntu Doxygen can be installed using +1. You will need Doxygen, which can be installed using ``` sudo apt-get install doxygen ``` -2. Clone the repository +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 ``` -3. Configure and build the documentation. +4. Configure and build the documentation. ``` - cd gz-physics; mkdir build; cd build; cmake ../; make doc + cd gz-physics; mkdir build; cd build; cmake ..; make doc ``` -4. View the documentation by running the following command from the build directory. +5. View the documentation by running the following command from the build directory. ``` firefox doxygen/html/index.html @@ -109,7 +115,7 @@ You can also generate the documentation from a clone of this repository by follo Follow these steps to run tests and static code analysis in your clone of this repository. -1. Follow the [source install instruction](#source-install). +1. Follow the "Source Installation" instructions in the [installation tutorial](https://gazebosim.org/api/physics/8/installation.html). 2. Run tests. @@ -132,19 +138,21 @@ gz-physics ├── bullet Files for bullet plugin component. ├── bullet-featherstone Files for bullet-featherstone plugin component. ├── dartsim Files for dartsim plugin component. -├── example Examples about how to use the library +├── examples Examples about how to use the library. ├── heightmap Heightmap related header files. ├── include/gz/physics Header files. ├── mesh Files for mesh component. -├── resources Model and mesh resource files used by tests. ├── 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. @@ -164,7 +172,7 @@ Please see # Versioning -This library uses [Semantic Versioning](https://semver.org/). Additionally, this library is part of the [Gazebo project](https://gazebosim.org) which periodically releases a versioned set of compatible and complimentary libraries. See the [Gazebo website](https://gazebosim.org) for version and release information. +This library uses [Semantic Versioning](https://semver.org/). Additionally, this library is part of the [Gazebo project](https://gazebosim.org) which periodically releases a versioned set of compatible and complementary libraries. See the [Gazebo website](https://gazebosim.org) for version and release information. # License From 902824b2549f425b7dea5ada6b362be31664faa7 Mon Sep 17 00:00:00 2001 From: Martin Pecka Date: Mon, 16 Sep 2024 16:40:32 +0200 Subject: [PATCH 2/5] tutorials/08-implementing-a-custom-feature: Fixed paths and directory listings (#690) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Martin Pecka Co-authored-by: Alejandro Hernández Cordero --- tutorials/08-implementing-a-custom-feature.md | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/tutorials/08-implementing-a-custom-feature.md b/tutorials/08-implementing-a-custom-feature.md index 7db6fd8ea..8cf3e5464 100644 --- a/tutorials/08-implementing-a-custom-feature.md +++ b/tutorials/08-implementing-a-custom-feature.md @@ -49,14 +49,13 @@ Looking closer to a plugin folder, for example, the `dartsim` (DART) plugin: dartsim ├── worlds Example SDF files for testing dartsim plugin functionalities. ├── src Main implementation files of the plugin features interfacing the physics engines API -├── include/gz/physics/dartsim Header files for the plugin features. └── CMakeLists.txt CMake plugin build script. ``` Basically, new implementation of \ref gz::physics::Feature "Feature" or \ref gz::physics::FeatureList "FeatureList", which is corresponded to a functionality of the external physics engine can be defined as a header in -`include/gz/physics/` folder. The custom feature could +`src` folder. The custom feature could be added in a \ref gz::physics::FeatureList "FeatureList" and implemented its functionalities in `src` folder. @@ -82,7 +81,7 @@ downstream physics plugins. For custom feature requirements, there are two main component classes in the general structure of a custom feature: -- \ref gz::physics::Entity "Entity" corresponds to the "proxy object" that +- \ref gz::physics::Entity "Entity" corresponds to the "proxy object" where the \ref gz::physics::Feature "Feature" is implemented. These are the most common "proxy objects" that are inherited from `Entity` class: - \ref gz::physics::Feature::Engine "Engine": Placeholder class for the @@ -134,9 +133,9 @@ will not run at the same time when requested. ### Define custom feature template -With the requirements and restrictions above, we first need to define a feature template for the custom feature. In this case, this feature will be responsible for retrieving world pointer from the physics engine. The template is placed in [World.hh](https://github.com/gazebosim/gz-physics/blob/main/dartsim/include/gz/physics/dartsim/World.hh): +With the requirements and restrictions above, we first need to define a feature template for the custom feature. In this case, this feature will be responsible for retrieving world pointer from the physics engine. The template is placed in [World.hh](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/World.hh): -\snippet dartsim/include/gz/physics/dartsim/World.hh feature template +\snippet dartsim/src/World.hh feature template The `RetrieveWorld` feature retrieves world pointer from physics engine, so we will use the `World` entity inherited @@ -159,9 +158,8 @@ dartsim ├── src │ ├── CustomFeatures.hh │ ├── CustomFeatures.cc +| ├── World.hh │ └── ... -├── include/gz/physics/dartsim -│ └── World.hh └── CMakeLists.txt ``` @@ -178,24 +176,24 @@ After defining the feature template, we can add it to a custom The custom feature `RetrieveWorld` is added to `CustomFeatureList`, other custom features could also be added here. The `CustomFeatures` "FeatureList" here uses data structures and classes from: -- [Base.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/Base.hh), which defines structures that contain information to create `Model`, `Joint`, `Link`, and `Shape` objects in Dartsim API. +- [Base.hh](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/Base.hh), which defines structures that contain information to create `Model`, `Joint`, `Link`, and `Shape` objects in Dartsim API. They act as an interface between Gazebo Physics Library and the actual physics engine. - \ref gz::physics::Implements3d "Implements3d" for implementing the custom feature with \ref gz::physics::FeaturePolicy3d "FeaturePolicy3d" ("FeaturePolicy" of 3 dimensions and scalar type `double`). -We will then implement the actual function with Dartsim API in [CustomFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/CustomFeatures.cc) to override the member function +We will then implement the actual function with Dartsim API in [CustomFeatures.cc](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/CustomFeatures.cc) to override the member function declared in the custom feature header file: \snippet dartsim/src/CustomFeatures.cc implementation Here, we implement the behavior of `GetDartsimWorld` with Dartsim API to return the world pointer from `EntityStorage` object storing world pointers of `dartsim` in -[Base](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/Base.hh) class. +[Base](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/Base.hh) class. In the end, we add the implemented `CustomFeatures` "FeatureList" together with other \ref gz::physics::FeatureList "FeatureList" to final `DartsimFeatures` -"FeatureList" as in [dartsim/src/plugin.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/plugin.cc) +"FeatureList" as in [dartsim/src/plugin.cc](https://github.com/gazebosim/gz-physics/blob/gz-physics8/dartsim/src/plugin.cc) (please see the \ref createphysicsplugin "Implement a physics feature" tutorial for registering the plugin to Gazebo Physics). @@ -208,6 +206,5 @@ dartsim │ ├── CustomFeatures.hh │ ├── CustomFeatures.cc │ ├── ... -├── include/gz/physics/dartsim └── CMakeLists.txt ``` From 615afd9b5c2c52120a144773a6f8ddb781a8d7b6 Mon Sep 17 00:00:00 2001 From: Martin Pecka Date: Tue, 17 Sep 2024 00:18:24 +0200 Subject: [PATCH 3/5] tutorials/09_use_custom_engine: Add actual build and run instructions (#689) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Martin Pecka Co-authored-by: Alejandro Hernández Cordero Co-authored-by: Ian Chen --- tutorials/09_use_custom_engine.md | 57 +++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/tutorials/09_use_custom_engine.md b/tutorials/09_use_custom_engine.md index 136804745..572728997 100644 --- a/tutorials/09_use_custom_engine.md +++ b/tutorials/09_use_custom_engine.md @@ -158,13 +158,56 @@ While we won't go into detail, here is an example to test our new To get a more comprehensive view of how `EntityManagementFeatures` are constructed in TPE and Dartsim, feel free to take a look here: -- Dartsim: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/dartsim/src/EntityManagementFeatures.cc) -- TPE: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/ign-physics2/tpe/plugin/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/ign-physics2/tpe/plugin/src/EntityManagementFeatures.cc) +- Dartsim: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/main/dartsim/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/main/dartsim/src/EntityManagementFeatures.cc) +- TPE: [EntityManagementFeatures.hh](https://github.com/gazebosim/gz-physics/blob/main/tpe/plugin/src/EntityManagementFeatures.hh) and [EntityManagementFeatures.cc](https://github.com/gazebosim/gz-physics/blob/main/tpe/plugin/src/EntityManagementFeatures.cc) + +## Compile and run the example + +Clone the source code, create a build directory and use `cmake` to compile the code: + +```bash +git clone https://github.com/gazebosim/gz-physics +cd gz-physics/examples/simple_plugin +mkdir build +cd build +cmake .. +# Linux +cmake --build . --target PluginTest +# Windows +cmake --build . --target PluginTest --config Release +``` + +Run the test to verify the new physis plugin: + +```bash +# Linux +./PluginTest + +# Windows +.\Release\PluginTest.exe +``` + +You'll see: + +```bash +$ ./PluginTest +Created empty world! +``` + +Once you implement more features, you could try passing `SimplePlugin` as the physics engine +to Gazebo Sim following \ref physicsengine "Use different physics engines" tutorial, e.g. setting + + # Linux + export GZ_SIM_PHYSICS_ENGINE_PATH=$GZ_SIM_PHYSICS_ENGINE_PATH:$(pwd)/build + # Windows + set GZ_SIM_PHYSICS_ENGINE_PATH=\build\Release + +And run Gazebo sim with -## Load and test + gz sim -v4 -s --physics-engine SimplePlugin -Please follow the previous tutorial \ref installation "Installation" to build -`gz-physics` from source again for our new feature to be compiled. +However, with the poor one feature we have implemented in this tutorial, you will only see an error, +because Gazebo Sim needs much more features: -Now we can load the new physics plugin named `gz-physics-tpe-plugin` -to test it on Gazebo by following this \ref physicsengine "Use different physics engines" tutorial. + [error] [Physics.cc:854] No physics plugins implementing required interface found in library + [D:\programming\gz9-ws\gz-ws\src\gz-physics\examples\simple_plugin\build\Release\SimplePlugin.dll]. From 6afc9a7ce615d6eba704b4d034b95d1e7c716d95 Mon Sep 17 00:00:00 2001 From: Ian Chen Date: Mon, 16 Sep 2024 18:48:51 -0700 Subject: [PATCH 4/5] Update instructions for homebrew installation (#691) Signed-off-by: Ian Chen --- tutorials/02_installation.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 91a80d638..c1da08359 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -83,11 +83,8 @@ system requirements. ## Binary Installation -1. Install Homebrew, which should also prompt you to install the XCode -command-line tools: - ``` - ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - ``` +1. Install [Homebrew](https://brew.sh/), which should also prompt you to install the XCode +command-line tools. 2. Run the following commands ``` From 8e28e941d71c9214c89d14658cbf219ef324e0a7 Mon Sep 17 00:00:00 2001 From: "Addisu Z. Taddese" Date: Thu, 26 Sep 2024 17:26:31 -0500 Subject: [PATCH 5/5] Prepare for 8.0.0 (#693) Signed-off-by: Addisu Z. Taddese --- CMakeLists.txt | 2 +- Changelog.md | 13 ++++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 033d629c2..b16b4dd17 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -16,7 +16,7 @@ find_package(gz-cmake4 REQUIRED) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) -gz_configure_project(VERSION_SUFFIX pre2) +gz_configure_project(VERSION_SUFFIX) #============================================================================ # Set project-specific options diff --git a/Changelog.md b/Changelog.md index c904bd290..c6ee05876 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,9 +1,20 @@ ## Gazebo Physics 8.x -### Gazebo Physics 8.0.0 (2024-09-XX) +### Gazebo Physics 8.0.0 (2024-09-25) 1. **Baseline:** this includes all changes from 7.3.0 and earlier. +1. Miscellaneous documentation fixes + * [Pull request #691](https://github.com/gazebosim/gz-physics/pull/691) + * [Pull request #689](https://github.com/gazebosim/gz-physics/pull/689) + * [Pull request #690](https://github.com/gazebosim/gz-physics/pull/690) + * [Pull request #688](https://github.com/gazebosim/gz-physics/pull/688) + * [Pull request #686](https://github.com/gazebosim/gz-physics/pull/686) + * [Pull request #684](https://github.com/gazebosim/gz-physics/pull/684) + * [Pull request #683](https://github.com/gazebosim/gz-physics/pull/683) + * [Pull request #682](https://github.com/gazebosim/gz-physics/pull/682) + * [Pull request #681](https://github.com/gazebosim/gz-physics/pull/681) + 1. Remove deprecated functions * [Pull request #673](https://github.com/gazebosim/gz-physics/pull/673)