|
|
|
|
|
|
🔌 Environmental Annotations API#
ROS 2 API#
To interact with the Environmental Annotations, you can refer to the following ROS 2 APIs.
Topics |
Services |
|---|---|
C++ API#
Conversions#
The eulero_utils package provides several utility functions to interact with Environmental Metadata in your
C++ code and to convert between ROS 2 messages, C++ objects and YAML::Nodes.
Function |
Description |
|---|---|
|
Creates a fully instantiated |
|
Creates a |
|
Creates a vector of |
|
Stores a vector of |
|
Creates a fully instantiated |
|
Creates a ROS 2 Message from a fully instantiated |
Note
In the previous table, EnvironmentalAnnotation doesn’t name a type. It is a placeholder for any of the available
Environmental Annotations (Building, BuildingAnchor, Floor, FloorAnchor, Lane, Map,
Waypoint, WaypointList, Zone).
To use these functions in your Code, you need to include the needed header files:
#include "eulero_utils/building_conversions.hpp" // for Building conversions
#include "eulero_utils/floor_conversions.hpp" // for Floor conversions
// etc.
// Alternatively, you can include all conversions at once
#include "eulero_utils/conversions.hpp"
Then you can start using the conversion functions in your code. For example, to initialize a eulero::Building
object from a YAML file, you can use:
data = YAML::LoadFile(yaml_name);
for (const auto & building_node : data["buildings"]) {
auto building = eulero::building::fromYAML(building_node);
}
Database Interaction#
The eulero_model package provides several tools to interact with the Database where the Environmental Annotations
are stored. It allows, for example, to be notified when a new Annotation is created, updated or deleted. Also,
it allows to query the Database to retrieve specific Annotations which match certain criteria.
To start interacting with the Database, you need to include the needed header files:
#include "eulero_model/core/eulero_db_client.hpp"
And create a new instance of the eulero::EuleroDbClient class:
auto db_client = std::make_shared<eulero::EuleroDbClient>("my_db_client");
Note
Before start using your eulero::EuleroDbClient instance to interact with the Database, it is a good practice
to wait until the Database is ready. You can do so by using the isClientAvailable() function.
while (!db_client->isClientAvailable() && rclcpp::ok()) {
// WAIT
}
Finally, you can start using your eulero::EuleroDbClient to interact with the Environmental Annotations stored
in the Database.
For example, to register a new callback that is triggered every time a Zone is created, updated or deleted, you can
use:
db_client->getClient()->registerEvtCb(
[&](pal_stores_msgs::msg::DatabaseEvent::_event_type_type, const std::string &,
const std::string &) {
RCLCPP_INFO(rclcpp::logger("my_node_logger"), "Change detected in Database");
// Do something
}, {"eulero::Zone"});
Similarly, to retrieve all the Available Zones you can create a new stores::StoreQuery with a
stores::Condition that matches all the Zones with the is_active field set to true:
#include "eulero_model/zone.hpp"
stores::StoreQuery query;
query.matchAll(
{
stores::Condition("$.is_active", stores::Condition::Operation::EQ, "true")
});
auto list_zones = db_client->getClient()->list<eulero::Zone>(query);
The template function list<eulero::Zone> returns a vector of std::shared_ptr to eulero::Zone objects that
are NOT fully initialized. It only contains the key of each Zone. To fully initialize the Zone objects,
you can use the load function:
auto vo = std::make_shared<eulero::Zone>();
vo->load(list_zone.key());
RViz GUI#
To allow users to easily interact with Environmental Annotations, there are several RViz Tools available. Using these tools,
users can create new Annotations such as Zones, Lanes, and Waypoints and add them to the corresponding
Building and Floor.
Waypoint Tool#
To create a new Waypoint using the RViz Waypoint Tool, first, select the position and orientation of the new
Waypoint, then a pop-up window will appear asking for the name and the properties of the new Waypoint.
Once created, the new Waypoint is ready to be used for the 🚩 Waypoint Navigation.
Zone Tool#
To create a new Zone using the RViz Zone Tool, use the left-click to place a new vertex of the Zone.
To add the last vertex of the Zone, use the right-click.
Once the last vertex is added, a pop-up window will appear asking for the name and the properties of the new Zone.
Note
To create a new Zone, you need to select a minimum of 3 vertexes.
For more information about the Zone parameters and how they are used, please refer to 🌐 Costmap Filters.
Lane Tool#
To create a new Lane using the RViz Lane Tool, use the left-click to place a new vertex of the Lane.
To add the last vertex of the Lane, use the right-click.
Once the last vertex is added, a pop-up window will appear asking for the name and the properties of the new Lane.
Note
To create a new Lane, you need to select a minimum of 2 vertexes.
For more information about the Lane parameters and how they are used, please refer to 🌐 Costmap Filters.