Skip to content

Commit

Permalink
Regroup tutorials into four categories (#2109)
Browse files Browse the repository at this point in the history 
* Regroup tutorials into the 4 recommended categories
---------
Signed-off-by: Mabel Zhang <[email protected]>
Signed-off-by: Michael Carroll <[email protected]>
Co-authored-by: Michael Carroll <[email protected]>
  • Loading branch information
@mabelzhang
mabelzhang authored Jan 18, 2024
1 parent c158287 commit 0f27ce0
Show file tree
Hide file tree
Showing 5 changed files with 107 additions and 86 deletions.
107 changes: 65 additions & 42 deletions tutorials.md.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,71 +4,79 @@ 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
### Advanced

* \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.
* \subpage erbtemplate "ERB Template": Use ERB, a templating language, to generate SDF files for simulation worlds.

## Intermediate
## How-to Guides

* \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
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.

### Beginner

### Specific systems and features
* \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.

* \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.
### Intermediate

* \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 underwater_vehicles "Underwater Vehicles": Understand how to simulate underwater vehicles.
* \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 auto_inertia_calculation "Automatic Inertia Calculation": Automatically compute inertia values(mass, mass matrix, center of mass) for SDFormat links.

## Advanced users
### Advanced

* \subpage physics "Physics engines": Loading different physics engines.
* \subpage entity_creation "Entity creation": Insert models or lights using services.
* \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.
* \subpage physics "Physics engines": Load different physics engines.

## 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.
Expand All @@ -81,6 +89,21 @@ 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.

## 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.

## 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).
Expand Down
6 changes: 3 additions & 3 deletions tutorials/entity_creation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/9/classgz_1_1msgs_1_1EntityFactory.html)
Expand All @@ -65,7 +65,7 @@ This message allows us to create entities from strings, files,
[Lights](https://gazebosim.org/api/msgs/9/classgz_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.
Expand All @@ -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:

Expand Down
61 changes: 26 additions & 35 deletions tutorials/model_photo_shoot.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

```
```
<plugin
filename="gz-sim-physics-system"
name="gz::sim::systems::Physics">
</plugin>
```

A physics plugin is needed only if the `<random_joints_pose>` 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 `<random_joints_pose>` 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:

```
```
<plugin
filename="gz-sim-sensors-system"
name="gz::sim::systems::Sensors">
<render_engine>ogre2</render_engine>
<background_color>1, 1, 1</background_color>
</plugin>
```

A render plugin is needed to render the image. If `ogre2` is used, as shown in
the example, the `<backgrond_color>` 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 `<backgrond_color>` 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:

```
```
<include>
<uri>https://fuel.gazebosim.org/1.0/OpenRobotics/models/Robonaut</uri>
<plugin
Expand All @@ -61,21 +56,18 @@ plugin will also affect the final resulting background color on the images.
<random_joints_pose>true</random_joints_pose>
</plugin>
</include>
```

The model is loaded through the `<uri>` tag. Then the `model photo shoot`
plugin and its options are specified:

* `<translation_data_file>`: (optional) Location to store the camera
translation, scaling data and joints position (if using the
`<random_joints_pose>` option) that can be used to replicate the
pictures using other systems.
* `<random_joints_pose>`: (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 `<uri>` tag. Then the `model photo shoot`
plugin and its options are specified:
* `<translation_data_file>`: (optional) Location to store the camera
translation, scaling data and joints position (if using the
`<random_joints_pose>` option) that can be used to replicate the
pictures using other systems.
* `<random_joints_pose>`: (optional) When set to `true` the joints in the model
will be set to random positions prior to taking the pictures.

4. Camera sensor:

```
```
<model name="photo_shoot">
<link name="link">
<pose>0 0 0 0 0 0</pose>
Expand All @@ -99,8 +91,7 @@ will be set to random positions prior to taking the pictures.
</link>
<static>true</static>
</model>
```

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.
17 changes: 12 additions & 5 deletions tutorials/physics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,17 +28,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

Expand Down Expand Up @@ -70,7 +75,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
```

To use an existing alternative engine (e.g. Bullet Featherstone)

Expand Down
2 changes: 1 addition & 1 deletion tutorials/python_interfaces.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 0f27ce0

Please sign in to comment.