Merge branch 'gz-sim9' into Amal-python-system-GIL

README.md

@@ -106,7 +106,13 @@ where the YAML files for the packages are found, such as
 export GZ_CONFIG_PATH=/usr/local/share/gz:$HOME/ws/install/share/gz
 ```
 
-where `$HOME/ws` is an example colcon workspace used to build Gazebo
+where `$HOME/ws` is an example colcon workspace used to build Gazebo.
+
+On Windows, `gz sim` (i.e. running both server and GUI in one command) doesn't yet work.
+To run Gazebo Sim on Windows, you need to run the server in one terminal (`gz sim -s <other args>`)
+and the GUI in another terminal (`gz sim -g <other args>`). Remember this when reading through
+all Gazebo Sim tutorials. Also remember that Conda and `install\setup.bat` need to be sourced
+in both terminals (as well as any changes to `GZ_PARTITION` and other environment variables).
 
 # Documentation
 
@@ -116,7 +122,7 @@ See the [installation tutorial](https://gazebosim.org/api/sim/9/install.html).
 
 See the [installation tutorial](https://gazebosim.org/api/sim/9/install.html).
 
-See the [Writing Tests section of the contributor guide](https://github.com/gazebosim/gz-sim/blob/main/CONTRIBUTING.md#writing-tests) for help creating or modifying tests.
+See the [Writing Tests section of the contributor guide](https://gazebosim.org/docs/all/contributing/#writing-tests) for help creating or modifying tests.
 
 # Folder Structure
 

tutorials/install.md

@@ -1,7 +1,8 @@
 \page install Installation
 
-These instructions are for installing only Gazebo. If you're interested
-in using all the Gazebo libraries, not only Igniton Gazebo, check out this
+These instructions are for installing only Gazebo Sim. If you're interested
+in using all the Gazebo libraries including gz-launch, or to install all
+libraries from source, check out
 [Gazebo installation](https://gazebosim.org/docs/latest/install).
 
 We recommend following the binary install instructions to get up and running as
@@ -50,6 +51,27 @@ installing Gazebo from source.
   brew install gz-sim<#>
   ```
 
+### Windows
+
+1. First, follow the steps 1-4 of [Gazebo source install](https://gazebosim.org/docs/ionic/install_windows_src/#install-dependencies)
+  tutorial to install Conda, Visual Studio and set up a Conda environment (we'll call it `gz-ws`).
+
+  Do not forget to activate the Conda env (if not already activated)
+  inside the Visual Studio Command Prompt:
+
+  ```
+  conda activate gz-ws
+  ```
+
+2. Now install Gazebo.
+
+  ```
+  conda install gz-sim<#> --channel conda-forge
+  ```
+
+  Be sure to replace `<#>` with a number value, such as 8 or 9, depending on
+  which version you need.
+
 ## Source Install
 
 Install from source if you're interested in changing the source code or need a
@@ -115,6 +137,50 @@ feature which hasn't been released yet.
   sudo make install
   ```
 
+### Windows
+
+1. First, follow the steps 1-4 of [Gazebo source install](https://gazebosim.org/docs/ionic/install_windows_src/#install-dependencies)
+  tutorial to install Conda, Visual Studio and set up a Conda environment (we'll call it `gz-ws`).
+
+  Do not forget to activate the Conda env (if not already activated)
+  inside the Visual Studio Command Prompt:
+
+  ```
+  conda activate gz-ws
+  ```
+
+2. Install Gazebo dependencies:
+
+  You can view available versions and their dependencies:
+  ```
+  conda search libgz-sim* --channel conda-forge --info
+  ```
+
+  Install the dependencies, replacing `<#>` with the required versions:
+  ```
+  conda install gz-cmake<#> gz-common<#> gz-fuel-tools<#> gz-gui<#> gz-math<#> gz-msgs<#> gz-physics<#> gz-plugin<#> gz-rendering<#> gz-sensors<#> gz-tools<#> gz-transport<#> gz-utils<#> sdformat<#> --channel conda-forge
+  ```
+
+3. Navigate to where you would like to build the library, and clone the repository.
+  ```
+  # Optionally, append `-b gz-sim#` (replace # with a number) to check out a specific version
+  git clone https://github.com/gazebosim/gz-sim.git
+  ```
+
+4. Configure and build
+  ```
+  cd gz-sim
+  mkdir build
+  cd build
+  cmake .. -DBUILD_TESTING=OFF  # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install
+  cmake --build . --config Release
+  ```
+
+5. Optionally, install
+  ```
+  cmake --install . --config Release
+  ```
+
 ## Documentation
 
 API documentation and tutorials can be accessed at [https://gazebosim.org/libs/gazebo](https://gazebosim.org/libs/gazebo)
@@ -123,7 +189,10 @@ You can also generate the documentation from a clone of this repository by follo
 
 1. You will need [Doxygen](http://www.doxygen.org/). On Ubuntu Doxygen can be installed using
   ```
+  # Linux
   sudo apt-get install doxygen
+  # Windows
+  conda install doxygen --channel conda-forge
   ```
 
 2. Clone the repository
@@ -137,7 +206,7 @@ You can also generate the documentation from a clone of this repository by follo
   mkdir build
   cd build
   cmake ../
-  make doc
+  cmake --build . --target doc
   ```
 
 4. View the documentation by running the following command from the `build` directory.

tutorials/physics.md

@@ -10,7 +10,7 @@ by default.
 
 Downstream developers may also integrate other physics engines by creating new
 Gazebo Physics engine plugins. See
-[Gazebo Physics](https://gazebosim.org/api/physics/7/tutorials.html)'s
+[Gazebo Physics](https://gazebosim.org/api/physics/8/tutorials.html)'s
 tutorials to learn how to integrate a new engine.
 
 ## How Gazebo finds engines
@@ -25,24 +25,32 @@ If you've created a custom engine plugin, you can tell Gazebo where to find it
 by setting the `GZ_SIM_PHYSICS_ENGINE_PATH` environment variable to the
 directory where the plugin's shared library can be found.
 
-For example, if you've created the following physics engine shared library on
-Linux:
+For example, if you've created the following physics engine shared library:
 
 ```
+# Linux
 /home/physics_engines/libCustomEngine.so
+# Windows
+C:\Users\Robot\physics_engines\CustomEngine.dll
 ```
 
 You should set the variable as follows:
 
 ```
+# Linux
 export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines
+# Windows
+set GZ_SIM_PHYSICS_ENGINE_PATH=C:\Users\Robot\physics_engines
 ```
 
 If you have several libraries installed in different paths, you can add more
 paths, for example:
 
 ```
+# Linux, separate with :
 export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines:/home/more_engines
+# Windows, separate with ;
+set GZ_SIM_PHYSICS_ENGINE_PATH=C:\Users\Robot\physics_engines;C:\MoreEngines
 ```
 
 ## Tell Gazebo what engine to load
@@ -52,6 +60,7 @@ There are a few different ways of telling Gazebo which engine to load.
 For any method, you should provide the name of your plugin's shared library,
 but the `lib` prefix and the file extension are optional. So in this example,
 the file is `libCustomEngine.so` but it's enough to set `CustomEngine`.
+That is also prefered to support multiple operating systems.
 
 ### From SDF
 
@@ -103,23 +112,23 @@ Gazebo supports the following physics engine configurations through SDF.
 These options are available to all physics engines, but not all engines
 may support them. The default physics engine, DART, supports all these options.
 
-* [//physics/dart/collision_detector](http://sdformat.org/spec?ver=1.8&elem=physics#dart_collision_detector)
+* [//physics/dart/collision_detector](http://sdformat.org/spec?ver=1.11&elem=physics#dart_collision_detector)
     * Options supported by DART: `ode` (default), `bullet`, `fcl`, `dart`.
 
-* [//physics/dart/solver/solver_type](http://sdformat.org/spec?ver=1.8&elem=physics#solver_solver_type)
+* [//physics/dart/solver/solver_type](http://sdformat.org/spec?ver=1.11&elem=physics#solver_solver_type)
     * Options supported by DART: `dantzig` (default), `pgs`
 
 ## Troubleshooting
 
 > Failed to find plugin [libCustomEngine.so]. Have you checked the
 > GZ_SIM_PHYSICS_ENGINE_PATH environment variable?
 
-Gazebo can't find out where `libCustomEngine.so` is located.
+Gazebo can't find out where `libCustomEngine.so` or `CustomEngine.dll` is located.
 
 If that's an engine you believe should be installed with Gazebo Physics,
 check if the relevant plugin is installed.
 
-If that's a 3rd party engine, find where the `.so` file is installed and add
+If that's a 3rd party engine, find where the `.so` or `.dll` file is installed and add
 that path to the environment variable as described above.
 
 > Unable to load the [/home/physics_engines/libCustomEngine.so] library.

tutorials/point_cloud_to_mesh.md

@@ -21,7 +21,7 @@ After installing, open CloudCompare and import your point cloud file by going to
 Depending on the number of points in your point cloud, this could take several minutes.
 Once loaded, you should see the following tunnel section:
 
-![Opening the point cloud](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/cloudcompare2.png)
+\image html files/point_cloud_to_mesh/cloudcompare2.png
 
 Many 3D scans will be composed of millions, sometimes hundreds of millions of points.
 Converting a scan to a 3D model with that many points would be very difficult due to the number of polygons that would be created and the long processing time necessary to compute the normals.
@@ -35,21 +35,21 @@ We'll still walk through reducing points, however, to make the process quicker.
 
 To reduce the number of points in your cloud, click on the tunnel so a yellow cube outline appears around it, then go to `Edit` > `Subsample`.
 
-![Min. space between points](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/min_space.jpg)
+\image html files/point_cloud_to_mesh/min_space.jpg
 
 The number you will need to enter in the `min. space between points` field will vary depending on your point cloud.
 A value of .01 was sufficient to bring our point cloud to an easy-to-manage 1 million points.
 Point count is visible in the `Properties` window on the lower left side of the screen.
 
-![Point count of subsample](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/properties.png)
+\image html files/point_cloud_to_mesh/properties.png
 
 How many points you reduce down to will largely depend on how long you are willing to wait for the point cloud to be converted into a mesh.
 The more points you start with, the longer it will take to compute the normals and create the mesh.
 
 After the operation is complete you’ll have two clouds in your scene: the original point cloud and your subsampled point cloud.
 Most operations in CloudCompare will create new point clouds and keep the original, so make sure that you have the new point cloud selected before running an operation.
 
-![Selecting the new point cloud](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/secondcloud.png)
+\image html files/point_cloud_to_mesh/secondcloud.png
 
 ### Create a Polygonal Mesh
 
@@ -60,7 +60,7 @@ A normal is essentially the direction a polygon is facing.
 To do this, go to `Edit` > `Normals` > `Compute`.
 You'll see this dialog box:
 
-![Choose Triangulation surface model](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/compute_normals.png)
+\image html files/point_cloud_to_mesh/compute_normals.png
 
 You’ll see various options in the dialog box that appears.
 The main thing you’ll want to consider is what `Local surface model` to use.
@@ -73,7 +73,7 @@ Now we get to actually convert our point cloud to a mesh.
 To do this go to `Plugins` > `PoissonRecon`.
 You'll see this dialog box:
 
-![Octree depth and output density selection](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/outputdensity.png)
+\image html files/point_cloud_to_mesh/outputdensity.png
 
 The value you enter in the `Octree depth` field will determine the polygon count of the created model.
 You may have to run the surface reconstruction a couple times with varying values before you land on a polygon count that is suitable for your needs.
@@ -94,18 +94,18 @@ Our tunnel has turned into a blob shape.
 This is because the mesh that CloudCompare creates will always be water tight even if it has to add polygons where there are no points.
 We just want our tunnels, though, so we need to remove those unnecessary polygons.
 
-![The blob shape](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/blob2.jpg)
+\image html files/point_cloud_to_mesh/blob2.jpg
 
 This is where our scalar field comes in.
 In the mesh's `Properties` window go to `SF display params` and take the left handle in the graph and drag it to the right until it hits the area where the bulk of the scalar field starts.
 
-![Adjusting scalar filed params](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/sf_display.png)
+\image html files/point_cloud_to_mesh/sf_display.png
 
 This will display only the polygons that were created from the point cloud and hide the polygons used to make the model watertight.
 The polygons are only hidden however.
 We still need to actually remove them.
 
-![Display original polygons](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/hidden_polygons2.jpg)
+\image html files/point_cloud_to_mesh/hidden_polygons2.jpg
 
 To remove the hidden polygons go to `Edit` > `Scalar fields` > `Filter By Value`.
 
@@ -114,11 +114,11 @@ Hitting export will simply export the mesh within that range.
 Instead, we'll hit `Split` to create two meshes.
 One with the polygons inside our specified range and one containing polygons outside that range.
 
-![Splitting the mesh](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/split.png)
+\image html files/point_cloud_to_mesh/split.png
 
 It is possible that you will get error "Visibility table not instantiated". This error causes only the "wanted" part of the mesh to be created when splitting, while the other ("unwanted") part will not be generated. But that is not a problem for our use-case.
 
-![Error "Visibility table not instantiated"](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/error.jpg)
+\image html files/point_cloud_to_mesh/error.jpg
 
 ### The Completed Model
 
@@ -128,6 +128,6 @@ Your file format will depend on the software you want to use but `.obj` is a wid
 
 Before exporting, check your mesh for holes. If still checked, disable display of the pointcloud, so that only your output mesh is shown. Inspect ground parts of the mesh (or any other parts you are most interested in) and check if there aren't holes in it. If there are some, you can try to repeat the trimming step with more relaxed threshold.
 
-![The completed mesh](https://raw.githubusercontent.com/gazebosim/gz-sim/main/tutorials/files/point_cloud_to_mesh/complete2.png)
+\image html files/point_cloud_to_mesh/complete2.png
 
 You can find more information on CloudCompare and a more in depth look at the tools we used in this tutorial on [the CloudCompare website](https://www.cloudcompare.org/) and the [CloudCompare wiki](https://www.cloudcompare.org/doc/wiki/index.php?title=Main_Page).

tutorials/terminology.md

@@ -26,7 +26,7 @@ to developers touching the source code.
 
 * **System**: Logic that operates on all entities that have a given set of
     components. Systems are plugins that can be loaded at runtime.
-    Gazebo ships with various systems, and downstream develpers can
+    Gazebo ships with various systems, and downstream developers can
     [create their own systems](createsystemplugins.html).
 
 * **Entity-component manager** (**ECM**): Provides functions for