Skip to content

RFC: changes in simulation Gems and Templates #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

RFC: changes in simulation Gems and Templates #94

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4fa7aa5
Add RFC for changes in simulation Gems and Templates
jhanca-robotecai Mar 4, 2025
b4e1b5e
Code review changes
jhanca-robotecai Mar 17, 2025
3ac5082
Code review changes 2
jhanca-robotecai Mar 17, 2025
23aabbd
Add info about ROS 2 Jazzy and ManipulationTemplate
jhanca-robotecai Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 150 additions & 0 deletions rfcs/RFC Feature - Cleaning up Gems and Templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# RFC Feature - Cleaning up Gems and Templates

## Summary:

This RFC lists a set of proposed changes in simulation-related Gems and project Templates hosted within the [o3de-extras](https://github.com/o3de/o3de-extras) repository. The goal is to discuss and to justify the needed modifications. It is triggered by the issues with the maintenance and testing of the large amount of assets and the codebase with each release.

The RFC briefly describes every simulation-related component that already exists in the repository and lists possible changes. It is important to note that the past releases of the Gems will be stored unchanged.

# Simulation-related Gems

## LevelGeoreferencing Gem

#### Summary
This Gem enables advanced robotics cases, simulation, Earth science, geodesy, cartography, and surveying. It exposes API that simplifies integration with formats like [KML](https://pl.wikipedia.org/wiki/Keyhole_Markup_Language) or [GeoJSON](https://pl.wikipedia.org/wiki/GeoJSON).

#### Proposed changes
No changes.

## ProteusRobot Gem

#### Summary
This Gem contains assets (meshes, textures and ready-to-use *prefabs*) of `Proteus` robot by *Amazon Robotics*.

#### Proposed changes
There are two gems with sample robots: `ProteusRobot` and `RosRobotSample`. Additionally, *Panda Franka* robot is included within `Ros2RoboticManipulationTemplate` project Template. We propose to create a new Gem, `RosRobotSamples`, with three sample robots: `Proteus`, `Panda Franka`, and `Husarion ROSBot XL`.

#### Consequences for users
All projects using `ProteusRobot` Gem will require an easy update: changing the required Gem name. All asset names (*prefabs*) and paths will remain unchanged, but not necessarily names and paths of each low-level asset (a mesh file or a texture). There is a risk that someone in some project uses these. Such project will require manual fixes or the old version of the Gem.

Comment on lines +28 to +29
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this the case? As far as I know, O3DE generates UUIDs and paths based on the 'scan folder' root. Gems can add new scan folder roots via a config file, which means there's likely a way to make sure that at least the relative paths of all the assets (from the scan roots) remain the same. If you need help with this, I can help investigate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review and the comment. I guess we are on the same page with the engine, but I did not put it in the right words.

The paths to the prefabs will remain the same or they will be added to the config file that you mentioned. The same goes for the material files. However, we plan to rename some of the texture files. It is very unlikely someone created their own material file and linked it with the textures from this repo (also due to the problem in the cmake that was recently discovered by us when trying to do the same: o3de/o3de-extras#837 ). Nevertheless, I wanted to point out such possibility in the RFC.

An example for the misleading name within the repository that we want to change:
Warehouse/Textures/WarehouseProps/WarehousePropsMaskMap_A.png
this will be renamed to WarehouseModules_roughness.png (files with _property suffix are discovered automatically by O3DE).

## ROS2 Gem

#### Summary
This Gem is a base for any robotic simulation using O3DE; it implements a ROS 2 node to enable ROS 2 communication and implements O3DE sensor components, such as camera, IMU, GNSS, Lidar, etc. Additionally, it supports the robot control mechanisms (with Ackerman, skid steering, and rigid body models) and joints' manipulation. Finally, it enables importing URDF/SDF robots.

#### Proposed changes
The changes within this Gem will be covered by separate RFCs due to the size of this Gem and the amount of required changes.

## RosRobotSample Gem

#### Summary
This Gem contains assets (meshes, textures and ready-to-use *prefabs*) of `ROSBot XL` robot by *Husarion*.

#### Proposed changes
There are two gems with sample robots: `ProteusRobot` and `RosRobotSample`. Additionally, the *Panda Franka* robot is included in the `Ros2RoboticManipulationTemplate` project template. We propose to create a new Gem, `RosRobotSamples`, with three sample robots: `Proteus`, `Panda Franka`, and `Husarion ROSBot XL`.

#### Impact for users
All projects using `RosRobotSample` Gem will require an easy update: changing the required Gem name. All asset names (*prefabs*) and paths will remain unchanged, but not necessarily names and paths of each low-level asset (a mesh file or a texture). There is a risk that someone in some project uses these. Such project will require manual fixes or the old version of the Gem.

## WarehouseAssets Gem

#### Summary
This Gem contains assets (meshes, textures and ready-to-use *prefabs*) that can be used to create a warehouse project suitable for robotic simulations.

#### Proposed changes
The meshes are not optimized for large warehouse environments and the warehouse elements have fixed sizes. Therefore, the proposed changes will focus on:
- reducing the number of vertices of meshes whenever possible and necessary
- modifying the sizes of warehouse elements to allow building warehouses of different dimensions

#### Impact for users
The existing *prefabs* will be modified in a way, to be interchangeable with the old ones. No actions from the users of `WarehouseAssets` will be needed, unless they do not use low-level assets (a mesh file or a texture) directly. All projects that use these will require manual fixes or the old version of the Gem.

## WarehouseAutomation Gem

#### Summary
This Gem contains assets (meshes, textures and ready-to-use *prefabs*) that can be used to create conveyor belts in warehouse projects suitable for robotic simulations. Additionally, it implements the physics of the conveyor belts and the proximity sensor. The Gem was implemented primarily for [ROSCon2023Demo](https://github.com/RobotecAI/ROSCon2023Demo) project. An example of its use can also be found in [ROS 2 Project Template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2RoboticManipulationTemplate).

#### Proposed changes
The meshes and the implementation of the conveyors are not optimized for large environments, which makes it very difficult to use efficiently. We propose to remove the Gem completely and to move the meaningful elements to other Gems:
- `ConveyorElements` Assets: optimize and move the reusable assets to `WarehouseAssets` Gem
- `ConveyorLine` Assets: optimize and move the reusable assets to `WarehouseAssets` Gem
- `ConveyorBelt` implementation: remove (the physical implementation of the conveyor belt is too computationally expensive)
- `ProximitySensor` implementation: move to `ROS 2` Gem next to `ContactSensor`; make the behavior of the two similar

The detailed list of meshes, textures and *prefabs* that will be copied and removed will be compiled after an agreement to remove the Gem.

#### Impact for users
The users will have to adapt the projects accordingly or use the old version of the Gem. The impact is unknown as the popularity of the Gem is not known, however, the complexity of the Gem hints at the rather low usage. E.g. [ROSCon2023Demo](https://github.com/RobotecAI/ROSCon2023Demo) project contains duplicates of the assets for this reason. On the other hand, the implementation of the belt's physics is used and will have to be either ported or reimplemented.

## WarehouseSample Gem

#### Summary
This Gem contains assets (meshes, textures and ready-to-use *prefabs*) that can be used to create a very simple warehouse project suitable for robotic simulations.

#### Proposed changes
This Gem should be removed completely after `WarehouseAssets` Gem is optimized and can be used to generate a small and lightweight warehouse environment. This proposal is triggered by the fact that the assets in the Gem require some rework after the updates in the engine (in *AssetProcessor*).

#### Impact for users
The users will have to adapt the projects accordingly, or use the old version of the Gem (the old version contains errors when used with future O3DE 2505.x). The impact is unknown as the popularity of the Gem is not known, however, the low quality of the assets (and the incorrect scale) hints that the Gem is not used widely. We will create a set of *prefabs* with the same names in `WarehouseAssets` Gem to minimize the impact of this change.

# Project templates

## Ros2FleetRobotTemplate project Template

#### Summary
This template was created to allow a quick start of a robotic simulation in a warehouse environment with multiple autonomous mobile robots (AMRs). The template is built based on `WarehouseAssets` and `ProteusRobot` Gems.

#### Proposed changes
No changes other than updates triggered by the proposed changes in the `WarehouseAssets` and the newly created `RosRobotSamples` Gems.

## Ros2ProjectTemplate project Template

#### Summary
This template was created to allow a quick start of a robotic simulation. It was meant to be the quickest to build and consume the least resources. The template is built based on `WarehouseSample` and `RosRobotSample` Gems.

#### Proposed changes
The template should be completely recreated based on `WarehouseAssets` and the newly created `RosRobotSamples` Gems.
Alternatively, the template could be completely removed and added to `Ros2FleetRobotTemplate` as a *default* level (the `Ros2FleetRobotTemplate` would contain two levels, for single- and multi-robot simulations).

## Ros2RoboticManipulationTemplate project Template

#### Summary
This template was created to allow a quick start of a robotic simulation in a warehouse environment with two different robotic arms. The template includes a large collection of assets (meshes, textures and ready-to-use *prefabs*).

#### Proposed changes
There are two levels in the template: `RoboticManipulation` and `RoboticPalletization`. The template will be reduced to the first one only for simplicity. The level itself will be updated, and the assets will be moved to the other Gems for reusability when necessary. The second level, `RoboticPalletization`, will be removed alongside some assets used within this level. This will remove duplicates: the conveyor belts are also located in `WarehouseAutomation` Gem; the further improved *Universal Robots UR10* robot is stored in the external [o3de-ur-robots-gem](https://github.com/RobotecAI/o3de-ur-robots-gem) repository. The decision to remove this level is based on the fact that the robot is navigated using the _launcher_ scripts from the external repositories. It does not work correctly with ROS 2 Jazzy, and it is a hustle to maintain.

The more detailed list of changes in assets:
- `BoxToyPuzzle` - assets will be simplified (textures are too detailed) and kept in the template
- `ConveyorLine` - assets will be removed
- `Gripper` - assets will be moved to the newly created `RosRobotSamples` Gem
- `Room` - assets will be simplified (textures are too detailed), materials will be corrected (the room is not visually pleasant) and kept in the template
- `UR10` - assets will be removed
- `UrdfImporter/panda` - assets will be moved to the newly created `RosRobotSamples` Gem
- unused `DiffuseProbeGrids` will be removed

# Conclusions

## What are the advantages of the feature?

The changes described in this RFC will simplify the maintenance of the existing assets in the [o3de-extras](https://github.com/o3de/o3de-extras) repository. More importantly, the names and the content will be easier to understand by the users, and the number of Gems will be reduced.

## What are the disadvantages of the feature?

Some assets will be moved between Gems and some names will change. The names and paths of the *prefab* will be kept, but not necessarily names and paths of each asset. Some assets will be removed. There is a risk that someone in some project uses low-level assets (a mesh file or a texture). Such project will require manual fixes or old versions of some Gems.

### How will this be implemented or integrated into the O3DE environment?

All Gems and Templates described in this RFC are already integrated into O3DE environment.

### Are there any alternatives to this feature?

This RFC describes changes in the structure of the existing data. It is highly possible that other developers might have different opinions on the best structure for such assets. Please file your comments below if you believe some changes should be made.

### How will users learn this feature?
- Documentation in [o3de.org](o3de.org) and Release Notes of O3DE.
- Discord social platform of O3DE.
- Posts by O3DE and Robotec.ai in their social media.

### Are there any open questions?