How to create and annotate your Environment¶

🏁 Goal of this tutorial

By the end of this tutorial, you will know how to create and annotate your environment. This will allow you to create Floors, Buildings, Lanes, and so on.

Pre-requisites¶

You should be able to remotely connect to your robot Set up ROS 2 communication with the robot.

You should be able to remotely access your robot SSH Connection to the robot.

You should be familiar with ROS’s RViz

You should first have completed the How to create a 2D map of the environment

You should first have completed the How to Localize in a known map of the environment

Explore default Environments with RViz¶

PAL Robots come with some default environments that correspond to some simulated Gazebo worlds. Their purpose it to help you get started with the environmental annotations and provide a template for creating new environments.

The easiest way to visualize and interact with the Environmental Annotations is by using the RViz GUI. This requires that you first establish the communication with the robot as explained in Set up ROS 2 communication with the robot.

Then, in the same terminal that is connected to the robot, you can start RViz with the command:

rviz2 -d /opt/pal/$PAL_DISTRO/share/<ROBOT>_advanced_2dnav/config/rviz/navigation.rviz

Attention

Make sure to replace the <ROBOT> placeholder with the name of your robot (e.g. pmb2, omni_base, ari, etc.). If you are using a TIAGo-Family robot, use the base_type name (either, pmb2 or omni_base).

Otherwise, if you want to use the simulation, you can use the following command:

source /opt/pal/${PAL_DISTRO}/setup.bash
ros2 launch <robot>_gazebo <robot>_gazebo.launch.py navigation:=True advanced_navigation:=True world_name:=pal_office

This starts the simulation in a virtual environment called pal_office.

Once RViz is running and is connected to the robot, you can explore the default environments by following these steps:

If not already available, load the PAL Navigation 2 panel in RViz

Go to the Environment tab in the PAL Navigation 2 panel

3. Explore the architecture of each Building by expanding it. In this list, the green items are the currently active ones and the black ones are inactive.

Explore default Environments with the CLI¶

In addition to the RViz GUI, you can also explore the default environments using the environment Command Line Interface (CLI). To do so, if you are working with a real robot, you first need to establish the communication with the robot as explained in SSH Connection to the robot.

Then, you can start using the pal environment command to explore the default environments.

~$ pal environment --help
usage: pal environment [-h] {list,get,activate,deactivate,enable,disable,remove} ...

Manage the available environmental annotations

positional arguments:
{list,get,activate,deactivate,enable,disable,remove}
                        Verb to execute
    list                Lists all entities
    get                 Gets a specific entity
    activate            Activates the defined Entity
    deactivate          Deactivates the defined Entity
    enable              Enables the defined Entity
    disable             Enables the defined Entity
    remove              Removes the defined Entity

options:
-h, --help            show this help message and exit

Using this CLI, you can list all the available entities in the environment

~$ pal environment list
Listing all entities ...
hospital
├── elevator
├── hospital_floor_0
│   ├── dock
│   ├── highway_1
│   ├── highway_2
│   ├── hospital_floor_0
│   ├── reduced_speed_area
│   ├── vo_chairs_1
│   ├── vo_chairs_2
│   └── wheelchair
└── hospital_floor_1
    ├── dock
    ├── hospital_floor_1
    ├── list_1
    ├── vo_chairs_1
    ├── vo_chairs_2
    └── waypoint_1
pal_office
├── elevator_left
├── elevator_right
├── pal_office_4th_floor
│   ├── aruco_1
│   ├── dock_1
│   ├── engineering
│   ├── highway_1
│   ├── highway_2
│   ├── vo_kitchen
│   ├── waypoint_list_nav
│   └── waypoint_nav
└── pal_office_7th_floor
    ├── dock_2
    ├── list_2
    ├── vo_kitchen
    ├── waypoint_admin
    ├── waypoint_kitchen
    └── workplaces
small_office
├── simple_building_anchor
└── small_office_floor
...

Or just the active ones:

~$ pal environment list --active
Listing active entities. Please wait...
pal_office
├── elevator_right
├── elevator_left
└── pal_office_4th_floor
    ├── dock_1
    ├── aruco_1
    ├── highway_1
    ├── highway_2
    ├── engineering
    ├── waypoint_nav
    ├── waypoint_list_nav
    └── vo_kitchen

Note

Please note that when multiple Buildings are configured, these commands can take a while to complete. Be patient while the system processes the request.

Alternatively, you can only list the entities of a specific type using the command:

~$ pal environment list --building
--------------------------------------------
| Key             | Is Active | Is Enabled |
--------------------------------------------
| willow_garage   | False     | False      |
| small_office    | False     | False      |
| hospital        | False     | False      |
| small_warehouse | False     | False      |
| pal_office      | True      | True       |
--------------------------------------------

Similarly, you can get the details of a specific entity by using the get verb:

~$ pal environment get --building pal_office
Building Name:  pal_office
Timezone:  Europe/Madrid
Is Active:  True
Is Enabled:  False

Create your Environment¶

Apart from the default environments, you can also create and annotate your own environment. To do so, we assume that you have already created a map of your environment using the steps described in the How to create a 2D map of the environment.

All the Environmental Annotation must live inside a Building, thus the first step is to create a new Building using the Add Building button on the PAL Navigation 2 panel.

This will create a new Building and a new Anchor that will allow you to add new Floors.

Once the Building is created, to add a new Floor, you can select it in the list of Buildings and then use the Add Floor button on the PAL Navigation 2 panel.

This will create a new Floor within the specified Building and and will also create a new Anchor that will allow you to add new Maps in the current Floor.

Finally, to add a new Map, you can select the Floor in the list of Floors and then use the Add Map button on the PAL Navigation 2 panel.

This will create a new Map within the specified Floor using the OccupancyGrid you created in the How to create a 2D map of the environment.

Finally, to start using your new Environment and adding new Annotations to it, you can deactivate the default Environment and activate your new one. To do so, you can right-click on the building you want to deactivate and select the Deactivate option from the context menu. Similarly, you can right-click on the building you want to activate and select the Activate option from the context menu.

Next steps¶

If you want to learn more about the environmental annotations, you can refer to 🏛️ Environmental Annotations.

If you want to learn more about how zones and lanes affect the navigation of the robot, you can refer to 🌐 Costmap Filters.

If you want to learn more about the waypoints and how to use them, you can refer to 🚩 Waypoint Navigation and How to Autonomously Navigate through a list of Waypoints.