Update documentation in gems (#633)

* update ProteusRobot and RosRobotSample gems docs
* update WarehouseSample readme
* add WarehouseAutomation gem readme
* code review
* fix ROS2 -> ROS 2
* code review: add readme images
---------
Signed-off-by: Jan Hanca <[email protected]>
Co-authored-by: Adam Dąbrowski <[email protected]>

.gitattributes

@@ -124,7 +124,11 @@ Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/Lucy_low.fbx filter=lf
 Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/marmoset_bake.tbscene filter=lfs diff=lfs merge=lfs -text
 Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/Brass/brass_bake.spp filter=lfs diff=lfs merge=lfs -text
 Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/stone/stone_bake.spp filter=lfs diff=lfs merge=lfs -text
+Gems/ProteusRobot/docs/images/*.png filter= diff= merge= -text
+Gems/RosRobotSample/docs/images/*.png filter= diff= merge= -text
+Gems/WarehouseAutomation/docs/images/*.png filter= diff= merge= -text
 Gems/WarehouseAssets/docs/images/*.png filter= diff= merge= -text
+Gems/WarehouseSample/docs/images/*.png filter= diff= merge= -text
 Templates/Ros2FleetRobotTemplate/docs/images/*.png filter= diff= merge= -text
 Gems/ROS2/docs/**/*.png -filter -diff -merge
 Templates/Ros2ProjectTemplate/Screenshots/*.png filter= diff= merge= -text

Gems/ProteusRobot/README.md

@@ -0,0 +1,30 @@
+[![Apache License, Version 2.0][apache_shield]][apache]
+
+# Proteus Robot Gem for Open 3D Engine (O3DE)
+
+## Requirements
+- Any O3DE project with the [ROS 2 Gem](https://docs.o3de.org/docs/user-guide/interactivity/robotics/) enabled.
+
+Please refer to [O3DE documentation](https://docs.o3de.org/docs/user-guide/gems/) to learn more about Gems and about registering Gems in the system and O3DE projects.
+
+## Description
+This is an Asset Gem. It contains a simplified model of [Proteus Robot](https://robotsguide.com/robots/proteus) - an autonomous mobile robot that can pick up, transport, and drop off containers. It is delivered as a ready-to-use O3DE prefab, `Proteus.prefab`, containing visual models, physics and the following ROS 2 components:
+- `ROS2 Frame`
+- `ROS2 Robot Control`
+- `ROS2 Skid Steering Twist Control`
+- `ROS2 Lidar Sensor`
+
+Additionally, the model is equipped with links that are suitable for adding `Camera` and `Imu` sensors.
+
+The robot publishes Lidar Sensor's output on the`/base_link/pc` ROS 2 topic and can be driven using the `/base_link/cmd_vel` ROS 2 topic. An example of its use can be found in [ROS 2 Project Template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2FleetRobotTemplate).
+
+## Screenshots
+![](docs/images/front.png)
+![](docs/images/back.png)
+
+## Acknowledgments
+This work is licensed under [Apache License, Version 2.0][apache]. You may elect at your option to use the [MIT License][mit] instead. Contributions must be made under both licenses.
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[mit]: https://opensource.org/licenses/MIT
+[apache_shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg

Gems/ProteusRobot/gem.json

@@ -2,10 +2,10 @@
     "gem_name": "ProteusRobot",
     "version": "1.0.0",
     "display_name": "Proteus Robot",
-    "license": "Apache-2.0",
+    "license": "Apache-2.0 or MIT",
     "license_url": "https://opensource.org/licenses/Apache-2.0",
     "origin": "RobotecAI",
-    "origin_url": "https://github.com/o3de/o3de-extras/tree/development/Gems/ProteusRobot",
+    "origin_url": "https://robotec.ai",
     "type": "Asset",
     "summary": "Proteus warehouse robot with Lidar sensor",
     "canonical_tags": [
@@ -18,15 +18,17 @@
         ""
     ],
     "icon_path": "preview.png",
-    "requirements": "Requires ROS 2 Gem for the Lidar to function",
+    "requirements": "Requires ROS 2 Gem",
     "documentation_url": "https://www.o3de.org/docs/user-guide/interactivity/robotics/project-configuration/#ros-2-project-templates",
-    "dependencies": [],
+    "dependencies": [
+        "ROS2==2.0.0"
+    ],
     "repo_uri": "https://raw.githubusercontent.com/o3de/o3de-extras/development",
-     "compatible_engines": [
+    "compatible_engines": [
         "o3de-sdk>=1.2.0",
         "o3de>=1.2.0"
     ],
     "engine_api_dependencies": [],
     "restricted": "ProteusRobot",
     "download_source_uri": "https://github.com/o3de/o3de-extras/releases/download/2.0/proteusrobot-1.0.0-gem.zip"
-}
+}

Gems/RosRobotSample/README.md

@@ -1,9 +1,34 @@
-# ROS 2 Robot Sample
+[![Apache License, Version 2.0][apache_shield]][apache]
 
-This gem contains a sample robot asset, ready to be used with the ROS 2 Gem. 
+# Ros Robot Sample Gem for Open 3D Engine (O3DE)
 
-The robot is delivered as a ready to use prefab containing models, physics and following ROS 2 components:
-- Frame
-- Robot Control
-- Twist Control
-- Lidar Sensor
+## Requirements
+- Any O3DE project with the [ROS 2 Gem](https://docs.o3de.org/docs/user-guide/interactivity/robotics/) enabled.
+
+Please refer to [O3DE documentation](https://docs.o3de.org/docs/user-guide/gems/) to learn more about Gems and about registering Gems in the system and O3DE projects.
+
+## Description
+This is an Asset Gem. It contains the [Husarion ROSbot XL](https://husarion.com/manuals/rosbot-xl/) robot - an autonomous mobile robot platform developed by [Husarion](https://husarion.com). The robot is delivered as a ready-to-use prefab, `ROSbot.prefab`, containing visual models, physics and the following ROS 2 components:
+- `ROS2 Frame`
+- `ROS2 Robot Control`
+- `ROS2 Skid Steering Twist Control`
+
+Additionally, the model is equipped with links that are suitable for adding `Camera` and `Imu` sensors. There are two extra O3DE prefabs with 2D and 3D LiDAR sensors attached: `ROSBot_slamtec.prefab` and `ROSbot_velodyne.prefab` with Slamtec RPLIDAR S1 and Velodyne Puck VLP-16 sensors respectively. The components are visualized with the corresponding meshes. 
+
+The robot publishes Lidar Sensor's output on the`/base_link/pc` ROS 2 topic and can be driven using the `/base_link/cmd_vel` ROS 2 topic. An example of its use can be found in [ROS 2 Project Template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2ProjectTemplate).
+
+## Screenshots
+![](docs/images/front.png)
+From left: `ROSbot_velodyne.prefab`, `ROSBot_slamtec.prefab`, and `ROSbot.prefab`
+
+![](docs/images/back.png)
+From left: `ROSbot.prefab`, `ROSBot_slamtec.prefab`, and `ROSbot_velodyne.prefab`
+
+## Acknowledgments
+This work is licensed under [Apache License, Version 2.0][apache]. You may elect at your option to use the [MIT License][mit] instead. Contributions must be made under both licenses.
+
+Models were created based on STL and URDF files kindly shared by Husarion.
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[mit]: https://opensource.org/licenses/MIT
+[apache_shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg

Gems/RosRobotSample/gem.json

@@ -3,10 +3,10 @@
     "display_name": "ROS Robot Sample",
     "license": "Apache-2.0 or MIT",
     "license_url": "https://opensource.org/licenses/Apache-2.0",
-    "origin": "Ros2WarehouseDemo",
-    "origin_url": "https://github.com/o3de/o3de-extras/tree/main/Gems/RosRobotSample",
+    "origin": "RobotecAI",
+    "origin_url": "https://robotec.ai",
     "type": "Asset",
-    "summary": "This project contains a sample robot asset",
+    "summary": "Husarion ROSbot XL robot assets.",
     "canonical_tags": [
         "Gem"
     ],
@@ -17,10 +17,10 @@
         "Linux"
     ],
     "icon_path": "preview.png",
-    "requirements": "",
+    "requirements": "Requires ROS 2 Gem",
     "documentation_url": "",
     "dependencies": [
-        "ROS2"
+        "ROS2==2.0.0"
     ],
     "compatible_engines": [
         "o3de-sdk>=1.2.0",
@@ -30,4 +30,4 @@
     "restricted": "",
     "download_source_uri": "https://github.com/o3de/o3de-extras/releases/download/2.0/rosrobotsample-1.0.0-gem.zip",
     "version": "1.0.0"
-}
+}

Gems/WarehouseAssets/README.md

@@ -4,7 +4,7 @@
 
 ## General description
 
-This gem contains a set of models and prefabs which can be used to create a warehouse project suitable for robotic simulations.
+This gem contains a set of models and prefabs that can be used to create a warehouse project suitable for robotic simulations.
 
 > Note: in O3DE there are 2 ways you can alter instantiated prefab: by changing prefab instance or prefab definition (source). If you modify prefab source, all instances will be altered. Thus unless you really know what you are doing, you should edit instances only. Please refer to [this document](https://www.o3de.org/docs/learning-guide/tutorials/entities-and-prefabs/entity-and-prefab-basics/) to learn about working with prefabs.
 
@@ -88,7 +88,7 @@ The folder contains also a `Components` subfolder, containing assets used in the
 
 ![](docs/images/WarehouseScene.png)
 
-The `WarehouseScene.prefab` contains a sample, ready-to-use warehouse scene, built from prefabs listed in this document. It is built as a tree of assets and prefabs defining each element of the warehouse. The top-level objects are shown on the following image:
+The `WarehouseScene.prefab` contains a sample, ready-to-use warehouse scene, built from prefabs listed in this document. It is built as a tree of assets and prefabs defining each element of the warehouse. The top-level objects are shown in the following image:
 
 ![](docs/images/WarehouseSceneStructure.png)
 
@@ -108,7 +108,7 @@ These objects are followed by instances of warehouse structural assets:
 - `Warehouse_Walls.prefab`
 - `Warehouse_Roof.prefab`
 
-The structure of prefabs in the warehouse scene is highly nested. For example, location of one of boxes in the structure looks like this:
+The structure of prefabs in the warehouse scene is highly nested. For example, the location of one of the boxes in the structure looks like this:
 
 ![](docs/images/WarehouseSceneSampleTree.png)
 
@@ -154,7 +154,7 @@ A sample set of parameters can be seen in this image:
 
 ***Tip 5***
 
-The `WarehouseScene.prefab` is equipped with 2 Reflection Probes, which can be found in: `Warehouse/Global_illumination/Reflection_Probe`. To work correctly, Reflection Probes require baked materials, thus are disabled by default. For a better visual experience, it is advised to enable them. To do so follow these steps:
+The `WarehouseScene.prefab` is equipped with 2 Reflection Probes, which can be found in `Warehouse/Global_illumination/Reflection_Probe`. To work correctly, Reflection Probes require baked materials and, as such, are disabled by default. For a better visual experience, it is advised to enable them. To do so follow these steps:
 
 1. Open the `WarehouseScene.prefab`.
 2. Navigate to `Warehouse/Global_illumination` and locate 2 `Reflection_Probe` entities.

Gems/WarehouseAutomation/README.md

@@ -0,0 +1,47 @@
+[![Apache License, Version 2.0][apache_shield]][apache]
+
+# Warehouse Automation Gem for Open 3D Engine (O3DE)
+
+## Requirements
+- Any O3DE project with the [ROS 2 Gem](https://docs.o3de.org/docs/user-guide/interactivity/robotics/) enabled.
+
+Please refer to [O3DE documentation](https://docs.o3de.org/docs/user-guide/gems/) to learn more about Gems and about registering Gems in the system and O3DE projects.
+
+## Description
+This Gem contains a set of models and prefabs with underlying O3DE components that can be used to create a warehouse simulation scene. It includes a conveyor belt with visuals and physical simulation as well as a proximity sensor that can be used to stop the belt, such as when transported goods reach a certain position. The conveyor belt is built from smaller pieces that can be put together in any configuration, allowing for twists and turns. Additionally, this Gem includes a sample palletizer configuration, in which one conveyor belt splits and feeds into two pick-up stations for robotic arms, and an extra roller conveyor for putting aside goods.
+
+The following assets are available in the Gem as O3DE prefabs:
+- `./Assets/Factory/ConveyorLine.prefab` - a sample palletizer configuration
+- `./Assets/Factory/ConveyorElements/ConveyorSegments_Turnout.prefab` - conveyor belt's element that splits into two and allows for goods distribution using a mechanized flap
+- `./Assets/Factory/ConveyorElements/ConveyorSegments_Straight.prefab` - conveyor belt's straight element
+- `./Assets/Factory/ConveyorElements/ConveyorSegments_Turn_90.prefab` - conveyor belt's turn element (90 degrees)
+- `./Assets/Factory/ConveyorElements/ConveyorSegments_End.prefab` - conveyor belt's end element with an extra flap to keep transported goods positioned
+
+Images of all prefabs are given in the next section.
+
+The proximity sensor is an O3DE component with no corresponding visualization. It uses `AzPhysics::RayCastRequest` to check for collisions in its range and returns continuously the result of this test via `ProximitySensorNotificationBus`. Any O3DE component can connect to this bus and react to certain events. The sensor and the bus are also available for scripting in [ScriptCanvas](https://docs.o3de.org/docs/user-guide/scripting/script-canvas/). It is possible to set the frequency and the range of the sensor. The visualization beam can be disabled.
+
+The Gem was implemented primarily for [ROSCon2023Demo](https://github.com/RobotecAI/ROSCon2023Demo) project. An example of its use can be also found in [ROS 2 Project Template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2RoboticManipulationTemplate).
+
+## Screenshots
+
+### Conveyor belt parts
+![](docs/images/conveyor.png)
+![](docs/images/conveyor2.png)
+From left: `ConveyorSegments_End.prefab`, `ConveyorSegments_Turn_90.prefab`, `ConveyorSegments_Turnout.prefab`, and `ConveyorSegments_Straight.prefab`
+
+### Sample palletizer configuration
+![](docs/images/palletizer.png)
+![](docs/images/palletizer2.png)
+Sample palletizer configuration with conveyor belt split into two pick-up stations (no robotic arms available in this Gem) and a roller conveyor for pallets.
+
+### Proximity sensor
+![](docs/images/proximity.png)
+Three instances of proximity sensors with a cube mesh primitive used for visualization. Note different range configurations between the left and the middle sensors. The beam of the right sensor is green due to the detection of a sample box.
+
+## Acknowledgments
+This work is licensed under [Apache License, Version 2.0][apache]. You may elect at your option to use the [MIT License][mit] instead. Contributions must be made under both licenses.
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[mit]: https://opensource.org/licenses/MIT
+[apache_shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg

Gems/WarehouseAutomation/gem.json

@@ -1,11 +1,11 @@
 {
     "version": "1.0.0",
     "gem_name": "WarehouseAutomation",
-    "display_name": "WarehouseAutomation",
+    "display_name": "Warehouse Automation",
     "license": "Apache-2.0",
     "license_url": "https://opensource.org/licenses/Apache-2.0",
     "origin": "RobotecAI",
-    "origin_url": "https://github.com/o3de/o3de-extras/development/Gems/WarehouseAutomation",
+    "origin_url": "https://robotec.ai",
     "type": "Code",
     "summary": "Gem for simulating an automated warehouse or factory",
     "canonical_tags": [
@@ -29,4 +29,4 @@
     ],
     "repo_uri": "https://github.com/o3de/o3de-extras",
     "restricted": "WarehouseAutomation"
-}
+}

Gems/WarehouseSample/README.md

@@ -0,0 +1,25 @@
+[![Apache License, Version 2.0][apache_shield]][apache]
+
+# WarehouseSample Gem for Open 3D Engine (O3DE)
+
+## Installation
+Please refer to [O3DE documentation](https://docs.o3de.org/docs/user-guide/gems/) to learn more about Gems and about registering Gems in the system and O3DE projects.
+
+## Description
+This is an Asset Gem. It contains the sample warehouse asset that was developed for [ROS2 Project Template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2ProjectTemplate). The asset is stored as a separate Gem to make it reusable in other projects, is it available as an O3DE prefab `Warehouse.prefab` stored in `Assets/O3DEScene/Prefabs` folder.
+
+The warehouse consists of two rooms and some space outside of the building. Please note, that the whole asset is scaled down, i.e., the dimensions of the building are relatively small for most applications.
+
+## Screenshots
+![](docs/images/outside.png)
+![](docs/images/inside1.png)
+![](docs/images/inside2.png)
+
+## Acknowledgments
+This work is licensed under [Apache License, Version 2.0][apache]. You may elect at your option to use the [MIT License][mit] instead. Contributions must be made under both licenses.
+
+The warehouse models are based on CC0 asset available [online](https://www.blendswap.com/blend/21850).
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[mit]: https://opensource.org/licenses/MIT
+[apache_shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg

Gems/WarehouseSample/gem.json

@@ -3,10 +3,10 @@
     "display_name": "WarehouseSample",
     "license": "Apache-2.0 or MIT",
     "license_url": "https://opensource.org/licenses/Apache-2.0",
-    "origin": "WarehouseSample",
-    "origin_url": "https://github.com/o3de/o3de-extras/tree/main/Gems/WarehouseSample",
+    "origin": "RobotecAI",
+    "origin_url": "https://robotec.ai",
     "type": "Asset",
-    "summary": "This project contains a Warehouse sample scene",
+    "summary": "This Gem contains a Warehouse sample scene",
     "canonical_tags": [
         "Gem"
     ],
@@ -28,4 +28,4 @@
     "restricted": "",
     "download_source_uri": "https://github.com/o3de/o3de-extras/releases/download/2.0/warehousesample-1.0.0-gem.zip",
     "version": "1.0.0"
-}
+}