Warehouse Scene Creation Guidelines (#325)

* Warehouse Scene Creation Guidelines

Signed-off-by: Paweł Budziszewski <[email protected]>
Co-authored-by: Adam Dąbrowski <[email protected]>
Co-authored-by: Piotr Jaroszek <[email protected]>

.gitattributes

@@ -126,6 +126,7 @@ Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/marmoset_bake.tbs
 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/WarehouseAssets/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
 Templates/Ros2FleetRobotTemplate/Screenshots/*.png filter= diff= merge= -text

Gems/WarehouseAssets/README.md

@@ -1,17 +1,19 @@
-## Warehouse Assets Gem
+# Warehouse Assets Gem
 
 ![](docs/images/WarehouseGem.png)
 
-### General description
+## General description
 
 This gem contains a set of models and prefabs which can be used to create a warehouse project suitable for robotic simulations.
 
-### Contents
+> 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.
+
+## Contents
 
 All of the contents of this gem reside in the folder `Assets`. It comprises 2 sub-folders:
 
-- `assets` containing models, textures, and material definitions
-- `Prefabs` containing prefabs that can be used to build the scene
+- `assets` containing models, textures, and material definitions,
+- `Prefabs` containing prefabs that can be used to build the scene.
 
 The `Prefabs` folder has the following structure:
 
@@ -19,7 +21,7 @@ The `Prefabs` folder has the following structure:
 
 All the prefabs have appropriate physics parameters including collision shapes.
 
-#### Basic Components
+### Basic Components
 
 ![](docs/images/Components.png)
 
@@ -31,7 +33,7 @@ A set of basic items to be used in the warehouse is located in the `Components`
 - `WarehouseBox3.prefab`
 - `WarehouseBox4.prefab`
 
-#### Storage Racks
+### Storage Racks
 
 ![](docs/images/StorageRacks.png)
 
@@ -43,7 +45,7 @@ Storage racks are created from basic components, combined in 5 different permuta
 - `Storage_rack4.prefab`
 - `Storage_rack5.prefab`
 
-#### Storage Rack Packs
+### Storage Rack Packs
 
 ![](docs/images/StorageRackPacks.png)
 
@@ -53,13 +55,13 @@ The rack packs were created by stacking 4 storage rack prefabs in different comb
 - `Storage_2x2_Pack2.prefab`
 - `Storage_2x2_Pack3.prefab`
 
-#### Storage on Wheels
+### Storage on Wheels
 
 ![](docs/images/StorageOnWheels.png)
 
 `Storage_on_wheels.prefab` is a storage cage on wheels. As opposed to other prefabs it can be moved around the scene. The collision shape was designed in a way, that allows the Proteus robot to ride below it.
 
-#### Rack protection
+### Rack protection
 
 ![](docs/images/RackProtection.png)
 
@@ -68,11 +70,11 @@ There are 2 elements, located in the `Rack_protectors` folder, that can be place
 - `Rack_front_protection.prefab`
 - `Rack_side_protection.prefab`
 
-#### Misc
+### Misc
 
 The `Misc` folder contains prefabs with floor lines.
 
-#### Warehouse structural
+### Warehouse structural
 
 The `Warehouse_structural` folder contains prefabs comprising the warehouse building. These are:
 
@@ -82,15 +84,37 @@ The `Warehouse_structural` folder contains prefabs comprising the warehouse buil
 
 The folder contains also a `Components` subfolder, containing assets used in these 3 prefabs.
 
-#### Warehouse scene
+### Warehouse scene
 
 ![](docs/images/WarehouseScene.png)
 
-The `WarehouseScene.prefab` contains a sample, ready-to-use warehouse scene, built from prefabs listed in this document.
+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:
+
+![](docs/images/WarehouseSceneStructure.png)
+
+- `Global_illumination` contains lights imitating global illumination and `Reflection Probe` objects.
+- `Storage_markings` contains number boards on storage racks.
+- `Floor_markings` contains decal objects with floor lines.
+- `Movables` contains `Storage_on_wheels` prefabs.
+- `Floor_tire_traces` contains decal objects with tire traces.
+- `Storage_racks` contains storage racks arranged in 2 groups:
+  - `Unpacked` with `Storage_rack` prefabs.
+  - `Packs` with `Storage_2x2_Pack` prefabs.
+- `Rack_protectors` contains rack protection prefabs.
+
+These objects are followed by instances of warehouse structural assets:
+
+- `Warehouse_Floor.prefab`
+- `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:
+
+![](docs/images/WarehouseSceneSampleTree.png)
 
-### Tips on using Warehouse Assets Gem
+## Tips on using Warehouse Assets Gem
 
-#### Creating Warehouse scene
+### Creating Warehouse scene
 
 ***Tip 1***
 
@@ -100,21 +124,21 @@ To achieve alignment, all 3 "structural" prefabs (floor, walls and roof) should
 
 Each of the frontal walls in the `Warehouse_Walls.prefab` contains optional gate openings and gates. It consists of 3 entities:
 
-- `Front_no_gates` - solid wall without opening
-- `Front_gate` - wall with gate opening
-- `Gate` - gate matching the opening
+- `Front_no_gates` - solid wall without opening,
+- `Front_gate` - wall with gate opening,
+- `Gate` - gate matching the opening.
 
 Each of them can be activated or deactivated by enabling or disabling `PhysX Collider` and `Mesh` components. It is possible to obtain one of the following variants:
 
-1. Solid wall - enable `Front_no_gates`, disable the other 2
-2. Open gate - enable `Front_gate`, disable the other 2
-3. closed gate - enable `Front_gate` and `Gate`, disable `Front_no_gates`
+1. Solid wall - enable `Front_no_gates`, disable the other 2.
+2. Open gate - enable `Front_gate`, disable the other 2.
+3. closed gate - enable `Front_gate` and `Gate`, disable `Front_no_gates`.
 
 ***Tip 3***
 
 Warehouses with open gates may be connected by placing them one after another.
 
-#### Visual quality
+### Visual quality
 
 ***Tip 4***
 
@@ -132,7 +156,7 @@ A sample set of parameters can be seen in this image:
 
 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:
 
-1. Open the `WarehouseScene.prefab`
+1. Open the `WarehouseScene.prefab`.
 2. Navigate to `Warehouse/Global_illumination` and locate 2 `Reflection_Probe` entities.
-3. Select each of them, enable the `Reflection Probe` component, and click `Bake Reflection Probe`
+3. Select each of them, enable the `Reflection Probe` component, and click `Bake Reflection Probe`.
 

Templates/Ros2FleetRobotTemplate/docs/scene_creation.md

@@ -0,0 +1,57 @@
+# Warehouse Scene Creation Guidelines
+
+This document describes the process of creating and modifying the warehouse scene which is the basis of the ROS 2 Fleet Template. All the prefabs and assets used in this scene can be found in the [Warehouse Assets Gem](../../../Gems/WarehouseAssets). Before proceeding please take a look at [README](../../../Gems/WarehouseAssets/README.md) of this Gem. You'll find a list of all included objects and some useful tips there.
+
+## Importing the ready-to-use warehouse scene
+
+![](images/warehousescene_prefab.png)
+
+The fastest and simplest way to create your own warehouse scene is to import the `WarehouseScene.prefab`. You can find it in the following location:
+
+![](images/importing_warehousescene_prefab.png)
+
+You can also type WarehouseScene in the search field of the `Pick Prefab` dialog.
+
+> Note: to find out more about instantiating prefabs please refer to [this document](https://www.o3de.org/docs/learning-guide/tutorials/entities-and-prefabs/entity-and-prefab-basics/#instantiate-a-prefab).
+
+For best visual results it is advised to do following things:
+
+- The `WarehouseScene` prefab is equipped with all the necessary lights. Any global or environmental lighting may interfere with internal lights. In particular, if you are creating the scene from scratch using the default O3DE template, you should consider removing all child entities of the `Atom Default Environment/` except for the camera.
+- In the Tips section of the [Warehouse Assets Gem documentation](../../../Gems/WarehouseAssets/README.md) you'll find a description of the camera configuration which will help achieve better visual results.
+
+> Note: the ROS 2 Fleet Template already contains a scene with the `WarehouseScene.prefab` and fully configured camera.
+
+## Modifying the warehouse scene
+
+If you have the `WarehouseScene` prefab on your scene you can easily apply modifications. It is possible to alter virtually any object on the scene, remove it or add a new one. The structure of the `WarehouseScene` prefab contains a few levels of nested prefabs (please refer to [this document](../../../Gems/WarehouseAssets/README.md) for a description). For example, prefabs with boxes are located inside prefabs with storage racks, which are often located in storage packs (containing 4 racks). See the image below.
+
+![](images/WarehouseSceneSampleTree.png)
+
+You can alter objects on each level by removing, scaling or moving any objects. For example, you can:
+
+- re-arrange boxes on shelves by translating and rotating existing ones, or adding new ones,
+- remove boxes from a shelf to make places for different objects,
+- remove the whole storage rack,
+- translate racks to different locations.
+
+Another type of modification concerns the warehouse structure. As described in the [Warehouse Assets Gem README Tips](../../../Gems/WarehouseAssets/README.md), you can easily change frontal walls by replacing the solid wall with open gates. This way you can stack two or more warehouses, one after the other.
+
+![](images/stacked_warehouses1.png)
+
+![](images/stacked_warehouses2.png)
+
+> 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. Simple hint: do not double-click on the prefab in the Entity Outliner. When double-clicking the editor enters focused mode, prefab is highlighted in blue, changes will be saved in the prefab source. 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.
+
+## Creating the warehouse scene
+
+According to your needs, you may also create a custom warehouse using selected assets from the Warehouse Assets Gem. As described in the [Warehouse Assets Gem README](../../../Gems/WarehouseAssets/README.md), the gem contains structural assets defining the building and various objects to be placed inside. Structural assets include 3 prefabs:
+
+- floor,
+- walls with gates,
+- roof with lights.
+
+To achieve alignment, all these prefabs should be instantiated with the same transform (position, rotation and scale). Besides the building structure, the gem provides a set of different objects to be used in the warehouse. These are arranged into prefabs with different levels of nesting. You can import the empty rack and place boxes on it, but you can also instantiate ready-to-use prefab with racks and boxes or pack of 4 racks. Of course, nothing prevents you from modifying such prefabs after instantiating.
+
+![](images/warehouse_assets.png)
+
+> Note: please refer to the [Warehouse Assets Gem README](../../../Gems/WarehouseAssets/README.md) for exact list of objects and instructions.