From d9eee29582b183e51850b8a09cacd478cc9f8562 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Fri, 1 Sep 2023 01:40:59 -0400 Subject: [PATCH 1/2] Regroup tutorials into the 4 recommended categories Signed-off-by: Mabel Zhang --- tutorials.md.in | 100 ++++++++++++++++++++------------- tutorials/entity_creation.md | 6 +- tutorials/model_photo_shoot.md | 61 +++++++++----------- tutorials/python_interfaces.md | 2 +- 4 files changed, 90 insertions(+), 79 deletions(-) diff --git a/tutorials.md.in b/tutorials.md.in index 10ace242e8..163d8d0843 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -4,70 +4,76 @@ Welcome to the Gazebo @GZ_DESIGNATION_CAP@ tutorials. These tutorials will guide you through the process of understanding the capabilities of the Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively. -## Getting Started +## Tutorials + +The Tutorials section contains step-by-step instructions with self-contained examples to help you get started using Gazebo. + +### Beginner * \subpage install "Installation": Install instructions. -* \subpage terminology "Terminology": List of terms used across the documentation. -* \subpage gui_config "GUI configuration": Customizing your layout. -* \subpage server_config "Server configuration": Customizing what system plugins are loaded. +* \subpage move_camera_to_model Move camera to model +* \subpage apply_force_torque "Apply Force and Torque": Apply forces and/or torques to models during simulation through the GUI. +* \subpage mouse_drag "Mouse Drag": Move models by dragging them in the scene using forces and torques. * \subpage model_command "Model Command": Use the CLI to get information about the models in a simulation. * \subpage reset_simulation Reset simulation -* \subpage resources "Finding resources": The different ways in which Gazebo looks for files. -* \subpage debugging "Debugging": Information about debugging Gazebo. +* \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server. -### GUI and rendering features +### Intermediate -* \subpage move_camera_to_model Move camera to model -* \subpage model_photo_shoot "Model Photo Shoot" Taking perspective, top, front, and side pictures of a model. -* \subpage videorecorder "Video Recorder": Record videos from the 3D render window. -* \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server. -* \subpage apply_force_torque "Apply Force and Torque": Applying forces and/or torques to models during simulation through the GUI. -* \subpage mouse_drag "Mouse Drag": Move models by dragging them in the scene using forces and torques. +* \subpage log "Logging": Record and play back time series of world state. +* \subpage levels "Levels": Load entities on demand in large environments. -### Migration from Gazebo classic +## How-to Guides -* \subpage migrationplugins "Plugins": Walk through the differences between writing plugins for Gazebo classic and Gazebo -* \subpage migrationsdf "SDF": Migrating SDF files from Gazebo classic to Gazebo -* \subpage migrationworldapi "World API": Guide on what World C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationmodelapi "Model API": Guide on what Model C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationlightapi "Light API": Guide on what Light C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationjointapi "Joint API": Guide on what Joint C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationactorapi "Actor API": Guide on what Actor C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationlinkapi "Link API": Guide on what Link C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage migrationsensorapi "Sensor API": Guide on what Sensor C++ functions to call in Gazebo when migrating from Gazebo classic -* \subpage ardupilot "Case Study": Migrating the ArduPilot ModelPlugin from Gazebo classic to Gazebo. +The How-to Guides provide recipes for specific "How to..." questions or things you may want to do. +They assume some experience. +If you are an absolute beginner, start with the Tutorials section. -## Intermediate +### Beginner -* \subpage log "Logging": Record and play back time series of world state. -* \subpage light_config "Light config": Configure lights in the scene. -* \subpage levels "Levels": Load entities on demand in large environments. -* \subpage python_interfaces Python interfaces +* \subpage gui_config "GUI configuration": Customize your layout. +* \subpage server_config "Server configuration": Customize what system plugins are loaded. +* \subpage model_photo_shoot "Model Photo Shoot" Taking perspective, top, front, and side pictures of a model. +* \subpage videorecorder "Video Recorder": Record videos from the 3D render window. -### Specific systems and features +### Intermediate -* \subpage detachablejoints "Detachable Joints": Creating models that start off rigidly attached and then get detached during simulation. -* \subpage triggeredpublisher "Triggered Publisher": Using the TriggeredPublisher system to orchestrate actions in simulation. +* \subpage light_config "Light config": Configure lights in the scene. +* \subpage entity_creation "Entity creation": Insert models or lights using services. * \subpage battery "Battery": Keep track of battery charge on robot models. -* \subpage particle_emitter "Particle emitter": Using particle emitters in simulation -* \subpage spherical_coordinates "Spherical coordinates": Working with latitude and longitude +* \subpage particle_emitter "Particle emitter": Use particle emitters in simulation +* \subpage detachablejoints "Detachable Joints": Create models that start off rigidly attached and then get detached during simulation. +* \subpage triggeredpublisher "Triggered Publisher": Use the TriggeredPublisher system to orchestrate actions in simulation. +* \subpage spherical_coordinates "Spherical coordinates": Work with latitude and longitude * \subpage underwater_vehicles "Underwater Vehicles": Understand how to simulate underwater vehicles. -* \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation. +* \subpage logicalaudiosensor "Logical Audio Sensor": Use the LogicalAudioSensor system to mimic logical audio emission and detection in simulation. -## Advanced users +### Advanced -* \subpage physics "Physics engines": Loading different physics engines. -* \subpage entity_creation "Entity creation": Insert models or lights using services. +* \subpage physics "Physics engines": Load different physics engines. * \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds. * \subpage distributedsimulation "Distributed Simulation": Spread simulation across several processes. -## Developers +### Developers * \subpage createsystemplugins "Create System Plugins": Programmatically access simulation using C++ plugins. * \subpage rendering_plugins "Rendering plugins": Write plugins that use Gazebo Rendering on the server and client. * \subpage test_fixture "Test Fixture": Writing automated CI tests -## 3D modeling help +### Migration from Gazebo classic + +* \subpage migrationplugins "Plugins": Walk through the differences between writing plugins for Gazebo classic and Gazebo +* \subpage migrationsdf "SDF": Migrating SDF files from Gazebo classic to Gazebo +* \subpage migrationworldapi "World API": Guide on what World C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationmodelapi "Model API": Guide on what Model C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationlightapi "Light API": Guide on what Light C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationjointapi "Joint API": Guide on what Joint C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationactorapi "Actor API": Guide on what Actor C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationlinkapi "Link API": Guide on what Link C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage migrationsensorapi "Sensor API": Guide on what Sensor C++ functions to call in Gazebo when migrating from Gazebo classic +* \subpage ardupilot "Case Study": Migrating the ArduPilot ModelPlugin from Gazebo classic to Gazebo. + +### 3D modeling help * \subpage collada_world_exporter "Collada World Exporter": Export an entire world to a single Collada mesh. * \subpage meshtofuel "Importing a Mesh to Fuel": Build a model directory around a mesh so it can be added to the Gazebo Fuel app. @@ -80,6 +86,20 @@ Gazebo @GZ_DESIGNATION_CAP@ library and how to use the library effectively. * \subpage blender_distort_meshes "Blender mesh distortion": Use a Blender Python script to programmatically deform and distort meshes to customized extents. * \subpage blender_procedural_datasets "Generation of Procedural Datasets with Blender": Use Blender with a Python script to generate procedural datasets of SDF models. +## Explanation + +The explanation section discusses concepts that require additional understanding than the scope of the Tutorials and How-to Guides. + +* \subpage terminology "Terminology": List of terms used across the documentation. + +## Reference + +The reference section contains information that may come in handy for lookup. + +* \subpage resources "Finding resources": The different ways in which Gazebo looks for files. +* \subpage python_interfaces Python interfaces +* \subpage debugging "Debugging": Information about debugging Gazebo. + ## License The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/tutorials/entity_creation.md b/tutorials/entity_creation.md index 0e5b9c8824..c6339aeab7 100644 --- a/tutorials/entity_creation.md +++ b/tutorials/entity_creation.md @@ -55,7 +55,7 @@ gz service --list /world/world_name/state_async ``` -# Factory message +## Factory message To create new entities in the world we need to use the [gz::msgs::EntityFactory](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1EntityFactory__V.html) @@ -65,7 +65,7 @@ This message allows us to create entities from strings, files, [Lights](https://gazebosim.org/api/msgs/6.0/classignition_1_1msgs_1_1Light.html) or even clone models. This tutorial introduces how to create entities from SDF strings and light messages. -## Insert an entity based on a string +### Insert an entity based on a string We will open an empty Gazebo world, let's start creating a sphere in the world. In the next snippet you can see how to create models based on strings. @@ -87,7 +87,7 @@ happen. You may see some traces in the console showing this information. There is an option to create a new entity every time that the message is sent by setting `allow_renaming` to true (you can use the method `set_allow_renaming()`). -## Insert a light +### Insert a light To insert a light in the world we have two options: diff --git a/tutorials/model_photo_shoot.md b/tutorials/model_photo_shoot.md index 7d7209d0f8..f3ce372c9c 100644 --- a/tutorials/model_photo_shoot.md +++ b/tutorials/model_photo_shoot.md @@ -21,37 +21,32 @@ SDF is used to load and configure the `Model Photo Shoot` plugin. The demo SDF contains a good example of the different options and other related plugins: 1. The physics plugin: - -``` + ``` -``` - -A physics plugin is needed only if the `` option is to -be used. This will allow the `Model Photo Shoot` plugin to set the joints -to random positions. + ``` + A physics plugin is needed only if the `` option is to + be used. This will allow the `Model Photo Shoot` plugin to set the joints + to random positions. 2. The render engine plugin: - -``` + ``` ogre2 1, 1, 1 -``` - -A render plugin is needed to render the image. If `ogre2` is used, as shown in -the example, the `` tag can be used to set the background -of the pictures taken by the plugin. Please note that lights added by the -plugin will also affect the final resulting background color on the images. + ``` + A render plugin is needed to render the image. If `ogre2` is used, as shown in + the example, the `` tag can be used to set the background + of the pictures taken by the plugin. Please note that lights added by the + plugin will also affect the final resulting background color on the images. 3. The model and the photo shoot plugin: - -``` + ``` https://fuel.gazebosim.org/1.0/OpenRobotics/models/Robonaut true -``` - -The model is loaded through the `` tag. Then the `model photo shoot` -plugin and its options are specified: - -* ``: (optional) Location to store the camera -translation, scaling data and joints position (if using the -`` option) that can be used to replicate the -pictures using other systems. -* ``: (optional) When set to `true` the joints in the model -will be set to random positions prior to taking the pictures. + ``` + The model is loaded through the `` tag. Then the `model photo shoot` + plugin and its options are specified: + * ``: (optional) Location to store the camera + translation, scaling data and joints position (if using the + `` option) that can be used to replicate the + pictures using other systems. + * ``: (optional) When set to `true` the joints in the model + will be set to random positions prior to taking the pictures. 4. Camera sensor: - -``` + ``` 0 0 0 0 0 0 @@ -99,8 +91,7 @@ will be set to random positions prior to taking the pictures. true -``` - -A `camera sensor` must be added as it will be used by the plugin to take the -pictures. This allows plugin users to set the different parameters of the -camera to their desired values. + ``` + A `camera sensor` must be added as it will be used by the plugin to take the + pictures. This allows plugin users to set the different parameters of the + camera to their desired values. diff --git a/tutorials/python_interfaces.md b/tutorials/python_interfaces.md index ad0e0d8ddc..5bcb44c1da 100644 --- a/tutorials/python_interfaces.md +++ b/tutorials/python_interfaces.md @@ -82,7 +82,7 @@ post_iterations 1000 pre_iterations 1000 ``` -# Gazebo Systems written in Python +## Gazebo Systems written in Python Gazebo also provides a way to write systems in Python. This is done using the `gz::sim::systems::PythonSystemLoader` system which loads a given python module From 12b4187df73f640ca52a0909036d3dc8e2d97037 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Sat, 2 Sep 2023 01:57:25 -0400 Subject: [PATCH 2/2] refine Signed-off-by: Mabel Zhang --- tutorials.md.in | 19 +++++++++++-------- tutorials/physics.md | 17 ++++++++++++----- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/tutorials.md.in b/tutorials.md.in index 163d8d0843..53495848e1 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -23,6 +23,10 @@ The Tutorials section contains step-by-step instructions with self-contained exa * \subpage log "Logging": Record and play back time series of world state. * \subpage levels "Levels": Load entities on demand in large environments. +### Advanced + +* \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds. + ## How-to Guides The How-to Guides provide recipes for specific "How to..." questions or things you may want to do. @@ -51,8 +55,6 @@ If you are an absolute beginner, start with the Tutorials section. ### Advanced * \subpage physics "Physics engines": Load different physics engines. -* \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds. -* \subpage distributedsimulation "Distributed Simulation": Spread simulation across several processes. ### Developers @@ -86,12 +88,6 @@ If you are an absolute beginner, start with the Tutorials section. * \subpage blender_distort_meshes "Blender mesh distortion": Use a Blender Python script to programmatically deform and distort meshes to customized extents. * \subpage blender_procedural_datasets "Generation of Procedural Datasets with Blender": Use Blender with a Python script to generate procedural datasets of SDF models. -## Explanation - -The explanation section discusses concepts that require additional understanding than the scope of the Tutorials and How-to Guides. - -* \subpage terminology "Terminology": List of terms used across the documentation. - ## Reference The reference section contains information that may come in handy for lookup. @@ -100,6 +96,13 @@ The reference section contains information that may come in handy for lookup. * \subpage python_interfaces Python interfaces * \subpage debugging "Debugging": Information about debugging Gazebo. +## Concepts + +The concepts section explains things that require additional understanding than the scope of the Tutorials and How-to Guides. + +* \subpage terminology "Terminology": List of terms used across the documentation. +* \subpage distributedsimulation "Distributed Simulation": Spread simulation across several processes. + ## License The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/tutorials/physics.md b/tutorials/physics.md index a8e1c12217..5ba3912995 100644 --- a/tutorials/physics.md +++ b/tutorials/physics.md @@ -26,17 +26,22 @@ directory where the plugin's shared library can be found. For example, if you've created the following physics engine shared library on Linux: -`/home/physics_engines/libCustomEngine.so` +``` +/home/physics_engines/libCustomEngine.so +``` You should set the variable as follows: -`export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines` - +``` +export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines +``` If you have several libraries installed in different paths, you can add more paths, for example: -`export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines:/home/more_engines` +``` +export GZ_SIM_PHYSICS_ENGINE_PATH=/home/physics_engines:/home/more_engines +``` ## Tell Gazebo what engine to load @@ -68,7 +73,9 @@ For the example above, you can load it like this: Alternatively, you can choose a plugin from the command line using the `--physics-engine` option, for example: -`gz sim --physics-engine CustomEngine` +``` +gz sim --physics-engine CustomEngine +``` ### From C++ API