Skip to content

Commit

Permalink
copied over tutorials and other pages
Browse files Browse the repository at this point in the history 
Signed-off-by: Dharini Dutia <[email protected]>
  • Loading branch information
@quarkytale
quarkytale committed Aug 24, 2023
1 parent e89546d commit 077256a
Show file tree
Hide file tree
Showing 76 changed files with 4,448 additions and 0 deletions.
140 changes: 140 additions & 0 deletions harmonic/GUI_tutorial.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Understanding the GUI

This guide is an introduction to the Gazebo Graphical User Interface (GUI).

## Prerequisites

Before beginning, you should have [Harmonic installed](/docs/harmonic/install).
If you installed [from source](/docs/harmonic/install)
you will need to [source](/docs/harmonic/install_ubuntu_src#using-the-workspace) the workspace;
otherwise, you're good to go!

Start by getting Gazebo up and running with a sample world:

```bash
gz sim shapes.sdf
```

`gz sim` will run the latest version of Gazebo you have installed.
You can check if you have more than one version of Gazebo installed by running `gz sim --versions`.
For example, if you have Harmonic (7.x.x), Fortress (6.x.x) and Edifice (5.x.x) installed, `--versions` might return:

```bash
7.0.0
6.0.0
5.0.0
```

To ensure you're working with Harmonic, include the `--force-version` directive when starting up:

```bash
gz sim --force-version 7.0.0 shapes.sdf
```

## GUI

After running `shapes.sdf`, you should see the following screen:

![shapes.sdf](tutorials/gui/shapes.png)

The interface consists of several sections:

### The Toolbars

The toolbar along the top of the GUI contains two buttons, a file menu button (![menu button](tutorials/gui/menu_btn.png)) on the left, and a plugins button (![plugins button](tutorials/gui/plugins_btn.png)) on the right.
The file menu button allows you to save the world to a file, save and load interface configurations and customize interface style settings.
An interface configuration consists of the plugins you have loaded and the style settings in place.

![toolbars](tutorials/gui/toolbars.png)

The top left toolbar hanging below the file menu button contains shape buttons (sphere, box, cylinder, capsule and ellipsoid) as well as lighting controls (point, directional and spot).
The shape buttons allow you to directly insert a box, sphere, cylinder capsule, or ellipsoid model into the world.
Simply click on the shape you would like to insert, and place it into the world.
The shape will automatically snap onto the ground plane, and its properties will show up on the Entity Tree plugin window.

The following image shows the scene and the Entity Tree after adding three shapes (`box_0`, `sphere_0` and `capsule_0`):

![shape insertion](tutorials/gui/shape_insertion.png)

The first five buttons on the second row are for `Transform Control`.
To learn more about this plugin, go to the `Transform Control` section of [Manipulating Models](manipulating_models) tutorial.

The plugins button lists all the available plugins.
You can scroll down this list to see all the plugins that are available for your version of Gazebo.
When you select one, its interface will appear in the right panel.

### The Right Panel

The GUI contains two plugins that you see in the right panel upon starting.
At the top is the Component Inspector, followed by the Entity Tree.

Everything in a simulation is considered an "entity."
In `shapes.sdf`, the entities listed are the ground plane, each of the shape models, and the sun.

Entities in the Entity Tree can be expanded to reveal their links, as well as corresponding visuals and collisions, and joints, if they exist.

You can select entities in the simulation by clicking on their names in the Entity Tree (or by clicking directly on the entity in the scene).
You can also hold `Ctrl` and click to select multiple.

![Selecting multiple entities from the entity tree](tutorials/gui/entity_select.png)

You can right-click on any plugin to open basic `Settings` or to `Close`.
You can (re)open plugins through the plugin menu.

### The Scene

Within the scene is where you'll interact with your simulated world and objects.

Currently, you can navigate the scene with a mouse in several ways:

* **Left-click**: select entity
* **Right-click**: opens menu with options:
* *Move to*: center the scene on an entity
* *Follow*: choose an entity for the view to stay centered on, whether it moves or you pan around
* *Remove*: erase the entity from the simulation
* *Copy*: copy the entity to the virtual clipboard
* *Paste*: paste the entity from the virtual clipboard creating a duplicate
* *View*: open a submenu with different options to visualize the simulation aspects of the entity like the collisions, the centre of mass, etc.
* **Left-click and drag**: pan around the scene
* **Right-click and drag**: zoom in and out
* **Scroll wheel forward/backward**: zoom in and out
* **Scroll wheel click and drag**: rotate the scene
* Or use **Shift key + left-click and drag**

More complex methods for interacting with the entities within a scene will be explained in-depth in the coming tutorials.

#### Grid Config

The grid visibility in the scene can be adjusted by a plugin.
You can adjust features of the world's grid, including cell size, grid position, cell count, and even color.

Open the Grid Config plugin by selecting it from the plugins button from the toolbar and selecting it from the dropdown list.
The plugin will now show up in the right panel (below the Entity Tree, scroll down if your screen did not display it).

![Select Grid Config](tutorials/gui/grid_config.png)

#### World Control

Along the bottom edge of the scene, you'll notice several buttons:

![Playback buttons](tutorials/gui/playback.png)

From left to right, the options are `Play`, `Steps` and `RTF` (real time factor).

Pressing `Play` will start the simulation.
You can use the same button to pause the simulation as well.

The `Steps` button allows you to step through the simulation at the rate of a step size, or simulation iteration.
You can customize step size by hovering over the button.

![hover steps](tutorials/gui/hover_steps.png)

At the furthest right end of the scene, you can expand `RTF` to see not only the percentage value that compares real time with sim time, but also those individual values themselves, as well as iteration count.

![RTF expanded](tutorials/gui/rtf_expanded.png)

The function of the World Control options will become clearer once you begin manipulating entities.

## Next Up

Now that you're comfortable with Gazebo GUI navigation and terminology, let's start learning about more meaningful model interactions with the [Manipulating Models](manipulating_models) tutorial.
156 changes: 156 additions & 0 deletions harmonic/Manipulating_models.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# Manipulating Models

This tutorial will walk you through using various plugins to assist model and scene manipulation in the Gazebo GUI.

The Transform Control plugin is a combination of keybindings and transform control options: selection, translation, rotation and snapping.
This chart of [Gazebo's keyboard shortcuts](hotkeys) may be helpful for this tutorial.

The View Angle plugin allows you to quickly and easily adjust the direction from which your scene faces an entity in the simulation.

The Component Inspector plugin displays a variety of object attributes.

The Align Tool aligns entities along or about a specific entity's bounding box.

## Prerequisites

Start by getting Gazebo up and running with a sample world:

```bash
gz sim shapes.sdf
```

The previous tutorial, [Understanding the GUI](gui), explains the basics of navigating the Gazebo GUI.

## Transform Control

The top left toolbar contains controls for transforming.
Alternatively, the Transform Control plugin can be selected from the plugin drop-down menu.
The plugin will then appear at the bottom of the right panel.

![Choosing Transform Control from the plugin list](img/plugins.png)

### Select Mode

Selection is the default mode.
You can click to select entities in the scene.
A selected entity will be highlighted in the Entity Tree to indicate its selection.
You can select multiple entities by holding `Ctrl` and clicking.

![Selecting multiple entities](img/select_mult.png)

Entities can't be manipulated in select mode.

You can always return to selection mode from any other mode by pressing `Esc`.

### Translate Mode

Enter into translate mode by clicking the second icon from the left in the top left toolbar, the Transform Control plugin, or by hitting the keyboard shortcut: `T`.

![Translate mode icon](img/translate_icon.png)

Translate mode allows you to translate entities along the x, y and z axes.

Click on any entity while in translate mode to see the arrows representing the axes you can move along.
The red arrow represents the x-axis, green the y-axis, and blue the z-axis.
Click and hold on any of the arrows while moving your mouse to move the entity in that direction.

![Translate mode](img/translate.gif)

Additionally, holding down any one of the `X`, `Y` or `Z` keys, or a combination of them, while clicking and dragging will constrain the model's movement along those axes, regardless of the direction you move your mouse or the axis arrow you select.

### Rotate Mode

Enter into rotate mode by clicking the third icon from the left in the top left toolbar, the Transform Control plugin, or by hitting the keyboard shortcut: `R`.

![Rotate mode icon](img/rotate_icon.png)

Rotate mode allows you to rotate entities around the roll, pitch and yaw axes of rotation.

Click on any entity while in rotate mode to see the circles representing the axes you can rotate along.
The red circle represents roll, green is pitch, and blue is yaw.
Click and hold on any of the circles while moving your mouse to rotate the entity around that axis.

![Rotate mode](img/rotate.gif)

#### Align to World frame

An entity's local axes can become unaligned from the world frame after rotation.
If you would like to translate along the world frame axis, simply hold `Shift`.

This isn't a permanent realignment; you can move the entity while holding `Shift`, but once you let go it will return to it's local translational frame.

![World frame alignment - translation](img/translate_worldframe.gif)

The same can be done for an entity's local rotational frame.

![World frame alignment - rotation](img/rotate_worldframe.gif)

### Enter Custom Snap Values

When translating or rotating, you can "snap" an entity's movement to preset increments by holding `Ctrl` and then clicking and dragging.
By default, the snap value is 1 meter for translation and 45° for rotation.

Translational snaps will snap relative to the world frame, whereas rotational snaps will snap relative to the object's current orientation.

![Snap rotation](img/snap.gif)

You can customize snap values by clicking on the snap icon ![Snap icon](img/snap_icon.png) in the top left toolbar or the Transform Control plugin.

![Custom snap values](img/custom_snap.png)

Try holding `Shift` and `Ctrl` simultaneously to snap a model along the world frame is if isn't already aligned.

## Component Inspector

With this plugin, you can select an entity to display some of its attributes, including its pose, whether or not wind is acting on it, whether or not it's static, and more.
The plugin also displays the gravitational and magnetic fields of your world.

Expanding the `Pose` attribute will show the coordinate values for a selected object.
The values will update as the object is moved around (translated or rotated) while the simulation is running.

![Updating pose values](img/pose_value.gif)

You can also pause the plugin so an object's pose values don't update in the inspector while the simulation is playing.

Additionally, the Component Inspector can be locked on one object so you can open another Component Inspector to simultaneously observe another object.

![Two Component Inspectors](img/pose2.gif)

## View Angle

Select the View Angle from the plugins drop-down menu.

You can choose which angle you want to view the scene from, relative to a selected entity or the world frame if no entity is selected.
The home button will return you to the original view pose from when the scene was loaded.

You can also select multiple entities to face simultaneously from each view angle.

![View angle for multiple entities](img/view.gif)

## Align Tool

Select the Align Tool from the plugins drop-down menu.

The Align Tool aligns a model along or about the bounding box of another model, or any other entity that has a bounding box, like a link for example.
It can't, however, align a child link or anything other than the top-level model.

With `Relative to First` selected, select two models using `Ctrl` + click (be sure you are in select mode) and then hover over any of the Align Tool
buttons to see a preview of the second model aligning to the first along its x, y or z axis.
Hovering over the buttons for each axis will show a preview of where the model would end up if aligned along that axis while clicking will confirm that
specific alignment.

![Align](img/align.gif)

The Reverse button will enable alignment about the outer boundary of a model's bounding box. This feature is helpful for placing objects exactly next to each
other. Notice the difference in alignment when the Reverse button is pressed in the gif below.

![Align Reverse](img/align_reverse.gif)

You can align more than two models as well, simply select more models with `Ctrl` + click. You can select `First` or `Last` in the `Relative to:` drop down menu to
choose which entity to align to.

## Next Up

So far you've interacted with basic shape models to learn about Gazebo's GUI.
It's also possible to insert more detailed models from [Gazebo Fuel](https://app.gazebosim.org) into the GUI.
Check out the [Model Insertion from Fuel](fuel_insert) tutorial to learn how.
84 changes: 84 additions & 0 deletions harmonic/Model_insertion_fuel.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Model Insertion from Fuel

Gazebo Fuel hosts hundreds of models that can easily be added to a world running in the Gazebo GUI.


## Prerequisites

Start by getting Gazebo up and running with an empty world:

```bash
gz sim empty.sdf
```

The previous tutorial, [Manipulating Models](Manipulating_models.md), shows you how to interact with models, which might be helpful once you add some Fuel models to your world.

## Choose a Model

Fuel's model collection is at [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models).
Head over and browse the available content.

![Fuel models preview](tutorials/fuel_insert/fuel.png)

Click on any one of the thumbnails, or use the search bar.
For example, let's find the [Mine Cart Engine](https://app.gazebosim.org/OpenRobotics/fuel/models/Mine%20Cart%20Engine).

![Vent](tutorials/fuel_insert/mine_cart_engine_detail.png)

Note that some of the model files are quite large and may take some time to download into your world.
Check that the file size on the right is reasonable for your application before moving on.

## Spawn a Model

There are a few different ways to spawn a model into the simulation.

1. **Spawn from 'Fuel Resource' using the Resource Spawner plugin.**

Select the Resource Spawner plugin from the plugin menu (top right corner).
The plugin will appear in the right panel, you might need to scroll down to be able to see the plugin.
Wait until the resource are loaded under the 'Fuel Resource' panel.
Select a resource owner (e.g. openrobotics), you can now search for the model name in the right panel.
Click on the cloud icon to download the model.
When the model has been downloaded, you can click on the model and insert it into your simulation scene.

![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_cloud.png)


2. **Download model files from Fuel and spawn from local sources using the Resource Spawner plugin.**

- Download the model files from [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models).
- Extract the files and places them under your local model directory (e.g. `~/my-local-models/model-name`).
The folder should contain `materials`, `meshes` as well as the `model.config` and the `model.sdf` files.
- Add your model directory as a resource with `export GZ_SIM_RESOURCE_PATH=~/my-local/models/`
- Open the Gazebo Simulator and add the Resource Spawner Plugin, the model should now show up under your local resources.

![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_local.png)

3. **Copying the SDF snippet and adding it to your custom world SDF file.**

With the `<>` button you can directly copy a SDF snippet to paste into your world SDF file.
The SDF snippet will look something like this:

```
<include>
<uri>
https://fuel.gazebosim.org/1.0/OpenRobotics/models/Mine Cart Engine
</uri>
</include>
```

You can then add that snippet to a world SDF file as shown in the animation below.
More information on how to build your own world SDF files can be found in the tutorial on [SDF Worlds](sdf_worlds).

![spawn](tutorials/fuel_insert/husky.gif)

4. **Downloading the code to permanently add a Fuel model to your custum SDF file.**

If you prefer to add a Fuel model permanently to an `sdf` file, you can just as easily download the code by clicking the download-arrow icon to the right of the model's image.
Kook at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file.

Now you can add more models, or even load in any one of the plugins you learned about to interact with the model the same way you could with the shapes in the previous tutorial.

## Next Up

Now that you know how to add models hosted on Gazebo Fuel, it is time to learn how to [Build Your Own Robot](building_robot).
Loading

0 comments on commit 077256a

Please sign in to comment.