From a397b45a5dcf591b2862e03e39dfa488420518f0 Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Fri, 8 Dec 2023 11:58:30 +0100 Subject: [PATCH] add sdformat sensors import description Signed-off-by: Jan Hanca --- .../interactivity/robotics/_index.md | 6 +- .../_index.md} | 25 ++++--- .../importing-robot/sdformat-sensors.md | 66 +++++++++++++++++++ 3 files changed, 81 insertions(+), 16 deletions(-) rename content/docs/user-guide/interactivity/robotics/{importing-robot.md => importing-robot/_index.md} (82%) create mode 100644 content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md diff --git a/content/docs/user-guide/interactivity/robotics/_index.md b/content/docs/user-guide/interactivity/robotics/_index.md index 6a80e3e44be..19326402dc7 100644 --- a/content/docs/user-guide/interactivity/robotics/_index.md +++ b/content/docs/user-guide/interactivity/robotics/_index.md @@ -8,12 +8,12 @@ description: Learn how to create robotics simulation in Open 3D Engine (O3DE) wi These Gems provide various O3DE components such as sensors, robot control and steering, manipulator arms, and support for importing robots from common formats. | Topic | Description | -|---------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| +| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [Overview](overview.md) | Overview of Gems, Templates and demos for robotics in O3DE. | | [ROS 2 Project Configuration](project-configuration.md) | Learn how to configure, build and run a project with the ROS 2 Gem. | | [ROS 2 Concepts and Structure](concepts-and-components-overview.md) | Overview of concepts and structure of the ROS 2 Gem, including an overview of its components. | | [Creating robotic simulation](creating-robotic-simulation.md) | High-level steps to create a robotic simulation with O3DE. | -| [Importing robots](importing-robot.md) | Learn how to import robots using Robot Importer. | +| [Importing robots](importing-robot) | Learn how to import robots using Robot Importer. | | [Grippers](grippers.md) | Documentation of robotic grippers feature. | | [Joints Manipulation](joints-manipulation.md) | Joints manipulation, such as with robotic manipulator arms. | | [Troubleshooting the simulation](troubleshooting.md) | Helpful solutions to some of the most common issues with ROS 2. | @@ -22,7 +22,7 @@ These Gems provide various O3DE components such as sensors, robot control and st ## Related topics | Topic | Description | -|----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [ROS 2 Gem reference](/docs/user-guide/gems/reference/robotics/ros2) | Gem reference documentation for ROS 2 Gem. | | [Setting up CLion IDE](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/docs/guides/development_in_clion.md) | CLion IDE project setup to support the ROS 2 Gem. | | [Open 3D Engine Contributor guide](/docs/contributing) | Read this guide if you wish to contribute to the ROS 2 Gem. | diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot.md b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md similarity index 82% rename from content/docs/user-guide/interactivity/robotics/importing-robot.md rename to content/docs/user-guide/interactivity/robotics/importing-robot/_index.md index d4aa0e0168f..a3d65bc50ff 100644 --- a/content/docs/user-guide/interactivity/robotics/importing-robot.md +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md @@ -18,26 +18,25 @@ SDFormat, URDF, and XACRO are widely used robot description standards within the [XML Macros (XACRO)](http://wiki.ros.org/xacro) is a macro language that simplifies the creation and maintenance of URDF files. XACRO allows you to generate URDF files using XML macros. In XACRO, you can define parameters and include files, which is useful to change and iterate on robot models. You can also expand and reuse XACRO across multiple robot models. -URDF/XACRO files contain complete robot descriptions, including references to external geometry files. While you can define primitive geometries directly within the URDF/XACRO file, it's common practice to use external mesh files, in formats such as DAE (Collada) or STL, to represent the visual and collision shapes of the robot. -Robot models are typically available in packages that include the URDF/XACRO file and additional geometry files that contain visualizations and collision shapes, either as primitive geometries or external mesh files. These packages may be distributed as ROS workspaces, which are more straightforward to use in ROS applications. +URDF, XACRO, and SDFormat files contain complete robot descriptions, including references to external geometry files. While you can define primitive geometries directly within the robot description file, it is a common practice to use external mesh files, in formats such as DAE (Collada) or STL, to represent the visual and collision shapes of the robot. +Robot models are typically available in packages that include the robot description file and additional geometry files with visualizations and collision shapes, either as primitive geometries or external mesh files. These packages may be distributed as ROS workspaces, which are more straightforward to use in ROS applications. ## Introduction to Robot Importer Import robots into your O3DE simulation project using the Robot Importer that's included in the ROS 2 Gem. Robot Importer has the following features: - Guides you through the import process step by step. -- Allows to change parameters of the import. -- Reads SDF, URDF and XACRO files. +- Allows to change parameters of the import, including search paths for assets. +- Reads SDFormat, URDF and XACRO files. - Copies all required assets files to the `Assets` folder of your O3DE project. - Creates a prefab with a multi-body structure using articulations or classic rigid bodies and joints components. ## Importing a robot into your simulation project - ### Prerequisite -Before you can use robot description files in a ROS package, you must first build a workspace with the package and its dependencies. This ensures that Robot Importer can find all the required files. +Depending on a content of robot description files, you might need to build a ROS workspace with the package and its dependencies. This ensures that Robot Importer can find all the required files. In some cases, it is possible to append paths used by the Robot Importer in the Wizard instead, and to skip the build of a ROS workspace completely. To build, create a workspace and run `colcon build`. Do not forget to source ROS 2 workspace before launching the O3DE Editor. @@ -57,17 +56,16 @@ For more information, refer to the robot description package's documentation, wh 4. Load a description file by doing the following: - - Select an SDF, URDF, or XACRO file to import by clicking on the **[...]** button. + - Select an SDFormat, URDF, or XACRO file to import by clicking on the **[...]** button. - A number of options are available to modify the behavior of the importer: * Use Articulations - Determines whether PhysX articulation components should be used for joints and rigid bodies. * Preserve URDF fixed joint - When set, preserves any fixed joints found when importing a URDF file. This prevents the joint reduction logic in libsdformat from merging links of those joints. * Fix URDF to be compatible with libsdformat - It allows you to import some URDFs or XACRO files that are not fully compatible. With this feature enabled, Robot Importer will try to adjust the URDF code to be compatible. - * Path Resolvers - SDF, URDF, and XACRO files are almost always referencing some other files (like meshes, and textures). This feature allows you to give a hint to Robot Importer where to find those assets. - This feature can be useful, in an advanced situation like: importing legacy files, or trying to import ROS 1 packages. \ + * Path Resolvers - SDFormat, URDF, and XACRO files are almost always referencing some other files (like meshes, and textures). This feature allows you to give a hint to Robot Importer where to find those assets. + This feature can be useful, in an advanced situation like importing legacy files or trying to import ROS 1 packages. \ **Important** This feature does not affect the XACRO parsing, since the XACRO bundled with ROS 2 installation is used at this moment. * Use `AMENT_PREFIX_PATH` - Uses the [AMENT_PREFIX_PATH](https://design.ros2.org/articles/ament.html) environment variable to locate asset references. It is a default behavior for ROS 2 description packages. - * Prefix Replacement - This is a map that allows you to determine how prefixes to specific paths will be resolved during import.SDF, URDF, and XACRO files are almost always referencing some other files (like meshes, and textures). This feature allows you to give a hint to Robot Importer where to find those assets. - **Important** This feature does not affect the XACRO parsing, since the XACRO bundled with ROS 2 installation is used at this moment. + * Prefix Replacement - This is a map that allows you to determine paths for the Path Resolvers, described earlier. - Click **Next**. ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_load_file.png) @@ -93,7 +91,7 @@ After this automatic adjustment, you can take a look into the changes that were ![Robot Importer](/images/user-guide/gems/ros2/URDF_fixing_result.png) {{< note >}} - Option 'Fix URDF to be compatible with libsdformat' allows you to successfully import URDF that is not compatible with simulation, but please remember to adjust the resulting prefab. + Option 'Fix URDF to be compatible with libsdformat' allows you to successfully import URDF files that are not compatible with simulation, but please remember to adjust the resulting prefab. {{< /note >}} ### Processing robot assets @@ -146,10 +144,11 @@ You can either resolve the issues now or after you finish using Robot Importer: 3. Finally, there is a prefab in the scene. You can add one or more [sensors](/docs/user-guide/interactivity/robotics/concepts-and-components-overview/#sensors) or mobilize robot with [ROS 2 Vehicle Dynamics](/docs/user-guide/interactivity/robotics/vehicle-dynamics/) or using [Joint Manipulation](/docs/user-guide/interactivity/robotics/joints-manipulation/). ![Robot Importer](/images/user-guide/gems/ros2/URDF_result.png) + ### Re-importing robots Use the Robot Importer to re-import URDF files. In some cases, assets (mesh files) don't update if they were previously imported correctly. To work around this and do a complete re-import, delete the assets from your project by using the Asset Browser or in the directory. ### Details -Implementation details are available in [RFC](https://github.com/o3de/sig-simulation/issues/80) \ No newline at end of file +Details about supported SDFormat sensors are available in the [SDFormat sub-page](./sdformat-sensors.md) \ No newline at end of file diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md new file mode 100644 index 00000000000..20695d7aa6a --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md @@ -0,0 +1,66 @@ +--- +linkTitle: SDFormat sensors +title: SDFormat sensors +description: Detailed description of support of SDFormat sensors in Robot Importer. +weight: 100 +--- + +## Introduction + +Robots described in either [SDFormat](http://sdformat.org/), [URDF](http://wiki.ros.org/urdf), or [XACRO](http://wiki.ros.org/xacro) format, can be imported into your O3DE simulation project using the Robot Importer. The tool converts links and joints into O3DE entities and components alongside the parameters defined in the input robot description file. You can find more details about Robot Importer in the [documentation](/docs/user-guide/interactivity/robotics/importing-robot/). + +Similarly, the robots' [sensors](http://sdformat.org/spec?ver=1.10&elem=sensor) are imported from the description files into O3DE using ROS 2 sensor components available in [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/). Note, that the sensor's description can be stored directly in SDFormat files or using `` tag in URDF and XACRO files. + +## Sensor import architecture + +Sensor import, i.e. the mapping between Gazebo description and O3DE components, is based on the O3DE [reflection system](/docs/user-guide/programming/components/reflection/reflecting-for-serialization/). In particular, O3DE components that are designed to mirror the behavior of SDFormat sensors and/or plugins are registered using a specialized attribute tag. The import structure, called _hook_, implements the conversion scheme between the robot description parameters and O3DE data. The Robot Importer finds all active _hooks_ and checks, if any of them can be used to import SDFormat data. The mapping is extendable, allowing you to add your _hooks_ and map them to existing SDFormat data. + +It is important to note, that implementation of sensors in [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/) exposes ROS 2 communication interfaces by design, which makes it comparable to Gazebo sensor plugins. Therefore, you do not have to define a Gazebo sensor plugin if you want to make ROS 2 topics available. On the other hand, both sensor and plugin names must match the _hook's_ definition to be added to O3DE representation of the robot if the plugin definition exists in the robot description file. This way you can override the default behavior of the Robot Importer with your specific implementation of the same sensor. + +### SDF sensor tag mappings + +Four basic sensors' _hooks_ are predefined in Robot Importer. These can be summarized as follows: + +| _Hook_ name | Supported SDFormat sensors | Supported SDFormat plugins | O3DE sensor component | +| ------------------ | -------------------------- | ----------------------------- | --------------------------- | +| _CameraSensorHook_ | `camera_sensor`, | `libgazebo_ros_camera` | `ROS2CameraSensorComponent` | +| | `depth_camera` | `libgazebo_ros_depth_camera` | | +| | `multicamera` | `libgazebo_ros_multicamera` | | +| | `rgbd_camera` | `libgazebo_ros_openni_kinect` | | +| _GNSSSensorHook_ | `gps`, `navsat` | `libgazebo_ros_gps_sensor` | `ROS2GNSSSensor` | +| _ImuSensorHook_ | `imu` | `libgazebo_ros_imu_sensor` | `ROS2ImuSensorComponent` | +| _LidarSensorHook_ | `lidar`, `ray` | `libgazebo_ros_ray_sensor` | `ROS2LidarSensorComponent` | +| | `gpu_lidar`, `gpu_ray` | `libgazebo_ros_laser` | _see information below_ | + +GPU implementation of ray/lidar sensors is not included in ROS 2 Gem and requires additional [O3DE RGL Gem](https://github.com/RobotecAI/o3de-rgl-gem). GPU sensors are mapped during the import to run on a CPU if this Gem is not available. + +### Extending default mapping + +You can extend the default mapping by implementing additional _hooks_ and registering them in the system based on the _SerializeContext_ reflection system. Typically, this consists of three tasks. + +First, you need to declare `ROS2::SDFormat::SensorImporterHook` structure that consists of the following: +* set of SDFormat sensors associated with your import scheme +* set of plugin names associated with your import scheme +* set of the supported parameters in the input robot description (used for import verbose only) +* registered callback function that is invoked by Robot Importer when _hook's_ definition matches the input data + +The registered callback function creates a number of O3DE components that are necessary to simulate a particular sensor. Additionally, it parses the robot description file to read certain processing parameters. + +Your second task is to implement your desired simulation behavior in an O3DE component, which would be created by the Robot Importer. Finally, you need to define and register your _hook_ via the _SerializeContext_ reflection system using `SensorImporterHooks` attribute tag. This allows the Robot Importer to find and add your _hook_ to the mapping. The registration can be done in any O3DE editor component and multiple _hooks_ can be registered at once. For simplicity, you might want to add the registration directly to your O3DE component. A sample code implementing the registration scheme can be as follows: +```cpp +void YourO3DEEditorComponent::Reflect(AZ::ReflectContext* context) +{ + if (auto serializeContext = azrtti_cast(context)) + { + const ROS2::SDFormat::SensorImporterHook& yourImporterHook = YourMethodToCreateHook(); + const ROS2::SDFormat::SensorImporterHook& anotherImporterHook = YourAnotherMethodToCreateHook(); + serializeContext->Class() + ->Attribute( + "SensorImporterHooks", + ROS2::SDFormat::SensorImporterHooksStorage{ AZStd::move(yourImporterHook), AZStd::move(anotherImporterHook) }); + } + // more reflection code goes here +} +``` + +