From 68860f15a380032e549c54c704bbbac4c8876662 Mon Sep 17 00:00:00 2001 From: methylDragon Date: Mon, 27 Jun 2022 16:26:41 -0700 Subject: [PATCH 1/7] Migrate some docs and project names in macros Signed-off-by: methylDragon --- README.md | 4 ++-- api.md.in | 4 ++-- examples/hello_world_loader/CMakeLists.txt | 2 +- examples/hello_world_loader/README.md | 2 +- examples/hello_world_plugin/CMakeLists.txt | 2 +- examples/hello_world_plugin/README.md | 2 +- examples/simple_plugin/CMakeLists.txt | 2 +- tutorials.md.in | 4 ++-- tutorials/01_intro.md | 16 +++++++-------- tutorials/02_installation.md | 20 +++++++++---------- tutorials/03_physics_plugins.md | 8 ++++---- tutorials/05_plugin_loading.md | 4 ++-- tutorials/06-physics-simulation-concepts.md | 5 ++--- tutorials/07-implementing-a-physics-plugin.md | 2 +- tutorials/08-implementing-a-custom-feature.md | 6 +++--- tutorials/09-set-up-physics-engine-tpe.md | 8 ++++---- tutorials/09_use_custom_engine.md | 4 ++-- 17 files changed, 47 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 336e0dadd..8d01d04a8 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Ubuntu Focal | [![Build Status](https://build.osrfoundation.org/buildStatus/icon Homebrew | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=ignition_physics-ci-ign-physics6-homebrew-amd64)](https://build.osrfoundation.org/job/ignition_physics-ci-ign-physics6-homebrew-amd64) Windows | [![Build Status](https://build.osrfoundation.org/buildStatus/icon?job=ign_physics-ci-win)](https://build.osrfoundation.org/job/ign_physics-ci-win) -Gazebo Physics, a component of [Ignition +Gazebo Physics, a component of [Gazebo Robotics](https://gazebosim.org), provides an abstract physics interface designed to support simulation and rapid development of robot applications. @@ -97,7 +97,7 @@ You can also generate the documentation from a clone of this repository by follo 3. Configure and build the documentation. ``` - cd ign-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. diff --git a/api.md.in b/api.md.in index 4767d0b6d..9bf3d8a27 100644 --- a/api.md.in +++ b/api.md.in @@ -1,6 +1,6 @@ -## Ignition @IGN_DESIGNATION_CAP@ +## Gazebo @IGN_DESIGNATION_CAP@ -Ignition @IGN_DESIGNATION_CAP@ is a component in Gazebo, a set of libraries +Gazebo @IGN_DESIGNATION_CAP@ is a component in Gazebo, a set of libraries designed to rapidly develop robot and simulation applications. ## License diff --git a/examples/hello_world_loader/CMakeLists.txt b/examples/hello_world_loader/CMakeLists.txt index 68c6bb885..b3f13316f 100644 --- a/examples/hello_world_loader/CMakeLists.txt +++ b/examples/hello_world_loader/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.5 FATAL_ERROR) -project(ign-physics-hello-world-loader) +project(gz-physics-hello-world-loader) find_package(gz-plugin2 REQUIRED COMPONENTS all) set(GZ_PLUGIN_VER ${gz-plugin2_VERSION_MAJOR}) diff --git a/examples/hello_world_loader/README.md b/examples/hello_world_loader/README.md index 8f7821497..d6bb2e719 100644 --- a/examples/hello_world_loader/README.md +++ b/examples/hello_world_loader/README.md @@ -5,7 +5,7 @@ plugins, according to a desired feature list. ## Build -From the root of the `ign-physics` repository, do the following to build the example: +From the root of the `gz-physics` repository, do the following to build the example: ```bash cd examples/hello_world_loader diff --git a/examples/hello_world_plugin/CMakeLists.txt b/examples/hello_world_plugin/CMakeLists.txt index 2a3b8db88..c5e5a698e 100644 --- a/examples/hello_world_plugin/CMakeLists.txt +++ b/examples/hello_world_plugin/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.5 FATAL_ERROR) -project(ign-physics-hello-world-plugin) +project(gz-physics-hello-world-plugin) find_package(gz-plugin2 REQUIRED COMPONENTS all) set(GZ_PLUGIN_VER ${gz-plugin2_VERSION_MAJOR}) diff --git a/examples/hello_world_plugin/README.md b/examples/hello_world_plugin/README.md index 0eda5ffb7..a07667b18 100644 --- a/examples/hello_world_plugin/README.md +++ b/examples/hello_world_plugin/README.md @@ -5,7 +5,7 @@ Gazebo Physics. ## Build -From the root of the `ign-physics` repository, do the following to build the example: +From the root of the `gz-physics` repository, do the following to build the example: ```bash cd examples/hello_world_plugin diff --git a/examples/simple_plugin/CMakeLists.txt b/examples/simple_plugin/CMakeLists.txt index dea8201de..ca331adbe 100644 --- a/examples/simple_plugin/CMakeLists.txt +++ b/examples/simple_plugin/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.5 FATAL_ERROR) -project(ign-physics-simple-plugin) +project(gz-physics-simple-plugin) find_package(gz-plugin2 REQUIRED COMPONENTS all) set(GZ_PLUGIN_VER ${gz-plugin2_VERSION_MAJOR}) diff --git a/tutorials.md.in b/tutorials.md.in index 9ed945793..e69f8c3a0 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -1,8 +1,8 @@ \page tutorials Tutorials -Welcome to the Ignition @IGN_DESIGNATION_CAP@ tutorials. These tutorials +Welcome to the Gazebo @IGN_DESIGNATION_CAP@ tutorials. These tutorials will guide you through the process of understanding the capabilities of the -Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively. +Gazebo @IGN_DESIGNATION_CAP@ library and how to use the library effectively. **Contents** diff --git a/tutorials/01_intro.md b/tutorials/01_intro.md index 3202bcc57..425f31571 100644 --- a/tutorials/01_intro.md +++ b/tutorials/01_intro.md @@ -4,7 +4,7 @@ Next Tutorial: \ref installation ## Motivation -Gazebo Physics (`ign-physics`) is a library component in Ignition, a set of +Gazebo Physics (`gz-physics`) is a library component in Gazebo, a set of libraries designed to rapidly develop robot and simulation applications. The main goal of the library is to provide an abstraction layer to various physics engines, which gives end-users the ability to use multiple @@ -17,18 +17,18 @@ Gazebo Physics extensibility and modularity. ## Overview -For a big picture of the Gazebo Physics operation in Ignition ecosystem, see +For a big picture of the Gazebo Physics operation in Gazebo ecosystem, see the abstract diagram below: @image html img/ign-libraries.png -In general, `ign-gazebo` is the main simulation library, in which its +In general, `gz-sim` is the main simulation library, in which its functionalities are powered by many component libraries. -For example, its graphical drawing is supported by `ign-rendering` or simulated -sensors that are defined and implemented in `ign-sensors`. -In particular, this library `ign-physics` provides an abstract interface to +For example, its graphical drawing is supported by `gz-rendering` or simulated +sensors that are defined and implemented in `gz-sensors`. +In particular, this library `gz-physics` provides an abstract interface to physics engines, which simulates dynamic transformations and interactions of -objects in `ign-gazebo`. The libraries are connected by C++ code. +objects in `gz-sim`. The libraries are connected by C++ code. Gazebo Physics uses a plugin architecture where each physics engine is implemented as a plugin that can be loaded at runtime. @@ -82,5 +82,5 @@ to \ref physicsplugin ### Future roadmap -Gazebo Physics evolves closely with the Ignition ecosystem. +Gazebo Physics evolves closely with the Gazebo ecosystem. For a broader overview, please visit [Gazebo's roadmap](https://gazebosim.org/about). diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index e4510460f..478ce2d55 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -1,7 +1,7 @@ \page installation Installation These instructions are for installing only Gazebo Physics. -If you're interested in using all the Ignition libraries, check out this [Ignition installation](https://gazebosim.org/docs/dome/install). +If you're interested in using all the Gazebo libraries, check out this [Gazebo installation](https://gazebosim.org/docs/dome/install). We recommend following the Binary Installation instructions to get up and running as quickly and painlessly as possible. @@ -32,7 +32,7 @@ wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - ## Binary Installation -On Ubuntu systems, `apt-get` can be used to install `ignition-plugin`: +On Ubuntu systems, `apt-get` can be used to install `gz-plugin`: ``` sudo apt-get update sudo apt-get install libignition-physics<#>-dev @@ -56,7 +56,7 @@ Be sure to replace `<#>` with a number value, such as `1` or `2`, depending on w 3. Configure and build ``` - cd ign-physics + cd gz-physics mkdir build cd build cmake .. @@ -110,7 +110,7 @@ Be sure to replace `<#>` with a number value, such as `1` or `2`, depending on w 3. Configure and build ``` - cd ign-physics + cd gz-physics mkdir build cd build cmake .. @@ -129,14 +129,14 @@ Only [Trivial Physics Engine (TPE)](https://community.gazebosim.org/t/announcing ## Prerequisites -First, follow the [ign-cmake](https://github.com/gazebosim/gz-cmake) tutorial for installing Conda, Visual Studio, CMake, and other prerequisites, and also for creating a Conda environment. +First, follow the [gz-cmake](https://github.com/gazebosim/gz-cmake) tutorial for installing Conda, Visual Studio, CMake, and other prerequisites, and also for creating a Conda environment. Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). Create if necessary, and activate a Conda environment: ``` -conda create -n ign-ws -conda activate ign-ws +conda create -n gz-ws +conda activate gz-ws ``` ## Binary Installation @@ -152,7 +152,7 @@ which version you need. This assumes you have created and activated a Conda environment while installing the Prerequisites. -1. Install Ignition dependencies: +1. Install Gazebo dependencies: You can view available versions and their dependencies: ``` @@ -172,7 +172,7 @@ This assumes you have created and activated a Conda environment while installing 3. Configure and build ``` - cd ign-physics + cd gz-physics mkdir build cd build cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install @@ -202,7 +202,7 @@ You can also generate the documentation from a clone of this repository by follo 3. Configure and build the documentation. ``` - cd ign-physics + cd gz-physics mkdir build cd build cmake .. diff --git a/tutorials/03_physics_plugins.md b/tutorials/03_physics_plugins.md index b580652d3..1e2017b79 100644 --- a/tutorials/03_physics_plugins.md +++ b/tutorials/03_physics_plugins.md @@ -9,7 +9,7 @@ It allows users to select from multiple supported physics engines based on their Its plugin interface loads physics engines with requested features at runtime. It is also possible to integrate your own selected physics engine by writing a compatible plugin interface. -To get a more in-depth understanding of how the physics plugin works in Ignition, we will start with some high level concepts and definitions. +To get a more in-depth understanding of how the physics plugin works in Gazebo, we will start with some high level concepts and definitions. @@ -19,7 +19,7 @@ Conceptually, the physics plugin can be viewed from two sides of its interface: Each physics engine provides access to different features implemented by the Gazebo Physics engine. The interface is made possible through the \ref gz::plugin "Gazebo Plugin" library, which instantiates \ref gz::physics::Feature "Features" in \ref gz::physics::FeatureList "FeatureLists" and supplies pointers to the selected engine. -This "user side interface" makes the Gazebo Physics library "callable" from other Ignition libraries. +This "user side interface" makes the Gazebo Physics library "callable" from other Gazebo libraries. The implementation side interface handles specific implementations of each `Feature`. Depending on what external physics engine we are using (DART, TPE etc.), the interface might be different. @@ -44,7 +44,7 @@ The implementation of the physics plugin revolves around four key elements. This class defines the concept of a `Feature`, examples like `GetWorldFromEngine`, \ref gz::physics::GetEngineInfo "GetEngineInfo" etc. There is a pre-defined list of features in Gazebo Physics. - They are implemented by using external physics engines' APIs to fulfill simulation needs requested by Ignition. + They are implemented by using external physics engines' APIs to fulfill simulation needs requested by Gazebo. 4. \ref gz::physics::FeatureList "FeatureList" @@ -82,7 +82,7 @@ The source code for Dartsim plugin can be found in [Gazebo Physics repository](h TPE ([Trivial Physics Engine](https://github.com/gazebosim/gz-physics/tree/ign-physics6/tpe)) is an open source library created by Open Robotics that enables fast, inexpensive kinematics simulation for entities at large scale. It supports higher-order fleet dynamics without real physics (eg. gravity, force, constraint etc.) and multi-machine synchronization. -Ignition support for TPE targets [Citadel](https://gazebosim.org/docs/citadel) and onward releases. +Gazebo support for TPE targets [Citadel](https://gazebosim.org/docs/citadel) and onward releases. The source code for TPE plugin can be found in [Gazebo Physics repository](https://github.com/gazebosim/gz-physics/tree/ign-physics6) under the `tpe/plugin` directory. The following is a list of features supported by each physics engine to help users select one that fits their needs. diff --git a/tutorials/05_plugin_loading.md b/tutorials/05_plugin_loading.md index 76e99f3ab..c956b0683 100644 --- a/tutorials/05_plugin_loading.md +++ b/tutorials/05_plugin_loading.md @@ -17,7 +17,7 @@ plugin using \ref gz::physics "Gazebo Physics" API. ## Write a simple loader -We will use a simplified physics plugin example for this tutorial. Source code can be found at [ign-physics/examples](https://github.com/gazebosim/gz-physics/tree/main/examples/hello_world_loader) folder. +We will use a simplified physics plugin example for this tutorial. Source code can be found at [gz-physics/examples](https://github.com/gazebosim/gz-physics/tree/main/examples/hello_world_loader) folder. First, create a workspace for the example plugin loader. @@ -62,7 +62,7 @@ engine implementing a \ref gz::physics::FeaturePolicy "FeaturePolicy" (3D ### Setup CMakeLists.txt for CMake build Now create a file named `CMakeLists.txt` with your favorite editor and add these -lines for finding `ign-plugin` and `ign-physics` dependencies in Citadel release. +lines for finding `gz-plugin` and `gz-physics` dependencies in Citadel release. After that, add the executable pointing to our file and add linking library so that `cmake` can compile it. diff --git a/tutorials/06-physics-simulation-concepts.md b/tutorials/06-physics-simulation-concepts.md index eee12aa86..4eed92f00 100644 --- a/tutorials/06-physics-simulation-concepts.md +++ b/tutorials/06-physics-simulation-concepts.md @@ -16,7 +16,7 @@ Here is a snapshot of simulation features supported by ign-physics: - Kinematics; joint, arbitrary body shapes, various kinematic states like transmoration, velocity, acceleration etc., inverse kinematics - Dynamics: joint constraints, mass matrix, gravity, forces and frictions, closed-loop structures -Ignition adopts SDFormat structure to describe visual elements and +Gazebo adopts SDFormat structure to describe visual elements and also the dynamic physics aspects. To get started on SDFormat 1.7, refer to this [SDFormat specification](http://sdformat.org/spec?ver=1.7&elem=sdf). For a comprehensive tutorial for constructing your robot model from SDFormat, refer to this [Building robot](https://gazebosim.org/docs/fortress/building_robot) tutorial. @@ -26,7 +26,7 @@ For a comprehensive tutorial for constructing your robot model from SDFormat, re In this tutorial, we will show how to manipulate and visualize some physics aspects using demos on Gazebo. -All demos can be found in [ign-gazebo/examples/worlds](https://github.com/gazebosim/gz-sim/blob/main/examples/worlds/) folder. +All demos can be found in [gz-sim/examples/worlds](https://github.com/gazebosim/gz-sim/blob/main/examples/worlds/) folder. ### Differential drive @@ -225,4 +225,3 @@ both of the multicopters will ascend, this demonstrates how the physics engine utilizes model kinematics and dynamics to support simulating complex model and its controller. For more details about the multicopter controller, please see [MulticopterVelocityControl.cc](https://github.com/gazebosim/gz-sim/blob/main/src/systems/multicopter_control/MulticopterVelocityControl.cc). - diff --git a/tutorials/07-implementing-a-physics-plugin.md b/tutorials/07-implementing-a-physics-plugin.md index ed34ffdec..35f888004 100644 --- a/tutorials/07-implementing-a-physics-plugin.md +++ b/tutorials/07-implementing-a-physics-plugin.md @@ -74,7 +74,7 @@ plugin provides, i.e. `HelloWorldFeatureList` ### Setup CMakeLists.txt for building (Version: ign-physics6) Now create a file named `CMakeLists.txt` with your favorite editor and add these -lines for finding `ign-plugin` and `ign-physics` dependencies for the Fortress release: +lines for finding `gz-plugin` and `gz-physics` dependencies for the Fortress release: \include examples/hello_world_plugin/CMakeLists.txt diff --git a/tutorials/08-implementing-a-custom-feature.md b/tutorials/08-implementing-a-custom-feature.md index 185bb81ee..e4968ef16 100644 --- a/tutorials/08-implementing-a-custom-feature.md +++ b/tutorials/08-implementing-a-custom-feature.md @@ -14,12 +14,12 @@ know how to implement a dummy physics engine as a plugin and load it using \ref gz::physics "Gazebo Physics API". In this tutorial, we will look deeper into the structure of a physics engine plugin, for example, the available [DART](https://github.com/gazebosim/gz-physics/tree/main/dartsim) -physics engine in `ign-physics` repository and how to define a custom +physics engine in `gz-physics` repository and how to define a custom \ref gz::physics::Feature "Feature" for the plugin. ### Folder structure of the plugins -Below is the general structure of the `ign-physics` repository: +Below is the general structure of the `gz-physics` repository: ``` ign-physics @@ -41,7 +41,7 @@ As shown above, there are two physics engines available: - **DART**: `gz-physics-dartsim-plugin`. - **TPE**: `gz-physics-tpe-plugin`. -and their plugin folders are placed just below the top level of `ign-physics`. +and their plugin folders are placed just below the top level of `gz-physics`. Looking closer to a plugin folder, for example, the `dartsim` (DART) plugin: diff --git a/tutorials/09-set-up-physics-engine-tpe.md b/tutorials/09-set-up-physics-engine-tpe.md index fc033a3ba..16e9d3d17 100644 --- a/tutorials/09-set-up-physics-engine-tpe.md +++ b/tutorials/09-set-up-physics-engine-tpe.md @@ -3,7 +3,7 @@ ## Prerequisites In the previous tutorial \ref installation "Installation", you have installed -the Gazebo Physics corresponding to the desired Ignition release. +the Gazebo Physics corresponding to the desired Gazebo release. ## How to adapt a physics engine as a plugin in Gazebo Physics @@ -20,7 +20,7 @@ as an example for this tutorial. ### General structure of a physics plugin As described in \ref createcustomfeature "Implement a custom feature" tutorial, -the plugin folder is placed just below the top-level folder of `ign-physics`. +the plugin folder is placed just below the top-level folder of `gz-physics`. In general, any physics plugin folder will have the following structure, which is commented in detail: @@ -202,7 +202,7 @@ class for foundation metadata definitions of Models, Joints, Links, and Shapes o of TPE to provide easy access to [tpelib](https://github.com/gazebosim/gz-physics/tree/main/tpe/lib) structures in the TPE library. Note that we mention `Base` class here for completeness, `Base` class is not necessarily needed if there is a straightforward -way to interface external physics engine class objects with `ign-physics` class objects. +way to interface external physics engine class objects with `gz-physics` class objects. - \ref gz::physics::Implements3d "Implements3d" for implementing the custom feature with \ref gz::physics::FeaturePolicy3d "FeaturePolicy3d" ("FeaturePolicy" of 3 dimensions and scalar type `double`). @@ -276,7 +276,7 @@ for more comprehensive unit tests. ## Build the custom physics plugin Please follow the previous tutorial \ref installation "Installation" to build -`ign-physics` from source again for our new feature to be compiled. +`gz-physics` from source again for our new feature to be compiled. Now we can load the new physics plugin named `gz-physics-tpe-plugin` to test it on Gazebo by following this \ref switchphysicsengines "Switching physics engines" tutorial. diff --git a/tutorials/09_use_custom_engine.md b/tutorials/09_use_custom_engine.md index f44aeeecf..900b5ed07 100644 --- a/tutorials/09_use_custom_engine.md +++ b/tutorials/09_use_custom_engine.md @@ -103,7 +103,7 @@ in `EntityManagementFeatures` "FeatureList" using TPE API from `tpe/lib` in Gaze Before we dive into the feature implementation, we need to understand how the features are defined. The \ref gz::physics::ConstructEmptyWorldFeature "ConstructEmptyWorldFeature" -is declared in a function template file `ign-physics/include/ignition/physics/ConstructEmpty.hh`. +is declared in a function template file `gz-physics/include/ignition/physics/ConstructEmpty.hh`. Gazebo Physics library uses function templates to specify features that accept generic types. The use of templates makes it easier to implement features using different physics engine APIs, @@ -162,7 +162,7 @@ feel free to take a look here: ## Load and test Please follow the previous tutorial \ref installation "Installation" to build -`ign-physics` from source again for our new feature to be compiled. +`gz-physics` from source again for our new feature to be compiled. 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. From 333f0cfda728fbc37dd128f3b579de2c5103f98e Mon Sep 17 00:00:00 2001 From: methylDragon Date: Mon, 27 Jun 2022 16:38:23 -0700 Subject: [PATCH 2/7] Add project name migration note in Migration.md Signed-off-by: methylDragon --- Migration.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Migration.md b/Migration.md index 5a6bb2ff2..68fd79fb0 100644 --- a/Migration.md +++ b/Migration.md @@ -7,7 +7,7 @@ release will remove the deprecated code. ## Gazebo Physics 5.X to 6.X -### Deprecation +### Deprecations 1. The `ignition` namespace is deprecated and will be removed in future versions. Use `gz` instead. @@ -27,6 +27,14 @@ release will remove the deprecated code. 1. `IGNITION_UNITTEST_EXPECTDATA_ACCESS` (hard-tocked, inside test and detail headers) 1. `IGNITION_PHYSICS_DEFINE_COORDINATE_SPACE` (hard-tocked, inside detail header) +### Breaking Changes + +* The project name has been changed to use the `gz-` prefix, you **must** use the `gz` prefix! + * This also means that any generated code that use the project name (e.g. CMake variables, in-source macros) would have to be migrated. + * Some non-exhaustive examples of this include: + * `GZ__