diff --git a/pr-120/404.html b/pr-120/404.html index 34607b988..1dd191d64 100644 --- a/pr-120/404.html +++ b/pr-120/404.html @@ -1862,6 +1862,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Clock/ClockPublisher/index.html b/pr-120/Components/Clock/ClockPublisher/index.html index 133800fa4..e9d6b91a0 100644 --- a/pr-120/Components/Clock/ClockPublisher/index.html +++ b/pr-120/Components/Clock/ClockPublisher/index.html @@ -1969,6 +1969,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AWSIMEnvironment/index.html b/pr-120/Components/Environment/AWSIMEnvironment/index.html index c8a98072d..46515150a 100644 --- a/pr-120/Components/Environment/AWSIMEnvironment/index.html +++ b/pr-120/Components/Environment/AWSIMEnvironment/index.html @@ -2051,6 +2051,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AddNewEnvironment/AddEnvironment/index.html b/pr-120/Components/Environment/AddNewEnvironment/AddEnvironment/index.html index a74069455..7550e43d3 100644 --- a/pr-120/Components/Environment/AddNewEnvironment/AddEnvironment/index.html +++ b/pr-120/Components/Environment/AddNewEnvironment/AddEnvironment/index.html @@ -2015,6 +2015,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/index.html b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/index.html index 1eb41472b..5f9f0628b 100644 --- a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/index.html +++ b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/index.html @@ -1945,6 +1945,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/index.html b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/index.html index f951d48d2..b537957fb 100644 --- a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/index.html +++ b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/index.html @@ -1960,6 +1960,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/index.html b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/index.html index 9c76fc1b5..a55588751 100644 --- a/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/index.html +++ b/pr-120/Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/index.html @@ -2105,6 +2105,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/AddNewEnvironment/AddTrafficLights/index.html b/pr-120/Components/Environment/AddNewEnvironment/AddTrafficLights/index.html index 068fd70a1..066f27cb2 100644 --- a/pr-120/Components/Environment/AddNewEnvironment/AddTrafficLights/index.html +++ b/pr-120/Components/Environment/AddNewEnvironment/AddTrafficLights/index.html @@ -1967,6 +1967,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/CreatePCD/index.html b/pr-120/Components/Environment/CreatePCD/index.html index 9502fad71..472d1eb40 100644 --- a/pr-120/Components/Environment/CreatePCD/index.html +++ b/pr-120/Components/Environment/CreatePCD/index.html @@ -2072,6 +2072,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/LaneletBoundsVisualizer/index.html b/pr-120/Components/Environment/LaneletBoundsVisualizer/index.html index 6d0c80b1c..ec16e3808 100644 --- a/pr-120/Components/Environment/LaneletBoundsVisualizer/index.html +++ b/pr-120/Components/Environment/LaneletBoundsVisualizer/index.html @@ -1931,6 +1931,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/SmokeSimulator/index.html b/pr-120/Components/Environment/SmokeSimulator/index.html index d8f824ca2..4c756fafc 100644 --- a/pr-120/Components/Environment/SmokeSimulator/index.html +++ b/pr-120/Components/Environment/SmokeSimulator/index.html @@ -1931,6 +1931,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Environment/V2I/index.html b/pr-120/Components/Environment/V2I/index.html index 0c2aa9762..6f0a02a00 100644 --- a/pr-120/Components/Environment/V2I/index.html +++ b/pr-120/Components/Environment/V2I/index.html @@ -1973,6 +1973,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/ROS2/AddACustomROS2Message/index.html b/pr-120/Components/ROS2/AddACustomROS2Message/index.html index 913490232..263a53d7c 100644 --- a/pr-120/Components/ROS2/AddACustomROS2Message/index.html +++ b/pr-120/Components/ROS2/AddACustomROS2Message/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/ROS2/ROS2ForUnity/index.html b/pr-120/Components/ROS2/ROS2ForUnity/index.html index b5b9557c3..75c29f06c 100644 --- a/pr-120/Components/ROS2/ROS2ForUnity/index.html +++ b/pr-120/Components/ROS2/ROS2ForUnity/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/ROS2/ROS2TopicList/index.html b/pr-120/Components/ROS2/ROS2TopicList/index.html index bb6b63910..bd69b77fd 100644 --- a/pr-120/Components/ROS2/ROS2TopicList/index.html +++ b/pr-120/Components/ROS2/ROS2TopicList/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/index.html b/pr-120/Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/index.html index 4f793ae0c..3e0173c4f 100644 --- a/pr-120/Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/index.html +++ b/pr-120/Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/index.html b/pr-120/Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/index.html index 5c4ee95e2..6a4d562e9 100644 --- a/pr-120/Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/index.html +++ b/pr-120/Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/CameraSensor/index.html b/pr-120/Components/Sensors/CameraSensor/index.html index 5c6308b00..e625c9e65 100644 --- a/pr-120/Components/Sensors/CameraSensor/index.html +++ b/pr-120/Components/Sensors/CameraSensor/index.html @@ -1988,6 +1988,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/GNSSSensor/index.html b/pr-120/Components/Sensors/GNSSSensor/index.html index 73ec827e1..70aeb8a72 100644 --- a/pr-120/Components/Sensors/GNSSSensor/index.html +++ b/pr-120/Components/Sensors/GNSSSensor/index.html @@ -1997,6 +1997,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/IMUSensor/index.html b/pr-120/Components/Sensors/IMUSensor/index.html index 80580552b..c6937f624 100644 --- a/pr-120/Components/Sensors/IMUSensor/index.html +++ b/pr-120/Components/Sensors/IMUSensor/index.html @@ -1973,6 +1973,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/LiDARSensor/AddNewLiDAR/index.html b/pr-120/Components/Sensors/LiDARSensor/AddNewLiDAR/index.html index 78f8324e8..01cf23af8 100644 --- a/pr-120/Components/Sensors/LiDARSensor/AddNewLiDAR/index.html +++ b/pr-120/Components/Sensors/LiDARSensor/AddNewLiDAR/index.html @@ -1940,6 +1940,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/LiDARSensor/LiDARSensor/index.html b/pr-120/Components/Sensors/LiDARSensor/LiDARSensor/index.html index 14ae052af..03ca6ea05 100644 --- a/pr-120/Components/Sensors/LiDARSensor/LiDARSensor/index.html +++ b/pr-120/Components/Sensors/LiDARSensor/LiDARSensor/index.html @@ -2030,6 +2030,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/LiDARSensor/RGLUnityPlugin/index.html b/pr-120/Components/Sensors/LiDARSensor/RGLUnityPlugin/index.html index d73c493cc..ec8cac152 100644 --- a/pr-120/Components/Sensors/LiDARSensor/RGLUnityPlugin/index.html +++ b/pr-120/Components/Sensors/LiDARSensor/RGLUnityPlugin/index.html @@ -1970,6 +1970,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/LiDARSensor/ReadMaterialInformation/index.html b/pr-120/Components/Sensors/LiDARSensor/ReadMaterialInformation/index.html index 7a24b162f..82d85da3f 100644 --- a/pr-120/Components/Sensors/LiDARSensor/ReadMaterialInformation/index.html +++ b/pr-120/Components/Sensors/LiDARSensor/ReadMaterialInformation/index.html @@ -1942,6 +1942,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Sensors/VehicleStatusSensor/index.html b/pr-120/Components/Sensors/VehicleStatusSensor/index.html index 6ca690c2a..6ce9acf91 100644 --- a/pr-120/Components/Sensors/VehicleStatusSensor/index.html +++ b/pr-120/Components/Sensors/VehicleStatusSensor/index.html @@ -1964,6 +1964,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Traffic/NPCs/Pedestrian/index.html b/pr-120/Components/Traffic/NPCs/Pedestrian/index.html index e532fd748..9896d0ce4 100644 --- a/pr-120/Components/Traffic/NPCs/Pedestrian/index.html +++ b/pr-120/Components/Traffic/NPCs/Pedestrian/index.html @@ -11,7 +11,7 @@ - + @@ -1871,6 +1871,27 @@ + + +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + @@ -2803,7 +2824,7 @@

    Collider - +
    @@ -2813,7 +2834,7 @@

    Collider - Add Random Traffic Environment + Spawn NPCs from RVIZ

    diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-1.png b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-1.png new file mode 100644 index 000000000..d60cd3c83 Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-1.png differ diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-2.png b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-2.png new file mode 100644 index 000000000..c332e76cd Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image-2.png differ diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image.png b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image.png new file mode 100644 index 000000000..e3dd7df58 Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/image.png differ diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/index.html b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/index.html new file mode 100644 index 000000000..e79cf366c --- /dev/null +++ b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/index.html @@ -0,0 +1,2653 @@ + + + + + + + + + + + + + + + + + + + + + + + + + Spawn NPCs from RVIZ - AWSIM Labs Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + + + + + +
    + + + + +
    + +
    + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + + + +

    Spawn NPCs from RVIZ

    + +

    Introduction#

    +

    This feature allows you to spawn NPCs (pedestrians, cars, buses) in the Unity scene (AWSIM) from Autoware (RVIZ). It includes bulk deletion, vehicle velocity specification, and ensures NPC vehicles move straight, only colliding with the ground.

    +

    Setup#

    +

    You can change the configuration of the NPCs in the RVIZNPCSpawner component in AWSIM. It is attached to the Environment game object in the AutowareSimulation scene. You can also attach the RVIZNPCSpawner to any other game object and set all the required values in your custom scene.

    +
      +
    1. +

      Attach the RVIZNPCSpawner component to one of the game objects in the scene. By default, it's attached to Environment.

      +
      2. +
    2. +

      In AWSIM, you can add more cars (smaller vehicles) or buses (large vehicles) in the Npc Car prefabs / Npc Bus prefabs lists respectively.

      +
      3. +
    3. +

      Then, select the parent objects under which the Pedestrians or Vehicles will be spawned.

      +
      4. +
    4. +

      Finally, adjust the Despawn time to destroy the NPCs after a delay.

      +
      5. +
    +

    alt text

    +

    Spawning NPCs from Autoware#

    +
      +
    1. +

      Open up Autoware.

      +
      2. +
    2. +

      Click the 2D Dummy Car,2D Dummy Bus or 2D Dummy Pedestrian button in the toolbar.

      +
      3. +
    +

    alt text

    +
      +
    1. Set the pose of the dummy object by clicking and dragging on the map.
      2. +
    +

    alt text

    +
      +
    1. Set the velocity of the object in Tool Properties -> 2D Dummy Car/Pedestrian panel.
      2. +
    +

    alt text

    +
      +
    1. NPCs will not be spawned if the you try to place them outside the map.
      2. +
    + + + + + + + + + + + + + +
    +
    + + + + + +
    + + + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/rvizspawner.png b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/rvizspawner.png new file mode 100644 index 000000000..130dce1a6 Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/rvizspawner.png differ diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/spawnPedestrian.gif b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/spawnPedestrian.gif new file mode 100644 index 000000000..5164a1d5e Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/spawnPedestrian.gif differ diff --git a/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/toolsprop.png b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/toolsprop.png new file mode 100644 index 000000000..2fbc95533 Binary files /dev/null and b/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/toolsprop.png differ diff --git a/pr-120/Components/Traffic/NPCs/Vehicle/index.html b/pr-120/Components/Traffic/NPCs/Vehicle/index.html index 617960492..c1f50608c 100644 --- a/pr-120/Components/Traffic/NPCs/Vehicle/index.html +++ b/pr-120/Components/Traffic/NPCs/Vehicle/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/index.html b/pr-120/Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/index.html index 7ac3be42a..366077b04 100644 --- a/pr-120/Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/index.html +++ b/pr-120/Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/index.html @@ -14,7 +14,7 @@ - + @@ -1985,6 +1985,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • @@ -2698,13 +2719,13 @@

    Check final configuration +
    Next
    - Pedestrian + Spawn NPCs from RVIZ
    diff --git a/pr-120/Components/Traffic/RandomTraffic/RandomTrafficSimulator/index.html b/pr-120/Components/Traffic/RandomTraffic/RandomTrafficSimulator/index.html index da9f00a32..472c41751 100644 --- a/pr-120/Components/Traffic/RandomTraffic/RandomTrafficSimulator/index.html +++ b/pr-120/Components/Traffic/RandomTraffic/RandomTrafficSimulator/index.html @@ -1970,6 +1970,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Traffic/RandomTraffic/YieldingRules/index.html b/pr-120/Components/Traffic/RandomTraffic/YieldingRules/index.html index 24a317926..be0646918 100644 --- a/pr-120/Components/Traffic/RandomTraffic/YieldingRules/index.html +++ b/pr-120/Components/Traffic/RandomTraffic/YieldingRules/index.html @@ -1922,6 +1922,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Traffic/TrafficComponents/index.html b/pr-120/Components/Traffic/TrafficComponents/index.html index 4f49fa346..0ff933e55 100644 --- a/pr-120/Components/Traffic/TrafficComponents/index.html +++ b/pr-120/Components/Traffic/TrafficComponents/index.html @@ -2122,6 +2122,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/AddNewVehicle/AddAVehicle/index.html b/pr-120/Components/Vehicle/AddNewVehicle/AddAVehicle/index.html index 08c266d4b..a1f759d0f 100644 --- a/pr-120/Components/Vehicle/AddNewVehicle/AddAVehicle/index.html +++ b/pr-120/Components/Vehicle/AddNewVehicle/AddAVehicle/index.html @@ -2056,6 +2056,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/AddNewVehicle/AddColliders/index.html b/pr-120/Components/Vehicle/AddNewVehicle/AddColliders/index.html index 1ed1280b0..7049a453d 100644 --- a/pr-120/Components/Vehicle/AddNewVehicle/AddColliders/index.html +++ b/pr-120/Components/Vehicle/AddNewVehicle/AddColliders/index.html @@ -1927,6 +1927,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/AddNewVehicle/AddSensors/index.html b/pr-120/Components/Vehicle/AddNewVehicle/AddSensors/index.html index 74ab12e49..1e65748e4 100644 --- a/pr-120/Components/Vehicle/AddNewVehicle/AddSensors/index.html +++ b/pr-120/Components/Vehicle/AddNewVehicle/AddSensors/index.html @@ -2029,6 +2029,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/AddNewVehicle/AddVisualElements/index.html b/pr-120/Components/Vehicle/AddNewVehicle/AddVisualElements/index.html index 04853f91c..de9c5b0a0 100644 --- a/pr-120/Components/Vehicle/AddNewVehicle/AddVisualElements/index.html +++ b/pr-120/Components/Vehicle/AddNewVehicle/AddVisualElements/index.html @@ -1945,6 +1945,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/CustomizeSlip/index.html b/pr-120/Components/Vehicle/CustomizeSlip/index.html index 92a261216..18a2b77b8 100644 --- a/pr-120/Components/Vehicle/CustomizeSlip/index.html +++ b/pr-120/Components/Vehicle/CustomizeSlip/index.html @@ -1931,6 +1931,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/DynamicSensorPlacement/index.html b/pr-120/Components/Vehicle/DynamicSensorPlacement/index.html index 4b2965d71..03326e1d2 100644 --- a/pr-120/Components/Vehicle/DynamicSensorPlacement/index.html +++ b/pr-120/Components/Vehicle/DynamicSensorPlacement/index.html @@ -1940,6 +1940,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/EgoVehicle/index.html b/pr-120/Components/Vehicle/EgoVehicle/index.html index 87f7b8f99..2ab01f95b 100644 --- a/pr-120/Components/Vehicle/EgoVehicle/index.html +++ b/pr-120/Components/Vehicle/EgoVehicle/index.html @@ -2092,6 +2092,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/FollowCamera/index.html b/pr-120/Components/Vehicle/FollowCamera/index.html index e110b2014..a8efa4f7d 100644 --- a/pr-120/Components/Vehicle/FollowCamera/index.html +++ b/pr-120/Components/Vehicle/FollowCamera/index.html @@ -1918,6 +1918,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Components/Vehicle/URDFAndSensors/index.html b/pr-120/Components/Vehicle/URDFAndSensors/index.html index 847f607f4..b3b027b83 100644 --- a/pr-120/Components/Vehicle/URDFAndSensors/index.html +++ b/pr-120/Components/Vehicle/URDFAndSensors/index.html @@ -1937,6 +1937,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/Contact/index.html b/pr-120/DeveloperGuide/Contact/index.html index 194600a95..c03e8ac5b 100644 --- a/pr-120/DeveloperGuide/Contact/index.html +++ b/pr-120/DeveloperGuide/Contact/index.html @@ -1871,6 +1871,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/Documentation/index.html b/pr-120/DeveloperGuide/Documentation/index.html index a5b5bf923..3bd351af0 100644 --- a/pr-120/DeveloperGuide/Documentation/index.html +++ b/pr-120/DeveloperGuide/Documentation/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/EditorSetup/Graphy/index.html b/pr-120/DeveloperGuide/EditorSetup/Graphy/index.html index eabcf8e20..935e8a3d4 100644 --- a/pr-120/DeveloperGuide/EditorSetup/Graphy/index.html +++ b/pr-120/DeveloperGuide/EditorSetup/Graphy/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/EditorSetup/JetBrainsRider/index.html b/pr-120/DeveloperGuide/EditorSetup/JetBrainsRider/index.html index 866113dcb..0b1e74fdb 100644 --- a/pr-120/DeveloperGuide/EditorSetup/JetBrainsRider/index.html +++ b/pr-120/DeveloperGuide/EditorSetup/JetBrainsRider/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/EditorSetup/VSCode/index.html b/pr-120/DeveloperGuide/EditorSetup/VSCode/index.html index a9c8088d8..dffae12fe 100644 --- a/pr-120/DeveloperGuide/EditorSetup/VSCode/index.html +++ b/pr-120/DeveloperGuide/EditorSetup/VSCode/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/HowToContribute/index.html b/pr-120/DeveloperGuide/HowToContribute/index.html index 5186898cb..b401e3474 100644 --- a/pr-120/DeveloperGuide/HowToContribute/index.html +++ b/pr-120/DeveloperGuide/HowToContribute/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/License/index.html b/pr-120/DeveloperGuide/License/index.html index 8fb1d433b..e6f0339a0 100644 --- a/pr-120/DeveloperGuide/License/index.html +++ b/pr-120/DeveloperGuide/License/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/DeveloperGuide/TroubleShooting/index.html b/pr-120/DeveloperGuide/TroubleShooting/index.html index 132dd0ca6..d5d3f443b 100644 --- a/pr-120/DeveloperGuide/TroubleShooting/index.html +++ b/pr-120/DeveloperGuide/TroubleShooting/index.html @@ -1873,6 +1873,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/GettingStarted/QuickStartDemo/index.html b/pr-120/GettingStarted/QuickStartDemo/index.html index 70ba9657b..fb7de4351 100644 --- a/pr-120/GettingStarted/QuickStartDemo/index.html +++ b/pr-120/GettingStarted/QuickStartDemo/index.html @@ -2000,6 +2000,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/GettingStarted/SetupUnityProject/index.html b/pr-120/GettingStarted/SetupUnityProject/index.html index 861a4def9..85eac0d1e 100644 --- a/pr-120/GettingStarted/SetupUnityProject/index.html +++ b/pr-120/GettingStarted/SetupUnityProject/index.html @@ -1991,6 +1991,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/GettingStarted/UsingOpenSCENARIO/index.html b/pr-120/GettingStarted/UsingOpenSCENARIO/index.html index 5dbcb84bb..8a8e0b652 100644 --- a/pr-120/GettingStarted/UsingOpenSCENARIO/index.html +++ b/pr-120/GettingStarted/UsingOpenSCENARIO/index.html @@ -1958,6 +1958,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Introduction/AWSIM/index.html b/pr-120/Introduction/AWSIM/index.html index 48f01d248..210326eb2 100644 --- a/pr-120/Introduction/AWSIM/index.html +++ b/pr-120/Introduction/AWSIM/index.html @@ -1922,6 +1922,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Introduction/Autoware/index.html b/pr-120/Introduction/Autoware/index.html index e38901bd7..1dc7fe919 100644 --- a/pr-120/Introduction/Autoware/index.html +++ b/pr-120/Introduction/Autoware/index.html @@ -1922,6 +1922,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Introduction/CombinationWithAutoware/index.html b/pr-120/Introduction/CombinationWithAutoware/index.html index c68dc04c9..ad563b66c 100644 --- a/pr-120/Introduction/CombinationWithAutoware/index.html +++ b/pr-120/Introduction/CombinationWithAutoware/index.html @@ -1993,6 +1993,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/Introduction/CombinationWithAutowareAndScenarioSimulator/index.html b/pr-120/Introduction/CombinationWithAutowareAndScenarioSimulator/index.html index 8c6c1a13f..2c4848e48 100644 --- a/pr-120/Introduction/CombinationWithAutowareAndScenarioSimulator/index.html +++ b/pr-120/Introduction/CombinationWithAutowareAndScenarioSimulator/index.html @@ -1869,6 +1869,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/ProjectGuide/Directory/index.html b/pr-120/ProjectGuide/Directory/index.html index 1ac2e1bc1..5ff922d25 100644 --- a/pr-120/ProjectGuide/Directory/index.html +++ b/pr-120/ProjectGuide/Directory/index.html @@ -1883,6 +1883,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/ProjectGuide/ExternalLibraries/index.html b/pr-120/ProjectGuide/ExternalLibraries/index.html index 5e6fb1363..a46ef4bb2 100644 --- a/pr-120/ProjectGuide/ExternalLibraries/index.html +++ b/pr-120/ProjectGuide/ExternalLibraries/index.html @@ -1883,6 +1883,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/ProjectGuide/GitBranch/index.html b/pr-120/ProjectGuide/GitBranch/index.html index 49d3a3c77..14df6f0a7 100644 --- a/pr-120/ProjectGuide/GitBranch/index.html +++ b/pr-120/ProjectGuide/GitBranch/index.html @@ -1931,6 +1931,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/ProjectGuide/HotkeyList/index.html b/pr-120/ProjectGuide/HotkeyList/index.html index b04a35d53..61043f851 100644 --- a/pr-120/ProjectGuide/HotkeyList/index.html +++ b/pr-120/ProjectGuide/HotkeyList/index.html @@ -1958,6 +1958,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/ProjectGuide/Scenes/index.html b/pr-120/ProjectGuide/Scenes/index.html index df1d3626c..04c8bcf72 100644 --- a/pr-120/ProjectGuide/Scenes/index.html +++ b/pr-120/ProjectGuide/Scenes/index.html @@ -2041,6 +2041,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/index.html b/pr-120/index.html index d84ffb202..b30e0e5b7 100644 --- a/pr-120/index.html +++ b/pr-120/index.html @@ -1938,6 +1938,27 @@ +
  • + + + + + Spawn NPCs from RVIZ + + + + +
    • + + + + + + + + + +
  • diff --git a/pr-120/search/search_index.json b/pr-120/search/search_index.json index 904a9a41b..5b5ca4628 100644 --- a/pr-120/search/search_index.json +++ b/pr-120/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#welcome-to-awsim-labs","title":"Welcome to AWSIM Labs","text":"

    AWSIM Labs is currently being developed under the Autoware Labs initiative. Main purpose of this fork is to provide faster implementation of features needed by the users of the AWSIM while also ensuring a high-performance simulation environment for the Autoware.

    This is a fork of TIER IV's AWSIM.

    "},{"location":"#features","title":"Features","text":"
    • Many predefined components included (Vehicle dynamic models, Sensor models, Environment configuration, ROS2 communication, etc)
    • Support for Ubuntu 22.04 and windows10/11
    • ROS2 native communication (humble)
    • Open sourced
    • Made with Unity
    "},{"location":"#feature-differences-from-the-tier-ivawsim","title":"Feature differences from the TIER IV/AWSIM","text":"

    See Feature differences from the TIER IV/AWSIM in the Autoware Documentation.

    "},{"location":"#try-the-simulation-demo-yourself","title":"Try the simulation demo yourself!","text":"

    Run the AWSIM Labs demo with Autoware following the instructions in the Quick start demo.

    "},{"location":"Components/Clock/ClockPublisher/","title":"Clock Publisher","text":""},{"location":"Components/Clock/ClockPublisher/#introduction","title":"Introduction","text":"

    ClockPublisher allows the publication of the simulation time from the clock operating within AWSIM. The current time is retrived from a TimeSource object via the SimulatorROS2Node. The AWSIM provides convenient method for selecting the appropriate time source type as well as the flexibility to implement custom TimeSources tailored to specific user requirements.

    "},{"location":"Components/Clock/ClockPublisher/#setup","title":"Setup","text":"

    To enable the publication of the current time during simulation execution, ClockPublisher must be included as a component within the scene. Moreover, to allow the TimeSource to be set or changed, the TimeSourceSelector object must also be present in the active scene.

    "},{"location":"Components/Clock/ClockPublisher/#selecting-time-source","title":"Selecting Time Source","text":"

    The desired TimeSource can be selected in two ways:

    • Inspector Selection: TimeSource type can be conveniently choosen directly from the editor interface.

    • JSON Configuration File: Alternatively, the TimeSource type can be specified in the JSON configuration file via the TimeSource field. The supported values for this field can be found in the list of available time sources in the \"String Value for JSON Config\" column.

    "},{"location":"Components/Clock/ClockPublisher/#list-of-time-sources","title":"List of Time Sources","text":"Type String Value for JSON Config Description UNITY unity based on the time of the Unity Engine SS2 ss2 driven by an external source, used by the scenario simulator v2 DOTNET_SYSTEM system based on system time, starting with time since UNIX epoch, progressing according to simulation timescale DOTNET_SIMULATION simulation based on system time, starting with zero value, progressing according to simulation timescale ROS2 ros2 based on ROS2 time (system time by default)"},{"location":"Components/Clock/ClockPublisher/#architecture","title":"Architecture","text":"

    The ClockPublisher operates within a dedicated thread called the 'Clock' thread. This design choice offers significant advantages by freeing the publishing process from the constraints imposed by fixed update limits. As a result, ClockPublisher is able to consistently publish time at a high rate, ensuring stability and accuracy.

    "},{"location":"Components/Clock/ClockPublisher/#accessing-time-source","title":"Accessing Time Source","text":"

    Running the clock publisher in a dedicated thread introduced the challenge of accessing shared resources by different threads. In our case, the Main Thread and Clock Thread compete for TimeSoruce resources. The diagram below illustrates this concurrent behaviour, with two distinct threads vying for access to the TimeSource:

    • Main Thread: included publishing message by sensors (on the diagram blueish region labeled sensor loop),
    • Clock Thread: included clock publisher (on the diagram blueish region labeled clock loop).

    Given multiple sensors, each with its own publishing frequency, alongside a clock running at 100Hz, there is a notable competition for TimeSource resources. In such cases, it becomes imperative for the TimeSource class to be thread-safe.

    "},{"location":"Components/Clock/ClockPublisher/#thread-safe-time-source","title":"Thread-Safe Time Source","text":"

    The TimeSource synchronization mechanism employs a mutex to lock the necessary resource for the current thread. The sequence of actions undertaken each time the GetTime() method is called involves:

    • acquiring the lock,
    • getting the current time, e.g. system time since epoch, (this may be different for each type of time source),
    • obtaining the current simulation time-scale,
    • calculating the delta time since previous call, influenced by the time scale,
    • returning the current time,
    • releasing the lock.

    "},{"location":"Components/Clock/ClockPublisher/#extensions","title":"Extensions","text":"

    There are two additional classes used to synchronise the UnityEngine TimeAsDouble and TimeScale values between threads:

    • TimeScaleProvider: facilitates the synchronisation of the simulation time scale value across threads,
    • TimeAsDoubleProvider: provides access to the UnityEngine TimeAsDouble to the threads other than the main thread.
    "},{"location":"Components/Environment/AWSIMEnvironment/","title":"AWSIM Environment","text":""},{"location":"Components/Environment/AWSIMEnvironment/#awsim-environment","title":"AWSIM Environment","text":""},{"location":"Components/Environment/AWSIMEnvironment/#introduction","title":"Introduction","text":"

    Environment is an object that contains all the elements visible on the scene along with components that affect how they are rendered. It contains several objects aggregating static environment objects in terms of their type. Moreover, it contains elements responsible for controlling random traffic.

    Own Environment prefab

    If you would like to develop your own prefab Environment for AWSIM, we encourage you to read this tutorial.

    AutowareSimulation scene

    If you would like to see how Environment with random traffic works or run some tests, we encourage you to familiarize yourself with the AutowareSimulation scene described in this section.

    Prefab Environment is also used to create a point cloud (*.pcd file) needed to locate the EgoVehicle in the simulated AWSIM scene. The point cloud is created using the RGL plugin and then used in Autoware. We encourage you to familiarize yourself with an example scene of creating a point cloud - described here.

    Create PointCloud (*.pcd file)

    If you would like to learn how to create a point cloud in AWSIM using Environment prefab, we encourage you to read this tutorial.

    "},{"location":"Components/Environment/AWSIMEnvironment/#architecture","title":"Architecture","text":"

    The architecture of an Environment - with dependencies between components - is presented on the following diagram.

    "},{"location":"Components/Environment/AWSIMEnvironment/#prefabs","title":"Prefabs","text":"

    Prefabs can be found under the following path:

    Name Description Path Nishishinjuku Only stationary visual elements, no traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku.prefab Nishishinjuku RandomTraffic Stationary visual elements along with random traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku RandomTraffic.prefab Nishishinjuku Traffic Stationary visual elements along with non-random traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku Traffic.prefab

    Environment prefab

    Due to the similarity of the above prefabs, this section focuses on prefab Nishishinjuku RandomTraffic. The exact differences between Nishishinjuku RandomTraffic and Nishishinjuku Traffic will be described in the future.

    Environment name

    In order to standardize the documentation, the name Environment will be used in this section as the equivalent of the prefab named Nishishinjuku RandomTraffic.

    Nishishinjuku RandomTraffic prefab has the following content:

    As you can see it contains:

    • SJK* objects - which are aggregators for visual models.
    • RandomTrafficSimulator, TrafficIntersections, TrafficLanes, StopLines - which are responsible for random traffic of NPCVehicles.
    • NPCPedestrians - which is an aggregator of NPCPedestrian prefabs added to the scene.
    • Volume, Directional Light - which are components that affect the appearance of objects on the scene.

    All of these objects are described below in this section.

    "},{"location":"Components/Environment/AWSIMEnvironment/#visual-elements","title":"Visual elements","text":"

    Nishishinjuku RandomTraffic prefab contains many visual elements which are described here.

    "},{"location":"Components/Environment/AWSIMEnvironment/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    Nishishinjuku RandomTraffic prefab is added to the Environment object - between which there is rotation about the Oy axis by 90 degrees. This rotation is added because of the differences in coordinate alignments between the Nishishinjuku RandomTraffic prefab objects (which have been modeled as *.fbx files) and the specifics of the GridZone definition (more on this is described here).

    Object Environment is added to AutowareSimulation which is added directly to the main parent of the scene - there are no transformations between these objects.

    "},{"location":"Components/Environment/AWSIMEnvironment/#components","title":"Components","text":"

    Nishishinjuku RandomTraffic (Environment) prefab contains only one component:

    • Environment (script) - which is important for communicating with Autoware and loading elements from Lanelet2. Because it allows to define the location of the environment in relation to the world.
    "},{"location":"Components/Environment/AWSIMEnvironment/#layers","title":"Layers","text":"

    In order to enable the movement of vehicles around the environment, additional layers have been added to the project: Ground and Vehicle.

    All objects that are acting as a ground for NPCVehicles and EgoVehicle to move on have been added to Ground layer - they cannot pass through each other and should collide for the physics engine to calculate their interactions.

    For this purpose, NPCVehicles and EgoVehicle have been added to the Vehicle layer.

    In the project physics settings, it is ensured that collisions between objects in the Vehicle layer are disabled (this applies to EgoVehicle and NPCVehicles - they do not collide with each other):

    "},{"location":"Components/Environment/AWSIMEnvironment/#traffic-components","title":"Traffic Components","text":"

    Due to the specificity of the use of RandomTrafficSimulator, TrafficIntersections, TrafficLanes, StopLines objects, they have been described in a separate section Traffic Components - where all the elements necessary in simulated random traffic are presented.

    "},{"location":"Components/Environment/AWSIMEnvironment/#visual-elements-sjk","title":"Visual Elements (SJK)","text":"

    The visuals elements have been loaded and organized using the *.fbx files which can be found under the path:

    Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_optimized/Models/*\n

    Environment prefab contains several objects aggregating stationary visual elements of space by their category:

    • SJK01_P01 - contains all objects constituting the ground of the environment, these are roads and green fields - each of them contains a MeshColliders and layer set as Ground to ensure collisions with NPCVehicles and EgoVehicle.

    • SJK01_P02 - contains all road surface markings on roads added to the environment. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P03 - contains all the vertical poles added to the environment, such as lamp posts, road signs and traffic light poles. Only TrafficLight poles and PedestrianLight poles have MeshCollider added. The layer for all objects is Default.

    • SJK01_P04 - contains all barriers added to the environment, such as barriers by sidewalks. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P05 - contains all greenery added to the environment, such as trees, shrubs, fragments of greenery next to buildings. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P06 - contains all buildings added to the environment. Objects of this category also have a MeshCollider added, but their layer is Default.

    Scene Manager

    For models (visual elements) added to the prefab to work properly with the LidarSensor sensor using RGL, make sure that the SceneManager component is added to the scene - more about it is described in this section.

    In the scene containing Nishishinjuku RandomTrafficprefab Scene Manager (script) is added as a component to the AutowareSimulation object containing the Environment.

    "},{"location":"Components/Environment/AWSIMEnvironment/#trafficlights","title":"TrafficLights","text":"

    TrafficLights are a stationary visual element belonging to the SJK01_P03 group. The lights are divided into two types, the classic TrafficLights used by vehicles at intersections and the PedestrianLights found at crosswalks.

    Classic traffic lights are aggregated at object TrafficLightA01_Root01_ALL_GP01

    while lights used by pedestrians are aggregated at object TrafficLightB01_Root01_All_GP01.

    TrafficLights and PedestrianLights are developed using models available in the form of *.fbx files, which can be found under the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Models/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#classic-trafficlights","title":"Classic TrafficLights","text":"

    TrafficLights lights, outside their housing, always contain 3 signaling light sources of different colors - from left to right: green, yellow, red. Optionally, they can have additional sources of signaling the ability to drive in a specific direction in the form of one or three signaling arrows.

    In the environment there are many classic lights with different signaling configurations. However, each contains:

    • Transform - defines the position of the lights in the environment relative to the main parent of the group (SJK01_P03).
    • Mesh Filter - contains a reference to the Mesh of the object.
    • Mesh Renderer - enables the rendering of Mesh, including its geometry, textures, and materials, giving it a visual appearance in the scene.
    • Mesh Collider - allows an object to have collision detection based on Mesh.
    • Traffic Light (script) - provides an interface to control signaling by changing the emission of materials. This script is used for simulated traffic, so it is described.
    "},{"location":"Components/Environment/AWSIMEnvironment/#materials","title":"Materials","text":"

    An important element that is configured in the TrafficLights object are the materials in the Mesh Renderer component. Material with index 0 always applies to the housing of the lights. Subsequent elements 1-6 correspond to successive slots of light sources (round luminous objects) - starting from the upper left corner of the object in the right direction, to the bottom and back to the left corner. These indexes are used in script Traffic Light (script) - described here.

    Materials for lighting slots that are assigned in Mesh Renderer can be found in the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Materials/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#pedestrianlights","title":"PedestrianLights","text":"

    PedestrianLights lights, outside their housing, always contain 2 signaling light sources of different colors - red on top and green on the bottom.

    In the environment there are many pedestrian lights - they have the same components as classic TrafficLights, but the main difference is the configuration of their materials.

    "},{"location":"Components/Environment/AWSIMEnvironment/#materials_1","title":"Materials","text":"

    An important element that is configured in the PedestrianLights object are the materials in the Mesh Renderer component. Material with index 0 always applies to the housing of the lights. Subsequent elements 1-2 correspond to successive slots of light sources (round luminous objects) - starting from top to bottom. These indexes are used in script Traffic Light (script) - described here.

    Materials for lighting slots that are assigned in Mesh Renderer can be found in the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Materials/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#volume","title":"Volume","text":"

    Volume is GameObject with Volume component which is used in the High Definition Render Pipeline (HDRP). It defines a set of scene settings and properties. It can be either global, affecting the entire scene, or local, influencing specific areas within the scene. Volumes are used to interpolate between different property values based on the Camera's position, allowing for dynamic changes to environment settings such as fog color, density, and other visual effects.

    In case of prefab Nishishinjuku RandomTraffic volume works in global mode and has loaded Volume profile. This volume profile has a structure that overrides the default properties of Volume related to the following components: Fog, Shadows, Ambient Occlusion, Visual Environment, HDRI Sky. It can be found in the following path: Assets/AWSIM/Prefabs/Environments/Nishishinjuku/Volume Profile.asset

    "},{"location":"Components/Environment/AWSIMEnvironment/#directional-light","title":"Directional Light","text":"

    Directional Light is GameObject with Light component which is used in the High Definition Render Pipeline (HDRP). It controls the shape, color, and intensity of the light. It also controls whether or not the light casts shadows in scene, as well as more advanced settings.

    In case of prefab Nishishinjuku RandomTraffic a Directional type light is added. It creates effects that are similar to sunlight in scene. This light illuminates all GameObjects in the scene as if the light rays are parallel and always from the same direction. Directional light disregards the distance between the Light itself and the target, so the light does not diminish with distance. The strength of the Light (Intensity) is set to 73123.09 Lux. In addition, a Shadow Map with a resolution of 4096 is enabled, which is updated in Every Frame of the simulation. The transform of the Directional Light object is set in such a way that it shines on the environment almost vertically from above.

    "},{"location":"Components/Environment/AWSIMEnvironment/#npcpedestrians","title":"NPCPedestrians","text":"

    NPCPedestrians is an aggregating object for NPCPedestrian objects placed in the environment. Prefab Nishishinjuku RandomTraffic has 7 NPCPedestrian (humanElegant) prefabs defined in selected places. More about this NPCPedestrian prefab you can read in this section.

    "},{"location":"Components/Environment/AWSIMEnvironment/#environment-script","title":"Environment (script)","text":"

    Environment (script) contains the information about how a simulated Environment is positioned in real world. That means it describes what is the real world position of a simulated Environment.

    AWSIM uses part of a Military Grid Reference System (MGRS). To understand this topic, you only need to know, that using MGRS you can specify distinct parts of the globe with different accuracy. For AWSIM the chosen accuracy is a 100x100 km square. Such a square is identified with a unique code like 54SUE (for more information on Grid Zone please see this page).

    Inside this Grid Zone the exact location is specified with the offset calculated from the bottom-left corner of the Grid Zone. You can interpret the Grid Zone as a local coordinate system in which you position the Environment.

    In the Nishishinjuku RandomTraffic prefab, the simulated Environment is positioned in the Grid Zone 54SUE. The offset if equal to 81655.73 meters in the Ox axis, 50137.43 meters in the Oy axis and 42.49998 meters in the Oz axis. In addition to this shift, it is also necessary to rotate the Environment in the scene by 90 degrees about the Oy axis - this is ensured by the transform in the prefab object.

    This means that the 3D models were created in reference to this exact point and because of that the 3D models of Environment align perfectly with the data from Lanelet2.

    The essence of Environment (script)

    The Environment (script) configuration is necessary at the moment of loading data from Lanelet2.

    Internally it shifts the elements from Lanelet2 by the given offset so that they align with the Environment that is located at the local origin with no offset.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/","title":"Add Environment","text":""},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#add-an-environment","title":"Add an Environment","text":"

    Environment is an important part of a Scene in AWSIM. Every aspect of the simulated surrounding world needs to be included in the Environment prefab - in this section you will learn how to develop it. However, first Lanelet2 needs to be developed along with 3D models of the world, which will be the main elements of this prefab.

    Tip

    If you want to learn more about the Environment at AWSIM, please visit this page.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-a-lanelet2","title":"Create a Lanelet2","text":"

    Before you start creating Lanelet2, we encourage you to read the documentation to find out what Lanelet2 is all about. Lanelet2 can be created using VectorMapBuilder (VMP) based on the PCD obtained from real-life LiDAR sensor.

    When working with the VMP, it is necessary to ensure the most accurate mapping of the road situation using the available elements. Especially important are TrafficLanes created in VMB as connected Road Nodes and StopLines created in VMB as Road Surface Stoplines.

    Lanelet2 positioning

    Lanelet2 should be created in MGRS coordinates of the real place you are recreating. Please position your Lanelet2 relative to the origin (bottom left corner) of the MGRS Grid Zone with the 100 km Square ID in which the location lays. More details can be read here.

    You can think of the Grid Zone as a local coordinate system. Instead of making global (0,0) point (crossing of Equator and Prime Median) our coordinate system origin we take a closer one. The MGRS Grid Zone with 100 km Square ID code designates a 100x100 [kmxkm] square on the map and we take its bottom left corner as our local origin.

    Example

    Lets examine one node from an example Lanelet2 map:

    <node id=\"4\" lat=\"35.68855194431519\" lon=\"139.69142711058254\">\n    <tag k=\"mgrs_code\" v=\"54SUE815501\"/>\n    <tag k=\"local_x\" v=\"81596.1357\"/>\n    <tag k=\"local_y\" v=\"50194.0803\"/>\n    <tag k=\"ele\" v=\"34.137\"/>\n</node>\n

    The node with id=\"4\" position is described as absolute coordinates given in the <node>. In this example the coordinates are as follows lat=\"35.68855194431519\" lon=\"139.69142711058254.

    It is also described as local transformation defined as a translation relative to the origin of the MGRS Grid Zone with 100 km Square ID (bottom left corner). The MGRS Grid Zone designation with 100 km Square ID in this case is equal to 54SUE. In this example the offset in the X axis is as follows k=\"local_x\" v=\"81596.1357\" and the offset in the Y axis is as follows k=\"local_y\" v=\"50194.0803\".

    Note that elevation information is also included.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-3d-models","title":"Create 3D models","text":"

    You can create 3D models of an Environment as you wish. It is advised however, to prepare the models in form of .fbx files. Additionally you should include materials and textures in separate directories. Many models are delivered in this format. This file format allows you to import models into Unity with materials and replace materials while importing. You can learn more about it here.

    You can see a .fbx model added and modified on the fly in the example of this section.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#guidelines","title":"Guidelines","text":"

    To improve the simulation performance of a scene containing your Environment prefab, please keep in mind some of these tips when creating 3D models:

    1. Prefer more smaller models over a few big ones.

      In general it is beneficial for performance when you make one small mesh of a object like tree and reuse it on the scene placing many prefabs instead of making one giant mesh containing all trees on the given scene. It is beneficial even in situations when you are not reusing the meshes. Lets say you have a city with many buildings - and every one of those buildings is different - it is still advised to model those building individually and make them separate GameObjects.

    2. Choose texture resolution appropriately.

      Always have in mind what is the target usage of your texture. Avoid making a high resolution texture for a small object or the one that will always be far away from the camera. This way you can save some computing power by not calculating the details that will not be seen because of the screen resolution.

      Practical advice

      You can follow these simple rules when deciding on texture quality (texel density):

      • For general objects choose 512px/m (so the minimum size of texture is 512/512)
      • For important objects that are close to the camera choose 1024px/m (so the minimum size of texture is 1024/1024)

    3. (optional) Add animation.

      Add animations to correct objects. If some element in the 3D model are interactive they should be divided into separate parts.

    What's more, consider these tips related directly to the use of 3D models in AWSIM:

    1. Creating a 3D model based on actual point cloud data makes it more realistic.
    2. AWSIM is created using HDRP (High Definition Rendering Pipeline) which performs better when object meshes are merged.
    3. Occlusion culling and flutter culling cannot be used because the sensors detection target will disappear.
    4. Each traffic light should have a separate GameObject. Also, each light in the traffic light should be split into separate materials.
    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-an-environment-prefab","title":"Create an Environment prefab","text":"

    In this part, you will learn how to create a Environment prefab - that is, develop a GameObject containing all the necessary elements and save it as a prefab.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#1-add-3d-models","title":"1. Add 3D models","text":"

    In this section we will add roads, buildings, greenery, signs, road markings etc. to our scene.

    Most often your models will be saved in the .fbx format. If so, you can customize the materials in the imported model just before importing it. Sometimes it is necessary as models come with placeholder materials. You can either

    • replace materials for every added GameObject into the Scene,
    • or replace materials for one GameObject and save this object as a prefab to easily load it later.

    In order to add 3D models from the .fbx file to the Scene please do the following steps:

    1. In the Project view navigate to the directory where the model is located and click on the model file.
    2. Now you can customize the materials used in the model in the Inspector view.
    3. Drag the model into the Scene where you want to position it.
    4. Move the Object in the Hierarchy tree appropriately.
    5. (optional) Now you can save this model configuration as a prefab to easily reuse it. Do this by dragging the Object from the Scene into the Project view. When you get a warning make sure to select you want to create an original new prefab.

    Example

    An example video of the full process of importing a model, changing the materials, saving new model as a prefab and importing the new prefab.

    When creating a complex Environment with many elements you should group them appropriately in the Hierarchy view. This depends on the individual style you like more, but it is a good practice to add all repeating elements into one common Object. E.g. all identical traffic lights grouped in TrafficLights Object. The same can be done with trees, buildings, signs etc. You can group Objects as you like.

    Object hierarchy

    When adding elements to the Environment that are part of the static world (like 3D models of buildings, traffic lights etc.) it is good practice to collect them in one parent GameObject called Map or something similar.

    By doing this you can set a transformation of the parent GameObject Map to adjust the world pose in reference to e.g. loaded objects from Lanelet2.

    Remember to unpack

    Please remember to unpack all Object added into the scene. If you don't they will change materials together with the .fbx model file as demonstrated in the example below.

    This is unwanted behavior. When you import a model and change some materials, but leave the rest default and don't unpack the model, then your instances of this model on the scene may change when you change the original fbx model settings.

    See the example below to visualize what is the problem.

    Example

    In this example we will

    • Place the model on the Scene.
    • Then intentionally not unpack the model
    • Only then change the materials of the original fbx model, not the instance on the scene

    Watch what happens, the instance on the Scene changes the materials together with the model. This only happens if you don't unpack the model.

    Example Environment after adding 3D models

    After completing this step you should have an Environment Object that looks similar to the one presented below.

    The Environment with 3D models can look similar to the one presented below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#2-add-an-environment-script","title":"2. Add an Environment Script","text":"

    Add an Environment Script as component in the Environment object (see the last example in section before). It does not change the appearance of the Environment, but is necessary for the simulation to work correctly.

    1. Click on the Add Component button in the Environment object.

    2. Search for Environment and select it.

    3. Set the MGRS to the offset of your Environment as explained in this section.

    Info

    Due to the differences between VectorMapBuilder and Unity, it may be necessary to set the transform of the Environment object. The transform in Environment should be set in such a way that the TrafficLanes match the modeled roads. Most often it is necessary to set the positive 90 degree rotation over Y axis.

    This step should be done after importing items from lanelet2. Only then will you know if you have Environment misaligned with items from lanelet2.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#3-add-a-directional-light","title":"3. Add a Directional Light","text":"

    1. Create a new child Object of the Environment and name it Directional Light.

    2. Click Add Component button, search for Light and select it.

    3. Change light Type to Directional.

    4. Now you can configure the directional light as you wish. E.g. change the intensity or orientation.

    Tip

    For more details on lighting check out official Unity documentation.

    Example Environment after adding Directional Light

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#4-add-a-volume","title":"4. Add a Volume","text":"

    1. Create a new child object of the Environment and name it Volume.

    2. Click Add Component search for Volume and select it.

    3. Change the Profile to Volume Profile and wait for changes to take effect.

    4. Now you can configure the Volume individually as you wish.

    Tip

    For more details on volumes checkout official Unity documentation.

    Example Environment after adding Volume

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#5-add-npcpedestrians","title":"5. Add NPCPedestrians","text":"

    1. Make NPCPedestrians parent object.

    2. Open Assets/AWSIM/Prefabs/NPCs/Pedestrians in Project view and drag a humanElegant into the NPCPedestrians parent object.

    3. Click Add Component in the humanElegant object and search for Simple Pedestrian Walker Controller Script and select it.

      This is a simple Script that makes the pedestrian walk straight and turn around indefinitely. You can configure pedestrian behavior with 2 parameters.

      • Duration - how long will the pedestrian walk straight
      • Speed - how fast will the pedestrian walk straight

      Tip

      The Simple Pedestrian Walker Controller Script is best suited to be used on pavements.

    4. Finally position the NPCPedestrian on the scene where you want it to start walking.

      Warning

      Remember to set correct orientation, as the NPCPedestrian will walk straight from the starting position with the starting orientation.

    Example Environment after adding NPC Pedestrians

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#6-save-an-environment-prefab","title":"6. Save an Environment prefab","text":"

    After doing all the previous steps and having your Environment finished you can save it to prefab format.

    1. Find an Environments directory in the Project view (Assets/AWSIM/Prefabs/Environments).
    2. Drag the Environment Object into the Project view.
    3. (optional) Change the prefab name to recognize it easily later.

    Success

    Once you've added the Environment, you need to add and configure TrafficLights. For details please visit this tutorial.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/","title":"Add Random Traffic","text":"

    To add a Random Traffic to your scene you need the Random Traffic Simulator Script.

    1. Create a new Game Object as a child of Environment and call it RandomTrafficSimulator.

    2. Click a button Add Component in the Inspector to add a script.

    3. A small window should pop-up. Search for RandomTrafficSimulator script and add it by double clicking it or by pressing enter.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#basic-configuration","title":"Basic Configuration","text":"

    After clicking on the newly created RandomTrafficSimulator object in the Scene tree you should see something like this in the Inspector view.

    Random Traffic Simulator, as the name suggests, generates traffic based on random numbers. To replicate situations you can set a specific seed.

    You can also set Vehicle Layer Mask and Ground Layer Mask. It is important to set these layers correctly, as they are a base for vehicle physics. If set incorrectly the vehicles may fall through the ground into the infinity.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#add-npcvehicles","title":"Add NPCVehicles","text":"

    Random Traffic Simulator Script moves, spawns and despawns vehicles based on the configuration. These settings can to be adjusted to your preference.

    1. Setting Max Vehicle Count.

      This parameter sets a limit on how many vehicles can be added to the scene at one time.

    2. NPC Prefabs

      These are models of vehicles that should be spawned on the scene, to add NPC Prefabs please follow these steps:

      1. To do this click on the \"+\" sign and in the new list element at the bottom and click on the small icon on the right to select a prefab.

      2. Change to the Assets tab in the small windows that popped-up.

      3. Search for the Vehicle prefab you want to add, e.g. Hatchback.

      Available NPC prefabs are shown in the NPC Vehicle section.

      Control NPC Vehicle spawning

      Random Traffic Simulator Script will on random select one prefab from Npc Prefabs list every time when there are not enough vehicles on the scene (the number of vehicles on the scene is smaller than the number specified in the Max Vehicle Count field).

      You can control the odds of selecting one vehicle prefab over another by adding more than one instance of the same prefab to this list.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#add-spawnable-lanes","title":"Add spawnable lanes","text":"

    Spawnable lanes are the lanes on which new vehicles can be spawned by the Random Traffic Simulator Script. Best practice is to use beginnings of the lanes on the edges of the map as spawnable lanes.

    Warning

    Make sure you have a lanelet added into your scene. The full tutorial on this topic can be found here.

    Adding spawnable lanes is similar to Adding NPC Prefabs.

    1. Add an element to the Spawnable Lanes list by clicking on the \"+\" symbol or by selecting number of lanes directly.

    2. Now you can click on the small icon on the right of the list element and select a Traffic Lane you are interested in.

      Unfortunately all Traffic Lanes have the same names so it can be difficult to know which one to use. Alternatively you can do the following to add a traffic lane by visually selecting it in the editor:

      • Lock RandomTrafficSimulator in the Inspector view.

      • Select the Traffic Lane you are interested in on the Scene and as it gets highlighted in the Hierarchy view you can now drag and drop this Traffic Lane into the appropriate list element.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#vehicles-configuration","title":"Vehicles configuration","text":"

    The last thing to configure is the behavior of NPCVehicles. You can specify acceleration rate of vehicles and three values of deceleration.

    • Acceleration

      This value is used for every acceleration the vehicle performs (after stop line or traffic lights).

    • Deceleration

      This deceleration value is used for most casual traffic situations like slowing down before stop line.

    • Sudden Deceleration

      This deceleration rate is used for emergency situations - when using standard deceleration rate is not enough to prevent some accident from happening (e.g. vehicle on the intersection didn't give way when it was supposed to).

    • Absolute Deceleration

      This deceleration rate is a last resort for preventing a crash from happening. When no other deceleration is enough to prevent an accident this value is used. This should be set to the highest value achievable by a vehicle.

    Question

    This configuration is common for all vehicles managed by the Random Traffic Simulator Script.

    Success

    The last thing that needs to be done for RandomTraffic to work properly is to add intersections with traffic lights and configure their sequences. Details here.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/","title":"Add Traffic Intersection","text":"

    Every TrafficIntersection on the scene needs to be added as a GameObject. Best practice is to create a parent object TrafficIntersections and add all instances of TrafficIntersection as its children. You can do this the same as with Random Traffic Simulator.

    Traffic Lights configuration

    Before performing this step, check all TrafficLights for correct configuration and make sure that TrafficLights have added scripts. If you want to learn how to add and configure it check out this tutorial.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#add-a-box-collider","title":"Add a Box Collider","text":"

    1. TrafficIntersection needs to be marked with a box collider. First click on the Add Component button.

    2. In the window that popped up search for Box Collider and select it.

    3. Then set the position and orientation and size of the Box Collider. You can do this by manipulating Box Collider properties Center and Size in the Inspector view.

      Traffic Intersection Box Collider guidelines

      When adding a Box Collider marking your Traffic Intersection please make sure that

      • It is not floating over the ground - there is no gap between the Box Collider and The Traffic Intersection
      • It is high enough to cover all Vehicles that will be passing through the Intersection
      • It accurately represents the shape, position and orientation of the Traffic Intersection
    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#add-a-traffic-intersection-script","title":"Add a Traffic Intersection Script","text":"

    1. Click on the Add Component button.

    2. In the window that popped up search for Traffic Intersection and select it.

    3. You need to set a proper Collider Mask in order for the script to work.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#create-traffic-light-groups","title":"Create traffic light groups","text":"

    Traffic Light Groups are groups of traffic lights that are synchronized, meaning they light up with the same color and pattern at all times.

    Traffic lights are divided into groups to simplify the process of creating a lighting sequence. By default you will see 4 Traffic Light Groups, you can add and remove them to suit your needs.

    1. First choose from the drop-down menu called Group the Traffic Light Group name you want to assign to your Traffic Light Group.

    2. Then add as many Traffic Lights as you want your group to have. From the drop-down menu select the Traffic Lights you want to add.

      Select Traffic Lights visually

      If you have a lot of Traffic Lights it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#create-lighting-sequences","title":"Create lighting sequences","text":"

    Lighting Sequences is a list of commands based on which the Traffic Lights will operate on an intersection. The elements in the Lighting Sequences list are changes (commands) that will be executed on the Traffic Light Groups.

    Group Lighting Order should be interpreted as a command (or order) given to all Traffic Lights in selected Traffic Light Group. In Group Lighting Orders you can set different traffic light status for every Traffic Light Group (in separate elements). Lighting sequences list is processed in an infinite loop.

    It should be noted that changes applied to one Traffic Light Group will remain the same until the next Group Lighting Order is given to this Traffic Light Group. This means that if in one Group Lighting Order no command is sent to a Traffic Light Group then this Group will remain its current lighting pattern (color, bulb and status).

    For every Lighting Sequences Element you have to specify the following

    1. Interval Sec

      This is the time for which the sequence should wait until executing next order, so how long this state will be active.

    2. For every element in Group Lighting Orders there needs to be specified

      1. Group to which this order will be applied

      2. List of orders (Bulb Data)

        In other words - what bulbs should be turned on, their color and pattern.

        • Type - What type of bulb should be turned on
        • Color - What color this bulb should have (in most cases this will be the same as color of the bulb if specified)
        • Status - How the bulb should light up (selecting SOLID_OFF is necessary only when you want to turn the Traffic Light completely off, meaning no bulb will light up)

        Note

        When applying the change to a Traffic Light

        • First all bulbs are turned off
        • Only after that changes made in the order are applied

        This means it is only necessary to supply the data about what bulbs should be turned on. E.g. you don't have to turn off a red bulb when turning on the green one.

    Warning

    The first Element in the Lighting Sequences (in most cases) should contain bulb data for every Traffic Light Group. Traffic Light Groups not specified in the first Element will not light up at the beginning of the scene.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#example","title":"Example","text":"

    Lets consider the following lighting sequence element.

    In the Lighting Sequence Element 5 we tell all Traffic Lights in the Vehicle Traffic Light Group 2 to light up their Green Bulb with the color Green and status Solid On which means that they will be turned on all the time. We also implicitly tell them to turn all other Bulbs off.

    In the same time we tell all Traffic Lights in the Pedestrian Traffic Light Group 2 to do the very same thing.

    This state will be active for the next 15 seconds, and after that Traffic Intersection will move to the next Element in the Sequence.

    Now lets consider the following Lighting Sequences Element 6.

    Here we order the Traffic Lights in the Pedestrian Traffic Light Group 2 to light up their Green Bulb with the color Green and status Flashing. We also implicitly tell them to turn all other bulbs off, which were already off from the implicit change in Element 5, so this effectively does nothing.

    Note that Lighting Sequences Element 6 has no orders for Vehicle Traffic Light Group 2. This means that Traffic Lights in the Vehicle Traffic Light Group 2 will hold on to their earlier orders.

    This state will be active for 5 seconds, which means that Traffic Lights in the Vehicle Traffic Light Group 2 will be lighting solid green for the total of 20 seconds.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#how-to-test","title":"How to test","text":"

    To test how your Traffic Intersection behaves simply run the Scene as shown here (but don't launch Autoware). To take a better look at the Traffic Lights you can change to the Scene view by pressing ctrl + 1 - now you can move the camera freely (to go back to the Game view simply press ctrl + 2).

    As the time passes you can examine whether your Traffic Intersection is configured correctly.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/","title":"Load Items From Lanelet","text":""},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#load-items-from-lanelet2","title":"Load items from lanelet2","text":"

    To add RandomTraffic to the Environment, it is necessary to load elements from the lanelet2. As a result of loading, TrafficLanes and StopLines will be added to the scene. Details of these components can be found here.

    Warning

    Before following this tutorial make sure you have added an Environment Script and set a proper MGRS offset position. This position is used when loading elements from the lanelet2!

    1. Click on the AWSIM button in the top menu of the Unity editor and navigate to AWSIM -> Random Traffic -> Load Lanelet.

    2. In the window that pops-up select your osm file, change some Waypoint Settings to suit your needs and click Load.

      Waypoint Settings explanation

      • Resolution - resolution of resampling. Lower values provide better accuracy at the cost of processing time
      • Min Delta Length - minimum length(m) between adjacent points
      • Min Delta Angle - minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve

    3. Traffic Lanes and Stop Lanes should occur in the Hierarchy view. If they appear somewhere else in your Hierarchy tree, then move them into the Environment object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#complete-loaded-trafficlanes","title":"Complete loaded TrafficLanes","text":"

    The Traffic Lanes that were loaded should be configures accordingly to the road situation. The aspects you can configure

    • Right of way

      The right of way has to be configured so that Vehicles know how ot behave in the traffic. To configure this please visit a dedicated section in Add a Traffic Lane. After you have set right of way to all traffic lanes please follow this final step.

    • Stop Line

      Assuming you have all Stop Lines loaded from the lanelet you have to add them to the Traffic Lanes. For detailed instruction please visit a dedicated section in Add a Traffic Lane.

      If - for any reason - you don't have all the Stop Lines added, please follow this dedicated section.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#how-to-test","title":"How to test","text":"

    If you want to test your Traffic Lanes you have to try running a Random Traffic. To verify one particular Traffic Lane or Traffic Lane connection you can make a new spawnable lane next to the Traffic Lane you want to test. This way you can be sure NPCVehicles will start driving on the Traffic Lane you are interested in at the beginning.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#add-a-stopline-manually","title":"Add a StopLine manually","text":"

    When something goes wrong when loading data from lanelet2 or you just want to add another StopLine manually please do the following

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#1-add-a-gameobject","title":"1. Add a GameObject","text":"

    Add a new GameObject StopLine in the StopLines parent object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#2-add-a-stopline-script","title":"2. Add a StopLine Script","text":"

    Add a StopLine Script by clicking 'Add Component' and searching for Stop Line.

    Example

    So far your Stop Line should look like the following

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#3-set-points","title":"3. Set points","text":"

    Set the position of points Element 0 and Element 1. These Elements are the two end points of a Stop Line. The Stop Line will span between these points.

    You don't need to set any data in the 'Transform' section as it is not used anyway.

    StopLine coordinate system

    Please note that the Stop Line Script operates in the global coordinate system. The transformations of StopLine Object and its parent Objects won't affect the Stop Line.

    Example

    In this example you can see that the Position of the Game Object does not affect the position and orientation of the Stop Line.

    For a Game Object in the center of the coordinate system.

    The stop Line is in the specified position.

    However with the Game Object shifted in X axis.

    The Stop Line stays in the same position as before, not affected by any transformations happening to the Game Object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#4-has-stop-sign","title":"4. Has Stop Sign","text":"

    Select whether there is a Stop Sign.

    Select the Has Stop Sign tick-box confirming that this Stop Line has a Stop Sign. The Stop Sign can be either vertical or horizontal.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#5-select-a-traffic-light","title":"5. Select a Traffic Light","text":"

    Select from the drop-down menu the Traffic Light that is on the Traffic Intersection and is facing the vehicle that would be driving on the Traffic Lane connected with the Stop Line you are configuring.

    In other words select the right Traffic Light for the Lane on which your Stop Line is placed.

    Select Traffic Lights visually

    If you have a lot of Traffic Lights it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#6-configure-the-traffic-lane","title":"6. Configure the Traffic Lane","text":"

    Every Stop Line has to be connected to a Traffic Lane. This is done in the Traffic Lane configuration. For this reason please check the Traffic Lane section for more details.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#add-a-trafficlane-manually","title":"Add a TrafficLane manually","text":"

    It is possible that something may go wring when reading a lanelet2 and you need to add an additional Traffic Lane or you just want to add it. To add a Traffic Lane manually please follow the steps below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#1-add-a-gameobject_1","title":"1. Add a GameObject","text":"

    Add a new Game Object called TrafficLane into the TrafficLanes parent Object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#2-add-a-traffic-lane-script","title":"2. Add a Traffic Lane Script","text":"

    Click the 'Add Component' button and search for the Traffic lane script and select it.

    Example

    So far your Traffic Lane should look like the following.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#3-configure-waypoints","title":"3. Configure Waypoints","text":"

    Now we will configure the 'Waypoints' list. This list is an ordered list of nest points defining the Traffic Lane. When you want to add a waypoint to a Traffic Lane just click on the + button or specify the number of waypoints on the list in the field with number to the right from 'Waypoints' identifier.

    The order of elements on this list determines how waypoints are connected.

    Traffic Lane coordinate system

    Please note that the Traffic Lane waypoints are located in the global coordinate system, any transformations set to a Game Object or paren Objects will be ignored.

    This behavior is the same as with the Stop Line. You can see the example provided in the Stop Line tutorial.

    General advice

    • Two waypoints should not be too far away from each other.
    • When creating a turn that is a curvature please keep in mind the angle that is created between two next waypoints connected. The angles should be fairly small - this will translate to a smooth motion of vehicles.
    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#4-select-the-turn-direction","title":"4. Select the Turn Direction","text":"

    You also need to select the Turn Direction. This field describes what are the vehicles traveling on ths Traffic Lane doing in reference to other Traffic Lanes. You need to select whether the vehicles are

    • Driving straight (STRAIGHT)
    • Turning right (RIGHT)
    • Turning left (LEFT)

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#5-configure-next-lanes","title":"5. Configure Next Lanes","text":"

    You need to add all Traffic Lanes that have their beginning in the end of this Traffic Lane into the Next Lanes list. In other words if the vehicle can choose where he wants to drive (e.g. drive straight or drive left with choice of two different Traffic Lines).

    To do this click the + sign in the Next Lanes list and in the element that appeared select the correct Traffic Lane.

    Next Lane example

    Lets consider the following Traffic Intersection.

    In this example we will consider the Traffic Lane driving from the bottom of the screen and turning right. After finishing driving in this Traffic Lane the vehicle has a choice of 4 different Traffic Lanes each turning into different lane on the parallel road.

    All 4 Traffic Lanes are connected to the considered Traffic Lane. This situation is reflected in the Traffic Lane configuration shown below.

    Select Traffic Lanes visually

    If you have a lot of Traffic Lanes it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#6-configure-previous-lanes","title":"6. Configure Previous Lanes","text":"

    Traffic Lane has to have previous Traffic Lanes configured. This is done in the exact same way as configuring next lanes which was shown in the previous step. Please do the same, but add Traffic Lanes that are before the configured one instead of the ones after into the Prev Lanes list.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#7-configure-right-of-way","title":"7. Configure Right Of Way","text":"

    Now we will configure the Right Of Way Lanes. The Right Of Way Lanes is a list of Traffic Lanes that have a priority over the configured one. The process of adding the Right Of Way Lanes is the same as with adding Next Lanes. For this reason we ask you to see the aforementioned step for detailed description on how to do this (the only difference is that you add Traffic Lanes to the Right Of Way Lanes list).

    Right of way example

    In this example lets consider the Traffic Lane highlighted in blue from the Traffic Intersection below.

    This Traffic Lane has to give way to all Traffic Lanes highlighted on yellow. This means all of the yellow Traffic Lanes have to be added to the 'Right Of Way Lanes' list which is reflected on the configuration shown below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#8-add-stop-line","title":"8. Add Stop Line","text":"

    Adding a Stop Line is necessary only when at the end of the configured Traffic Lane the Stop Line is present. If so, please select the correct Stop Line from the drop-down list.

    Select Stop Line visually

    If you have a lot of Stop Lines it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#9-add-speed-limit","title":"9. Add Speed Limit.","text":"

    In the field called Speed Limit simply write the speed limit that is in effect on the configured Traffic Lane.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#10-set-the-right-of-ways","title":"10. Set the Right of Ways","text":"

    To make the Right Of Ways list you configured earlier take effect simply click the 'Set RightOfWays' button.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/","title":"Add TrafficLights","text":""},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#add-trafficlights","title":"Add TrafficLights","text":"

    To add TrafficLights into your Environment follow steps below.

    Tip

    In the Environment you are creating there will most likely be many TrafficLights that should look and work the same way. To simplify the process of creating an environment it is advised to create one TrafficLight of each type with this tutorial and then save them as prefabs that you will be able to reuse.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#1-add-trafficlight-object","title":"1. Add TrafficLight Object","text":"

    Into your Map object in the Hierarchy view add a new Child Object and name it appropriately.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#2-add-a-mesh-filter-and-select-meshes","title":"2. Add a Mesh Filter and select meshes","text":"

    1. Click on the Add Component button.

    2. Search for Mesh filter and select it by clicking on it.

    3. For each TrafficLight specify the mesh you want to use.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#3add-a-mesh-renderer-and-specify-materials","title":"3.Add a Mesh Renderer and specify materials","text":"

    1. The same way as above search for Mesh Renderer and select it.

    2. Now you need to specify individual component materials.

      For example in the Traffic.Lights.001 mesh there are four sub-meshes that need their individual materials.

      To specify a material click on the selection button on Materials element and search for the material you want to use and select it.

      Repeat this process until you specify all materials. When you add one material more than there are sub-meshes you will see this warning. Then just remove the last material and the TrafficLight is prepared.

      Info

      Different material for every bulb is necessary for the color changing behavior that we expect from traffic lights. Even though in most cases you will use the same material for every Bulb, having them as different elements is necessary. Please only use models of TrafficLights that have different Materials Elements for every Bulb.

      Materials order

      When specifying materials remember the order in which they are used in the mesh. Especially remember what Materials Elements are associated with every Bulb in the TrafficLight. This information will be needed later.

      Example

      In the case of Traffic.Lights.001 the bulb materials are ordered starting from the left side with index 1 and increasing to the right.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#4-add-a-mesh-collider","title":"4. Add a Mesh Collider","text":"

    The same way as above search for Mesh Collider and select it. Collider may not seem useful, as the TrafficLight in many cases will be out of reach of vehicles. It is however used for LiDAR simulation, so it is advised to always add colliders to Objects that should be detected by LiDARs.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#5-position-trafficlight-in-the-environment","title":"5. Position TrafficLight in the Environment","text":"

    Finally after configuring all visual aspects of the TrafficLight you can position it in the environment. Do this by dragging a TrafficLight with a square representing a plane or with an arrow representing one axis.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#6-add-trafficlight-script","title":"6. Add TrafficLight Script","text":"

    The Traffic Light Script will enable you to control how the TrafficLight lights up and create sequences.

    1. Click on Add Component, search for the Traffic Light script and select it.

    2. You should see the Bulb Emission config already configured. These are the colors that will be used to light up the Bulbs in TrafficLight. You may adjust them to suit your needs.

    3. You will have to specify Bulb material config, in which you should add elements with fields:

      • Bulb Type - One of the predefined Bulb types that describes the Bulb (its color and pattern).
      • Material Index - Index of the material that you want to be associated with the Bulb Type. This is where you need to use the knowledge from earlier where we said you have to remember what Materials Element corresponds to which bulb sub-mesh.

      Bulb configuration example

      Here we specify an element Type as RED_BULB and associate it with Material that has an index 3. This will result in associating the right most bulb with the name RED_BULB. This information will be of use to us when specifying TrafficLights sequences.

    Success

    Once you have added TrafficLights to your Environment, you can start configuring RandomTraffic which will add moving vehicles to it! Details here.

    "},{"location":"Components/Environment/CreatePCD/","title":"Create PCD","text":""},{"location":"Components/Environment/CreatePCD/#create-pcd","title":"Create PCD","text":"

    This section

    This section is still under development!

    "},{"location":"Components/Environment/CreatePCD/#pointcloudmapper","title":"PointCloudMapper","text":""},{"location":"Components/Environment/CreatePCD/#description","title":"Description","text":"

    PointCloudMapper is a tool for a vehicle based point cloud mapping in a simulation environment. It is very useful when you need a point cloud based on some location, but don't have the possibility to physically map the real place. Instead you can map the simulated environment.

    "},{"location":"Components/Environment/CreatePCD/#required-data","title":"Required Data","text":"

    To properly perform the mapping, make sure you have the following files downloaded and configured:

    • Lanelet2 format OSM data (*.osm file)

    • 3D model map of the area

      How to obtain a map

      You can obtain the 3D model of the area by using a Environment prefab prepared for AWSIM or by creating your own. You can learn how to create you own Environment prefab in this tutorial.

    • Configured in-simulation vehicle object with sensors attached (only the LiDAR is necessary)

      Vehicle model

      For the sake of creating a PCD the vehicle model doesn't have to be accurate. It will be just a carrier for LiDAR. The model can even be a simple box as shown earlier in this tutorial. Make sure it is not visible to the LiDAR, so it does not break the sensor readings.

    "},{"location":"Components/Environment/CreatePCD/#import-osm","title":"Import OSM","text":"

    1. Drag and drop an OSM file into Unity project.

    2. OSM file will be imported as OsmDataContainer.

    "},{"location":"Components/Environment/CreatePCD/#setup-an-environment","title":"Setup an Environment","text":"

    For mapping an Environment prefab is needed. The easiest way is to create a new Scene and import the Environment prefab into it. Details on how to do this can be found on this tutorial page.

    "},{"location":"Components/Environment/CreatePCD/#setup-a-vehicle","title":"Setup a Vehicle","text":"

    Create a Vehicle GameObject in the Hierarchy view.

    "},{"location":"Components/Environment/CreatePCD/#add-visual-elements-optional","title":"Add visual elements (optional)","text":"

    Add vehicle model by adding a Geometry Object as a child of Vehicle and adding all visual elements as children.

    Visual elements

    You can learn how to add visual elements and required components like Mesh Filter or Mesh Renderer in this tutorial.

    "},{"location":"Components/Environment/CreatePCD/#add-a-camera-optional","title":"Add a Camera (optional)","text":"

    Add a Camera component for enhanced visuals by adding a Main Camera Object as a child of Vehicle Object and attaching a Camera Component to it.

    1. Add a Main Camera Object.

    2. Add a Camera Component by clicking 'Add Component' button, searching for it and selecting it.

    3. Change the Transform for an even better visual experience.

      Camera preview

      Observe how the Camera preview changes when adjusting the transformation.

    "},{"location":"Components/Environment/CreatePCD/#setup-vehicle-sensors-rgl","title":"Setup Vehicle Sensors (RGL)","text":"

    This part of the tutorial shows how to add a LiDAR sensor using RGL.

    RGL Scene Manager

    Please make sure that RGLSceneManager is added to the scene. For more details and instruction how to do it please visit this tutorial page.

    1. Create an empty Sensors GameObject as a child of the Vehicle Object.

    2. Create a Lidar GameObject as a child of the Sensors Object.

    3. Attach Lidar Sensor (script) to previously created Lidar Object by clicking on the 'Add Component' button, searching for the script and selecting it.

      Point Cloud Visualization

      Please note that Point Cloud Visualization (script) will be added automatically with the Lidar Sensor (script).

    4. Configure LiDAR pattern, e.g. by selecting one of the available presets.

      Example Lidar Sensor configuration

      Gaussian noise

      Gaussian noise should be disabled to achieve a more accurate map.

    5. Attach RGL Mapping Adapter (script) to previously created Lidar Object by clicking on the 'Add Component' button, searching for the script and selecting it.

    6. Configure RGL Mapping Adapter - e.g. set Leaf Size for filtering.

      Example RGL Mapping Adapter configuration

      Downsampling

      Please note that downsampling is applied on the single LiDAR scans only. If you would like to filter merged scans use the external tool described below.

    "},{"location":"Components/Environment/CreatePCD/#effect-of-leaf-size-to-point-cloud-data-pcd-generation","title":"Effect of Leaf Size to Point Cloud Data (PCD) generation","text":"

    Downsampling aims to reduce PCD size which for large point clouds may achieve gigabytes in exchange for map details. It is essential to find the best balance between the size and acceptable details level.

    A small Leaf Size results in a more detailed PCD, while a large Leaf Size could result in excessive filtering such that objects like buildings are not recorded in the PCD.

    In the following examples, it can be observed that when a Leaf Size is 1.0, point cloud is very detailed. When a Leaf Size is 100.0, buildings are filtered out and results in an empty PCD. A Leaf Size of 10.0 results in a reasonable PCD in the given example.

    Leaf Size = 1.0 Leaf Size = 10.0 Leaf Size = 100.0"},{"location":"Components/Environment/CreatePCD/#setup-pointcloudmapper","title":"Setup PointCloudMapper","text":"

    1. Create a PointCloudMapper GameObject in the Hierarchy view.

    2. Attach Point Cloud Mapper script to previously created Point Cloud Mapper Object by clicking on the 'Add Component' button, searching for the script and selecting it.

    3. Configure the Point Cloud Mapper fields:

      • Osm Container - the OSM file you imported earlier

      • World Origin - MGRS position of the origin of the scene

        World Origin coordinate system

        Use ROS coordinate system for World Origin, not Unity.

      • Capture Location Interval - Distance between consecutive capture points along lanelet centerline
      • Output Pcd File Path - Output relative path from Assets folder
      • Target Vehicle - The vehicle you want to use for point cloud capturing that you created earlier

      Example Point Cloud Mapper configuration

      Lanelet visualization

      It is recommended to disable Lanelet Visualizer by setting Material to None and Width equal to zero. Rendered Lanelet is not ignored by the LiDAR so it would be captured in the PCD.

    "},{"location":"Components/Environment/CreatePCD/#effect-of-capture-location-interval-to-pcd-generation","title":"Effect of Capture Location Interval to PCD generation","text":"

    If the Capture Location Interval is too small, it could result in a sparse PCD where some region of the map is captured well but the other regions aren't captured at all.

    In the below example, Leaf Size of 0.2 was used. Please note that using a different combination of leaf size and Capture Location Interval may result in a different PCD.

    Capture Location Interval = 6 Capture Location Interval = 20 Capture Location Interval = 100"},{"location":"Components/Environment/CreatePCD/#capture-and-generate-pcd","title":"Capture and Generate PCD","text":"

    If you play simulation with a scene prepared with the steps above, PointCloudMapper will automatically start mapping. The vehicle will warp along centerlines by intervals of CaptureLocationInterval and capture point cloud data. PCD file will be written when you stop your scene or all locations in the route are captured.

    If the Vehicle stops moving for longer and you see the following message in the bottom left corner - you can safely stop the scene.

    The Point cloud *.pcd file is saved to the location you specified in the Point Cloud Mapper.

    "},{"location":"Components/Environment/CreatePCD/#pcd-postprocessing","title":"PCD postprocessing","text":"

    Install required tool

    The tool (DownsampleLargePCD) required for PCD conversion can be found under the link. README contains building instruction and usage.

    The generated PCD file is typically too large. Therefore you need to downsample it. Also, it should be converted to ASCII format because Autoware accepts only this format. PointCloudMapper returns PCD in binary format.

    1. Change the working directory to the location with DownsampleLargePCD tool.

    2. Use this tool to downsample and save PCD in ASCII format. 

      ./DownsampleLargePCD -in <PATH_TO_INPUT_PCD> -out <PATH_TO_OUTPUT_PCD> -leaf 0.2,0.2,0.2\n
      • Assuming input PCD is in your working directory and named in_cloud.pcd and output PCD is to be named out_cloud.pcd the command will be: 
        ./DownsampleLargePCD -in in_cloud.pcd -out out_cloud.pcd -leaf 0.2,0.2,0.2\n
      • You can also save PCD in binary format by adding -binary 1 option.

    3. Your PCD is ready to use.

    Converting PCD format without downsampling

    If you don't want to downsample your PCD you can convert PCD file to ASCII format with pcl_convert_pcd_ascii_binary tool. This tool is available in the pcl-tools package and can be installed on Ubuntu with the following command: 

    sudo apt install pcl-tools\n
    To convert your PCD use command: 
    pcl_convert_pcd_ascii_binary <PATH_TO_INPUT_PCD> <PATH_TO_OUTPUT_PCD> 0\n
    "},{"location":"Components/Environment/CreatePCD/#verify-the-pcd","title":"Verify the PCD","text":"

    To verify your PCD you can launch the Autoware with the PCD file specified.

    1. Copy your PCD from the AWSIM project directory to the Autoware map directory.

      cp <PATH_TO_PCD_FILE> <PATH_TO_AUTOWARE_MAP>/\n

    2. Source the ROS and Autoware

      source /opt/ros/humble/setup.bash\nsource <PATH_TO_AUTOWARE>/install/setup.bash\n

    3. Launch the planning simulation with the map directory path (map_path) and PCD file (pointcloud_map_file) specified.

      PCD file location

      The PCD file needs to be located in the Autoware map directory and as a pointcloud_map_file parameter you only supply the file name, not the path.

      Absolute path

      When launching Autoware never use ~/ to specify the home directory. Either write the full absolute path ot use $HOME environmental variable.

      ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit map_path:=<ABSOLUTE_PATH_TO_AUTOWARE_MAP> pointcloud_map_file:=<PCD_FILE_NAME>\n

    4. Wait for the Autoware to finish loading and inspect the PCD visually given the Effect of Leaf Size and Effect of Capture Location Interval.

    "},{"location":"Components/Environment/CreatePCD/#sample-scene","title":"Sample Scene","text":"

    PointCloudMapping.unity is a sample scene for PointCloudMapper showcase. It requires setup of OSM data and 3D model map of the area according to the steps above.

    Sample Mapping Scene

    In this example you can see a correctly configured Point Cloud Mapping Scene.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/","title":"LaneletBoundsVisualizer","text":""},{"location":"Components/Environment/LaneletBoundsVisualizer/#lanelet-bounds-visualizer","title":"Lanelet Bounds Visualizer","text":"

    Lanelet Bounds Visualizer is an Unity Editor extension allowing the user to load the left and right bounds of Lanelet to the Unity scene.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/#usage","title":"Usage","text":"

    The lanelet bounds load process can be performed by opening AWSIM -> Visualize -> Load Lanelet Bounds at the top toolbar of Unity Editor.

    A window shown below will pop up. Select your Osm Data Container to specify which OSM data to load the Lanelet from.

    The user can select whether to load the raw Lanelet or to adjust the resolution of the Lanelet by specifying the waypoint settings.

    To load the raw Lanelet, simply click the Load Raw Lanelet button.

    If the user wishes to change the resolution of the Lanelet, adjust the parameters of the Waypoint Settings as described below, and click the Load with Waypoint Settings button.

    • Resolution : resolution of resampling. Lower values provide better accuracy at the cost of processing time.
    • Min Delta Length : minimum length(m) between adjacent points.
    • Min Delta Angle : minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve.

    Once the Lanelet is successfully loaded, Lanelet bounds will be generated as a new GameObject named LaneletBounds.

    To visualize the LaneletBounds, make sure Gizmos is turned on and select the LaneletBounds GameObject.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/#important-notes","title":"Important Notes","text":"

    Generally speaking, visualizing Lanelet Bounds will result in a very laggy simulation. Therefore, it is recommended to hide the LaneletBounds GameObject when not used. The lag of the simulation becomes worse as you set the resolution of the Lanelet Bounds higher, so it is also recommended to set the resolution within a reasonable range.

    It is also important to note that no matter how high you set the resolution to be, it will not be any better than the original Lanelet (i.e. the raw data). Rather, the computational load will increase and the simulation will become more laggy. If the user wishes to get the highest quality of Lanelet Bounds, it is recommended to use the Load Raw Lanelet button.

    In short, Waypoint Setting parameters should be thought of as parameters to decrease the resolution from the original Lanelet to decrease the computational load and thus, reducing the lag of the simulation.

    Higher Resolution Raw Lanelet Lower Resolution"},{"location":"Components/Environment/SmokeSimulator/","title":"SmokeSimulator","text":""},{"location":"Components/Environment/SmokeSimulator/#smoke-simulator","title":"Smoke Simulator","text":"

    Simulating smoke in AWSIM may be useful when one wants to simulate exhaust gases from vehicles, smoke from emergency flare, etc.

    In Unity, it is common to use Particle System to simulate smokes. However, smoke simulated by Particle System cannot be sensed by RGL in AWSIM although in reality, smokes are detected by LiDAR.

    Smoke Simulator was developed to simulate smokes that can be detected by RGL in Unity. Smoke Simulator works by instantiating many small cubic GameObjects called Smoke Particles and allows each particle to be detected by RGL.

    This document describes how to use the Smoke Simulator.

    "},{"location":"Components/Environment/SmokeSimulator/#setting-smoke-simulator","title":"Setting Smoke Simulator","text":"

    1.Create an empty GameObject

    2.Attach SmokeGenerator.cs to the previously created GameObject.

    3.Adjust the parameters of the SmokeGenerator as described below:

    • Max Particle: Specifies the maximum number of particles created by the Smoke Generator
    • Particle Range Radius: Specifies the radius of a circle, centered at the GameObject, which defines the region in which Smoke Particles are generated in
    • Particle Size: Specifies the edge of a Smoke Particle
    • Average Lifetime: Specifies the average lifetime of a Smoke Particle

    • Variation Lifetime: Specifies the variation of lifetime of Smoke Particles.

      The lifetime of a Smoke Particle is calculated as follows:

      `lifetime` = `Average Lifetime` + Random.Range(-`Variation Lifetime`, `Variation Lifetime`)\n
    • Physics: These parameters can be adjusted to specify the behavior of the smoke particles.
      • Initial Plane Velocity: Specifies the velocity of a SmokeParticle in the x-z plane
      • Initial Vertical Velocity: Specifies the velocity of a SmokeParticle in the vertical direction
      • Plane Acceleration: Specifies the acceleration of a SmokeParticle in the x-z plane
      • Vertical Acceleration: Specifies the acceleration of a SmokeParticle in the vertical direction

    4.(Optional): You may also specify the Material of Smoke Particles. If this field is unspecified, a default material is used

    "},{"location":"Components/Environment/SmokeSimulator/#example-of-different-smokes","title":"Example of Different Smokes","text":""},{"location":"Components/Environment/SmokeSimulator/#thin-smoke","title":"Thin Smoke","text":""},{"location":"Components/Environment/SmokeSimulator/#heavy-smoke","title":"Heavy Smoke","text":""},{"location":"Components/Environment/V2I/","title":"V2I","text":""},{"location":"Components/Environment/V2I/#v2i-vehicle-to-infrastructure","title":"V2I (Vehicle-to-Infrastructure)","text":"

    V2I is a component that simulates V2I communication protocol which allows to exchange data between vehicles and road infrastructure. In the current version of AWSIM, the V2I component publishes information about traffic lights.

    "},{"location":"Components/Environment/V2I/#how-to-add-v2i-to-the-environment","title":"How to add V2I to the environment","text":""},{"location":"Components/Environment/V2I/#assign-lanelet2-wayid-and-relationid-to-trafficlight-object","title":"Assign Lanelet2 WayID and RelationID to TrafficLight object","text":"

    1. Load items from lanelet2 following the instruction

    2. Verify if Traffic Light Lanelet ID component has been added to Traffic Light game objects.

    3. Verify if WayID and RelationID has been correctly assigned. You can use Vector Map Builder as presented below

    "},{"location":"Components/Environment/V2I/#add-manually-traffic-light-lanelet-id-component-alternatively","title":"Add manually Traffic Light Lanelet ID component (alternatively)","text":"

    If for some reason, Traffic Light Lanelet ID component is not added to Traffic Light object.

    1. Add component manually

    2. Fill Way ID

    3. Fill Relation ID

    "},{"location":"Components/Environment/V2I/#add-v2i-prefab","title":"Add V2I prefab","text":""},{"location":"Components/Environment/V2I/#select-ego-transform","title":"Select EGO transform","text":""},{"location":"Components/Environment/V2I/#parameters","title":"Parameters","text":"Name Type Description Output Hz int Topic publication frequency Ego Vehicle Transform transform Ego Vehicle object transform Ego Distance To Traffic Signals double Maximum distance between Traffic Light and Ego Traffic Signal ID enum Possibility to select if as traffic_signal_id field in msg is Relation ID or Way ID Traffic Signals Topic string Topic name

    Note

    V2I feature can be used as Traffic Light ground truth information, and for that usage Way ID is supposed to be selected.

    "},{"location":"Components/ROS2/AddACustomROS2Message/","title":"Add custom ROS2 msg","text":""},{"location":"Components/ROS2/AddACustomROS2Message/#add-a-custom-ros2-message","title":"Add a custom ROS2 message","text":"

    If you want to use custom message in AWSIM, you need to generate the appropriate files, to do this you have to build ROS2ForUnity yourself - please follow the steps below. Remember to start with prerequisities though.

    ROS2ForUnity role

    For a better understanding of the role of ROS2ForUnity and the messages used, we encourage you to read this section.

    custom_msgs

    In order to simplify this tutorial, the name of the package containing the custom message is assumed to be custom_msgs - remember to replace it with the name of your package.

    "},{"location":"Components/ROS2/AddACustomROS2Message/#prerequisites","title":"Prerequisites","text":"

    ROS2ForUnity depends on a ros2cs - a C# .NET library for ROS2. This library is already included so you don't need to install it, but there are a few prerequisites that must be resolved first.

    Please select your system and resolve all prerequisites:

    UbuntuWindows
    • ros2cs prerequisites for Ubuntu
    • ROS2 version is humble and is located in /opt/ros/humble
    • Your package with custom message is located in the home directory ~/custom_msgs or is hosted on git repository.
    • Shell - commands have to be executed from the bash shell

    • ros2cs prerequisites for Windows

      Question

      Tests are not working ('charmap' codec can't decode byte) on Windows - look at troubleshooting here

    • ROS2 version is humble and is located in C:\\ros2_humble
    • Your package with custom message package is located in the home directory C:\\custom_msgs or is hosted on git repository.
    • Shell - commands should be executed from the powershell shell
    "},{"location":"Components/ROS2/AddACustomROS2Message/#1-workspace-preparation","title":"1. Workspace preparation","text":"

    1. Clone ROS2ForUnity repository by execute command:

      UbuntuWindows 
      git clone https://github.com/RobotecAI/ros2-for-unity ~/\n

      Warning

      The cloned ROS 2 For Unity repository must be located in the home directory ~/.

      git clone https://github.com/RobotecAI/ros2-for-unity /C\n

      Warning

      The cloned ROS 2 For Unity repository must be located in the home directory C:\\.

    2. Pull dependent repositories by execute commands:

      UbuntuWindows 
      cd ~/ros2-for-unity\n. /opt/ros/humble/setup.bash\n./pull_repositories.sh\n
      cd C:\\ros2-for-unity\nC:\\ros2_humble\\local_setup.ps1\n.\\pull_repositories.ps1\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#2-setup-custom_msgs-package","title":"2. Setup custom_msgs package","text":"

    The method to add a custom package to build depends on where it is located. The package can be on your local machine or just be hosted on a git repository. Please, choose the appropriate option and follow the instructions.

    "},{"location":"Components/ROS2/AddACustomROS2Message/#21-package-contained-on-local-machine","title":"2.1. Package contained on local machine","text":"

    1. Copy the custom_msgs package with custom message to the folder to src/ros2cs/custom_messages directory

      UbuntuWindows 
      cp -r ~/custom_msgs ~/ros2-for-unity/src/ros2cs/custom_messages/\n
      Copy-Item 'C:\\custom_msgs' -Destination 'C:\\ros2-for-unity\\src\\custom_messages'\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#22-package-hosted-on-git-repository","title":"2.2. Package hosted on git repository","text":"
    1. Open ros2-for-unity/ros2_for_unity_custom_messages.repos file in editor.

    2. Modify the contents of the file shown below, uncomment and set:

      • <package_name> - to your package name - so in this case custom_msgs,
      • <repo_url> - to repository address,
      • <repo_branch> - to desired branch. 
        repositories:\n#  src/ros2cs/custom_messages/<package_name>:\n#    type: git\n#    url: <repo_url>\n#    version: <repo_branch>\n

      Example

      Below is an example of a file configured to pull 2 packages (custom_msgs,autoware_msgs) of messages hosted on a git repository. 

      # NOTE: Use this file if you want to build with custom messages that reside in a separate remote repo.\n# NOTE: use the following format\n\nrepositories:\n    src/ros2cs/custom_messages/custom_msgs:\n        type: git\n        url: https://github.com/tier4/custom_msgs.git\n        version: main\n    src/ros2cs/custom_messages/autoware_msgs:\n        type: git\n        url: https://github.com/tier4/autoware_msgs.git\n        version: tier4/main\n

    3. Now pull the repositories again (also the custom_msgs package repository)

      UbuntuWindows 
      cd ~/ros2-for-unity\n./pull_repositories.sh\n
      cd C:\\ros2-for-unity\n.\\pull_repositories.ps1\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#3-build-ros-2-for-unity","title":"3. Build ROS 2 For Unity","text":"

    Build ROS2ForUnity with custom message packages using the following commands:

    UbuntuWindows 
    cd ~/ros2-for-unity\n./build.sh --standalone\n
    cd C:\\ros2-for-unity\n.\\build.ps1 -standalone\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#4-install-custom_msgs-to-awsim","title":"4. Install custom_msgs to AWSIM","text":"

    New ROS2ForUnity build, which you just made in step 3, contains multiple libraries that already exist in the AWSIM. To install custom_msgs and not copy all other unnecessary files, you should get the custom_msgs related libraries only.

    You can find them in following directories and simply copy to the analogous directories in AWSIM/Assets/Ros2ForUnity folder, or use the script described here.

    UbuntuWindows
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins which names matches custom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Linux/x86_64/ which names matches libcustom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins which names matches custom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Windows/x86_64/ which names matches custom_msgs_*
    "},{"location":"Components/ROS2/AddACustomROS2Message/#automation-of-copying-message-files","title":"Automation of copying message files","text":"UbuntuWindows

    To automate the process, you can use a script that copies all files related to your custom_msgs package.

    1. Create a file named copy_custom_msgs.sh in directory ~/ros2-for-unity/ and paste the following content into it. 
      #!/bin/bash\necho \"CUSTOM_MSGS_PACKAGE_NAME: $1\"\necho \"AWSIM_DIR_PATH: $2\"\nfind ./install/asset/Ros2ForUnity/Plugins -maxdepth 1 -name \"$1*\"    -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins \\;\nfind ./install/asset/Ros2ForUnity/Plugins/Linux/x86_64 -maxdepth 1 -name     \"lib$1*\" -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins/Linux/x86_64 \\;\n
    2. Save the file and give it executable rights with the command: 
      chmod a+x copy_msgs.sh\n
    3. Run the script with two arguments: 
      ./copy_custom_msgs.sh <CUSTOM_MSGS_PACKAGE_NAME> <AWSIM_DIR_PATH>\n
    • <CUSTOM_MSGS_PACKAGE_NAME> - the first one which is the name of the package with messages - in this case custom_msgs,
    • <AWSIM_DIR_PATH> - the second which is the path to the cloned AWSIM repository.

    Example

    ./copy_custom_msgs.sh custom_msgs ~/unity/AWSIM/\n

    To automate the process, you can use these commands with changed:

    • <CUSTOM_MSGS_PACKAGE_NAME> - the name of your package with messages - in this case custom_msgs,
    • <AWSIM_DIR_PATH> - to path to the cloned AWSIM repository 
      Get-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\\Assets\\Ros2ForUnity\\Plugins\nGet-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\Windows\\x86_64\\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\\Assets\\Ros2ForUnity\\Plugins\\Windows\\x86_64\n

    Example

    Get-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\* -Include @('custom_msgs*') | Copy-Item -Destination C:\\unity\\AWSIM\\Assets\\Ros2ForUnity\\Plugins\nGet-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\Windows\\x86_64\\* -Include @('custom_msgs*') | Copy-Item -Destination C:\\unity\\AWSIM\\Assets\\Ros2ForUnity\\Plugins\\Windows\\x86_64\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#5-test","title":"5. Test","text":"

    Make sure that the package files custom_msgs have been properly copied to the AWSIM/Assets/Ros2ForUnity. Then try to create a message object as described in this section and check in the console of Unity Editor if it compiles without errors.

    "},{"location":"Components/ROS2/ROS2ForUnity/","title":"ROS2 For Unity","text":""},{"location":"Components/ROS2/ROS2ForUnity/#ros2-for-unity","title":"ROS2 For Unity","text":"

    Ros2ForUnity (R2FU) module is a communication solution that effectively connects Unity and the ROS2 ecosystem, maintaining a strong integration. Unlike other solutions, it doesn't rely on bridging communication but rather utilizes the ROS2 middleware stack (specifically the rcl layer and below), enabling the inclusion of ROS2 nodes within Unity simulations.

    R2FU is used in AWSIM for many reasons. First of all, because it offers high-performance integration between Unity and ROS2, with improved throughput and lower latencies compared to bridging solutions. It provides real ROS2 functionality for simulation entities in Unity, supports standard and custom messages, and includes convenient abstractions and tools, all wrapped as a Unity asset. For a detailed description, please see README.

    "},{"location":"Components/ROS2/ROS2ForUnity/#prerequisites","title":"Prerequisites","text":"

    This asset can be prepared in two flavours:

    • standalone mode - where no ROS2 installation is required on target machine, e.g., your Unity simulation server. All required dependencies are installed and can be used e.g. as a complete set of Unity plugins.
    • overlay mode - where the ROS2 installation is required on target machine. Only asset libraries and generated messages are installed therefore ROS2 instance must be sourced.

    By default, asset R2FU in AWSIM is prepared in standalone mode.

    Warning

    To avoid internal conflicts between the standalone libraries, and sourced ones, ROS2 instance shouldn't be sourced before running AWSIM or the Unity Editor.

    Can't see topics

    There are no errors but I can't see topics published by R2FU

    • Make sure your DDS (Localhost settings) config is correct.
    • Sometimes ROS2 daemon brakes up when changing network interfaces or ROS2 version.

    Try to stop it forcefully (pkill -9 ros2_daemon) and restart (ros2 daemon start).

    "},{"location":"Components/ROS2/ROS2ForUnity/#concept","title":"Concept","text":"

    Describing the concept of using R2FU in AWSIM, we distinguish:

    • ROS2Node - it is the equivalent of a node in ROS2, it has its own name, it can have any number of subscribers, publishers, service servers and service clients. In the current AWSIM implementation, there is only one main node.
    • ROS2Clock - it is responsible for generating the simulation time using the selected source.
    • SimulatorROS2Node - it is a class that is directly responsible for AWSIM<->ROS2 communication, and contains one instance each of ROS2Node and ROS2Clock, so it creates the main AWSIM node in ROS2 and simulates the time from the selected source (currently UnityTimeSource is used). It is initialized at the moment of running the scene in Unity - thanks to the RuntimeInitializeOnLoadMethod mark.
    • Publisher - it is the equivalent of the publisher in ROS2, it uses a single topic on which it can publish a selected type of message, and it has a selected QoS profile. Each publisher in AWSIM is created in ROS2Node object of class SimulatorROS2Node.
    • Subscriber - it is the equivalent of the subscriber in ROS2, it uses a single topic from which it subscribes to the selected type of message, and it has a selected QoS profile. Each subscriber in AWSIM is created in ROS2Node object of class SimulatorROS2Node.

    The SimulatorROS2Node implementation, thanks to the use of R2FU, allows you to add communication via ROS2 to any Unity component. For example, we can receive control commands from any other ROS2 node and publish the current state of Ego, such as its position in the environment.

    Simulation time

    If you want to use system time (ROS2 time) instead of Unity time, use ROS2TimeSource instead of UnityTimeSource in the SimulatorROS2Node class.

    "},{"location":"Components/ROS2/ROS2ForUnity/#package-structure","title":"Package structure","text":"

    Ros2ForUnity asset contains:

    • Plugins - dynamically loaded libraries for Windows and Linux (*.dll and *.so files). In addition to the necessary libraries, here are the libraries created as a result of generation the types of ROS2 messages that are used in communication.
    • Scripts - scripts for using R2FU in Unity - details below.
    • Extension Scripts - scripts for using R2FU in AWSIM, provide abstractions of a single main Node and simplify the interface - details below. These scripts are not in the library itself, but directly in the directory Assets/AWSIM/Scripts/ROS/**.
    "},{"location":"Components/ROS2/ROS2ForUnity/#scripts","title":"Scripts","text":"
    • ROS2UnityCore - the principal class for handling ROS2 nodes and executables. Spins and executes actions (e.g. clock, sensor publish triggers) in a dedicated thread.
    • ROS2UnityComponent - ROS2UnityCore adapted to work as a Unity component.
    • ROS2Node - a class representing a ROS2 node, it should be constructed through ROS2UnityComponent class, which also handles spinning.
    • ROS2ForUnity - an internal class responsible for handling checking, proper initialization and shutdown of ROS2 communication,
    • ROS2ListenerExample - an example class provided for testing of basic ROS2->Unity communication.
    • ROS2TalkerExample - an example class provided for testing of basic Unity->ROS2 communication.
    • ROS2PerformanceTest - an example class provided for performance testing of ROS2<->Unity communication.
    • Sensor - an abstract base class for ROS2-enabled sensor.
    • Transformations - a set of transformation functions between coordinate systems of Unity and ROS2.
    • PostInstall - an internal class responsible for installing R2FU metadata files.
    • Time scripts - a set of classes that provide the ability to use different time sources:
      • ROS2Clock - ROS2 clock class that for interfacing between a time source (Unity or ROS2 system time) and ROS2 messages.
      • ROS2TimeSource - acquires ROS2 time (system time by default).
      • UnityTimeSource - acquires Unity time.
      • DotnetTimeSource - acquires Unity DateTime based clock that has resolution increased using Stopwatch.
      • ITimeSource - interface for general time extraction from any source.
      • TimeUtils - utils for time conversion.
    "},{"location":"Components/ROS2/ROS2ForUnity/#extension-scripts","title":"Extension Scripts","text":"

    Additionally, in order to adapt AWSIM to the use of R2FU, the following scripts are used:

    • SimulatorROS2Node - it is a class that is directly responsible for AWSIM<->ROS2 communication.

    • ClockPublisher - allows the publication of the simulation time from the clock running in the SimulatorROS2Node. It must be added as a component to the scene in order to publish the current time when the scene is run.

    • QoSSettings - it is the equivalent of ROS2 QoS, which allows to specify the QoS for subscribers and publishers in AWSIM. It uses the QualityOfServiceProfile implementation from the Ros2cs library.
    • ROS2Utility - it is a class with utils that allow, for example, to convert positions in the ROS2 coordinate system to the AWSIM coordinate system.
    • DiagnosticsManager - prints diagnostics for desired elements described in *.yaml config file.
    "},{"location":"Components/ROS2/ROS2ForUnity/#default-message-types","title":"Default message types","text":"

    The basic ROS2 msgs types that are supported in AWSIM by default include:

    • common_interfaces:
      • std_msgs.
      • geometry_msgs,
      • sensor_msgs,
      • nav_msgs,
      • diagnostic_msgs,
    • rcl_interfaces:
      • builtin_interfaces,
      • action_msgs,
      • rosgraph_msgs,
      • test_msgs.
    • autoware_msgs:
      • autoware_common_msgs,
      • autoware_control_msgs,
      • autoware_localization_msgs,
      • autoware_map_msgs,
      • autoware_perception_msgs,
      • autoware_planning_msgs,
      • autoware_sensing_msgs,
      • autoware_system_msgs,
      • autoware_vehicle_msgs.
    • tier4_autoware_msgs:
      • tier4_control_msgs,
      • tier4_vehicle_msgs.
    • Others:
      • tf2_msgs,
      • unique_identifier_msgs.

    In order for the message package to be used in Unity, its *.dll and *.so libraries must be generated using R2FU.

    Custom message

    If you want to generate a custom message to allow it to be used in AWSIM please read this tutorial.

    "},{"location":"Components/ROS2/ROS2ForUnity/#use-of-generated-messages-in-unity","title":"Use of generated messages in Unity","text":"

    Each message type is composed of other types - which can also be a complex type. All of them are based on built-in C# types. The most common built-in types in messages are bool, int, double and string. These types have their communication equivalents using ROS2.

    A good example of a complex type that is added to other complex types in order to specify a reference - in the form of a timestamp and a frame - is std_msgs/Header. This message has the following form:

    builtin_interfaces/msg/Time stamp\nstring frame_id\n

    ROS2 directive

    In order to work with ROS2 in Unity, remember to add the directive using ROS2; at the top of the file to import types from this namespace.

    "},{"location":"Components/ROS2/ROS2ForUnity/#create-an-object","title":"Create an object","text":"

    The simplest way to create an object of Header type is:

    var header = new std_msgs.msg.Header()\n{\n    Frame_id = \"map\"\n}\n

    It is not required to define the value of each field. As you can see, it creates an object, filling only frame_id field - and left the field of complex builtin_interfaces/msg/Time type initialized by default. Time is an important element of any message, how to fill it is written here.

    "},{"location":"Components/ROS2/ROS2ForUnity/#accessing-and-filling-in-message-fields","title":"Accessing and filling in message fields","text":"

    As you might have noticed in the previous example, a ROS2 message in Unity is just a structure containing the same fields - keep the same names and types. Access to its fields for reading and filling is the same as for any C# structure.

    var header2 = new std_msgs.msg.Header();\nheader2.Frame_id = \"map\";\nheader2.Stamp.sec = \"1234567\";\nDebug.Log($\"StampSec: {header2.Stamp.sec} and Frame: {header2.Frame_id}\");\n

    Field names

    There is one always-present difference in field names. The first letter of each message field in Unity is always uppercase - even if the base ROS2 message from which it is generated is lowercase.

    "},{"location":"Components/ROS2/ROS2ForUnity/#filling-a-time","title":"Filling a time","text":"

    In order to complete the time field of the Header message, we recommend the following methods in AWSIM:

    1. When the message has no Header but only the Time type:

      var header2 = new std_msgs.msg.Header();\nheader2.Stamp = SimulatorROS2Node.GetCurrentRosTime();\n

    2. When the message has a Header - like for example autoware_vehicle_msgs/VelocityReport:

      velocityReportMsg = new autoware_vehicle_msgs.msg.VelocityReport()\n{\n    Header = new std_msgs.msg.Header()\n    {\n        Frame_id = \"map\",\n    }\n};\nvar velocityReportMsgHeader = velocityReportMsg as MessageWithHeader;\nSimulatorROS2Node.UpdateROSTimestamp(ref velocityReportMsgHeader);\n

    These methods allow to fill the Time field in the message object with the simulation time - from ROS2Clock

    "},{"location":"Components/ROS2/ROS2ForUnity/#create-a-message-with-array","title":"Create a message with array","text":"

    Some message types contain an array of some type. An example of such a message is nav_msgs/Path, which has a PoseStamped array. In order to fill such an array, you must first create a List<T>, fill it and then convert it to a raw array.

    var posesList = new List<geometry_msgs.msg.PoseStamped>();\nfor(int i=0; i<=5;++i)\n{\n    var poseStampedMsg = new geometry_msgs.msg.PoseStamped();\n    poseStampedMsg.Pose.Position.X = i;\n    poseStampedMsg.Pose.Position.Y = 5-i;\n    var poseStampedMsgHeader = poseStampedMsg as MessageWithHeader;\n    SimulatorROS2Node.UpdateROSTimestamp(ref poseStampedMsgHeader);\n    posesList.Add(poseStampedMsg);\n}\nvar pathMsg = new nav_msgs.msg.Path(){Poses=posesList.ToArray()};\nvar pathMsgHeader = pathMsg as MessageWithHeader;\nSimulatorROS2Node.UpdateROSTimestamp(ref pathMsgHeader);\n// pathMsg is ready\n
    "},{"location":"Components/ROS2/ROS2ForUnity/#publish-on-the-topic","title":"Publish on the topic","text":"

    In order to publish messages, a publisher object must be created. The static method CreatePublisher of the SimulatorROS2Node makes it easy. You must specify the type of message, the topic on which it will be published and the QoS profile. Below is an example of autoware_vehicle_msgs.msg.VelocityReport type message publication with a frequency of 30Hz on /vehicle/status/velocity_status topic, the QoS profile is (Reliability=Reliable, Durability=Volatile, History=Keep last, Depth=1):

    using UnityEngine;\nusing ROS2;\n\nnamespace AWSIM\n{\n    public class VehicleReportRos2Publisher : MonoBehaviour\n    {\n        float timer = 0;\n        int publishHz = 30;\n        QoSSettings qosSettings = new QoSSettings()\n        {\n            ReliabilityPolicy = ReliabilityPolicy.QOS_POLICY_RELIABILITY_RELIABLE,\n            DurabilityPolicy = DurabilityPolicy.QOS_POLICY_DURABILITY_VOLATILE,\n            HistoryPolicy = HistoryPolicy.QOS_POLICY_HISTORY_KEEP_LAST,\n            Depth = 1,\n        };\n        string velocityReportTopic = \"/vehicle/status/velocity_status\";\n        autoware_vehicle_msgs.msg.VelocityReport velocityReportMsg;\n        IPublisher<autoware_vehicle_msgs.msg.VelocityReport> velocityReportPublisher;\n\n        void Start()\n        {\n            // Create a message object and fill in the constant fields\n            velocityReportMsg = new autoware_vehicle_msgs.msg.VelocityReport()\n            {\n                Header = new std_msgs.msg.Header()\n                {\n                    Frame_id = \"map\",\n                }\n            };\n\n            // Create publisher with specific topic and QoS profile\n            velocityReportPublisher = SimulatorROS2Node.CreatePublisher<autoware_vehicle_msgs.msg.VelocityReport>(velocityReportTopic, qosSettings.GetQoSProfile());\n        }\n\n         bool NeedToPublish()\n        {\n            timer += Time.deltaTime;\n            var interval = 1.0f / publishHz;\n            interval -= 0.00001f;\n            if (timer < interval)\n                return false;\n            timer = 0;\n            return true;\n        }\n\n        void FixedUpdate()\n        {\n            // Provide publications with a given frequency\n            if (NeedToPublish())\n            {\n                // Fill in non-constant fields\n                velocityReportMsg.Longitudinal_velocity = 1.00f;\n                velocityReportMsg.Lateral_velocity = 0.00f;\n                velocityReportMsg.Heading_rate = 0.00f;\n\n                // Update Stamp\n                var velocityReportMsgHeader = velocityReportMsg as MessageWithHeader;\n                SimulatorROS2Node.UpdateROSTimestamp(ref velocityReportMsgHeader);\n\n                // Publish\n                velocityReportPublisher.Publish(velocityReportMsg);\n            }\n        }\n    }\n}\n
    "},{"location":"Components/ROS2/ROS2ForUnity/#upper-limit-to-publish-rate","title":"Upper limit to publish rate","text":"

    The above example demonstrates the implementation of the 'publish' method within the FixedUpdate Unity event method. However, this approach has certain limitations. The maximum output frequency is directly tied to the current value of Fixed TimeStep specified in the Project Settings. Considering that the AWSIM is targeting a frame rate of 60 frames per second (FPS), the current Fixed TimeStep is set to 1/60s. And this impose 60Hz as a limitation on the publish rate for any sensor, which is implemented within FixedUpdate method. In case a higher output frequency be necessary, an alternative implementation must be considered or adjustments made to the Fixed TimeStep setting in the Editor->Project Settings->Time.

    The table provided below presents a list of sensors along with examples of topics that are constrained by the Fixed TimeStep limitation.

    Object Topic GNSS Sensor /sensing/gnss/pose IMU Sensor /sensing/imu/tamagawa/imu_raw Traffic Camera /sensing/camera/traffic_light/image_raw Pose Sensor /awsim/ground_truth/vehicle/pose OdometrySensor /awsim/ground_truth/localization/kinematic_state LIDAR /sensing/lidar/top/pointcloud_raw Vehicle Status /vehicle/status/velocity_status

    If the sensor or any other publishing object within AWSIM does not have any direct correlation with physics (i.e., does not require synchronization with physics), it can be implemented without using the FixedUpdate method. Consequently, this allows the bypass of upper limits imposed by the Fixed TimeStep.

    The table presented below shows a list of objects that are not constrained by the Fixed TimeStep limitation.

    Object Topic Clock /clock"},{"location":"Components/ROS2/ROS2ForUnity/#subscribe-to-the-topic","title":"Subscribe to the topic","text":"

    In order to subscribe messages, a subscriber object must be created. The static method CreateSubscription of the SimulatorROS2Node makes it easy. You must specify the type of message, the topic from which it will be subscribed and the QoS profile. In addition, the callback must be defined, which will be called when the message is received - in particular, it can be defined as a lambda expression. Below is an example of std_msgs.msg.Bool type message subscription on /vehicle/is_vehicle_stopped topic, the QoS profile is \u201csystem default\u201d: 

    using UnityEngine;\nusing ROS2;\n\nnamespace AWSIM\n{\n    public class VehicleStoppedSubscriber : MonoBehaviour\n    {\n        QoSSettings qosSettings = new QoSSettings();\n        string isVehicleStoppedTopic = \"/vehicle/is_vehicle_stopped\";\n        bool isVehicleStopped = false;\n        ISubscription<std_msgs.msg.Bool> isVehicleStoppedSubscriber;\n\n        void Start()\n        {\n            isVehicleStoppedSubscriber = SimulatorROS2Node.CreateSubscription<std_msgs.msg.Bool>(isVehicleStoppedTopic, VehicleStoppedCallback, qosSettings.GetQoSProfile());\n        }\n\n        void VehicleStoppedCallback(std_msgs.msg.Bool msg)\n        {\n            isVehicleStopped = msg.Data;\n        }\n\n        void OnDestroy()\n        {\n            SimulatorROS2Node.RemoveSubscription<std_msgs.msg.Bool>(isVehicleStoppedSubscriber);\n        }\n    }\n}\n
    "},{"location":"Components/ROS2/ROS2TopicList/","title":"ROS2 topic list","text":""},{"location":"Components/ROS2/ROS2TopicList/#ros2-topic-list","title":"ROS2 topic list","text":"

    The following is a summary of the ROS2 topics that the AWSIM node subscribes to and publishes on.

    Ros2ForUnity

    AWSIM works with ROS2 thanks to the use of Ros2ForUnity - read the details here. If you want to generate a custom message to allow it to be used in AWSIM please read this tutorial.

    "},{"location":"Components/ROS2/ROS2TopicList/#list-of-subscribers","title":"List of subscribers","text":"Category Topic Message type frame_id Hz QoS

    Control

    Ackermann Control /control/command/control_cmd autoware_control_msgs/msg/Control - 60 Reliable, TransientLocal, KeepLast/1 Gear /control/command/gear_cmd autoware_vehicle_msgs/msg/GearCommand - 10 Reliable, TransientLocal, KeepLast/1 Turn Indicators /control/command/turn_indicators_cmd autoware_vehicle_msgs/TurnIndicatorsCommand - 10 Reliable, TransientLocal, KeepLast/1 Hazard Lights /control/command/hazard_lights_cmd autoware_vehicle_msgs/HazardLightsCommand - 10 Reliable, TransientLocal, KeepLast/1 Emergency /control/command/emergency_cmd tier4_vehicle_msgs/msg/VehicleEmergencyStamped - 60 Reliable, TransientLocal, KeepLast/1"},{"location":"Components/ROS2/ROS2TopicList/#list-of-publishers","title":"List of publishers","text":"Category Topic Message type frame_id Hz QoS

    Clock

    /clock rosgraph_msgs/Clock - 100 Best effort,Volatile,Keep last/1

    Sensors

    Camera /sensing/camera/traffic_light/camera_info sensor_msgs/CameraInfo traffic_light_left_camera/camera_link 10 Best effort,Volatile,Keep last/1 Camera /sensing/camera/traffic_light/image_raw sensor_msgs/Image traffic_light_left_camera/camera_link 10 Best effort,Volatile,Keep last/1 GNSS /sensing/gnss/pose geometry_msgs/Pose gnss_link 1 Reliable,Volatile,Keep last/1 GNSS /sensing/gnss/pose_with_covariance geometry_msgs/PoseWithCovarianceStamped gnss_link 1 Reliable,Volatile,Keep last/1 IMU /sensing/imu/tamagawa/imu_raw sensor_msgs/Imu tamagawa/imu_link 30 Reliable,Volatile,Keep last/1000 Top LiDAR /sensing/lidar/top/pointcloud_raw sensor_msgs/PointCloud2 sensor_kit_base_link 10 Best effort,Volatile,Keep last/5 Top LiDAR /sensing/lidar/top/pointcloud_raw_ex sensor_msgs/PointCloud2 sensor_kit_base_link 10 Best effort,Volatile,Keep last/5

    Vehicle Status

    Velocity /vehicle/status/velocity_status autoware_vehicle_msgs/VelocityReport base_line 30 Reliable,Volatile,Keep last/1 Steering /vehicle/status/steering_status autoware_vehicle_msgs/SteeringReport - 30 Reliable,Volatile,Keep last/1 Control Mode /vehicle/status/control_mode autowar_vehicle_msgs/ControlModeReport - 30 Reliable,Volatile,Keep last/1 Gear /vehicle/status/gear_status autoware_vehicle_msgs/GearReport - 30 Reliable,Volatile,Keep last/1 Turn Indicators /vehicle/status/turn_indicators_status autoware_vehicle_msgs/TurnIndicatorsReport - 30 Reliable,Volatile,Keep last/1 Hazard Lights /vehicle/status/hazard_lights_status autoware_vehicle_msgs/HazardLightsReport - 30 Reliable,Volatile,Keep last/1

    Ground Truth

    Pose /awsim/ground_truth/vehicle/pose geometry_msgs/PoseStamped base_link 100 Reliable,Volatile,Keep last/1 V2I /perception/traffic_light_recognition/external/traffic_signals autoware_perception_msgs/msg/TrafficLightGroupArray - 10 Reliable,Volatile,Keep last/1"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/","title":"Preparing the connection between AWSIM and scenario_simulator_v2","text":""},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#preparing-the-connection-between-awsim-and-scenario_simulator_v2","title":"Preparing the connection between AWSIM and scenario_simulator_v2","text":"

    This tutorial describes: - how to modify scenario to work with AWSIM Labs - how to prepare the AWSIM Labs scene to work with scenario_simulator_v2

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#scenario-preparation-to-work-with-awsim-labs","title":"Scenario preparation to work with AWSIM Labs","text":"

    To run the created scenario with AWSIM Labs, necessary adjustments need to be made. After opening the generated .yaml file with a text editor of your choice, follow the steps below:

    1. CatalogLocation: [ ] should be removed and replaced with lines specifying the vehicle's properties. 
         VehicleCatalog:\n   Directory:\n   path: $(ros2 pkg prefix --share openscenario_experimental_catalog)/vehicle\n
    2. The file locations of the vector map and pointcloud map need to be changed. 
        RoadNetwork:\n    LogicFile:\n      filepath: /home/your-username/projects/autoware/src/simulator/shinjuku_map/map/lanelet2_map.osm\n    SceneGraphFile:\n      filepath: /home/your-username/projects/autoware/src/simulator/shinjuku_map/map/lanelet2_map.osm\n
    3. In order for the added NPC to be created by AWSIM Labs, the model3d: definition and the name of the desired prefab to be used should be entered.

        - name: Npc1\n        Vehicle:\n          name: ''\n          vehicleCategory: car\n          model3d: \"small_car\"\n
    4. The BoundingBox values should also be updated according to the preferred NPC model.\"Default AWSIM Labs asset catalog\" section provides features that can be utilized to use default models."},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#default-awsim-labs-asset-catalog","title":"Default AWSIM Labs asset catalog","text":"

    AWSIM Labs currently supports the following asset key values.

    The list can be extended if required. Appropriate values should be added to asst key list in the ScenarioSimulatorConnector component and the vehicle parameters in scenario simulator should match them.

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#ego-vehicle-entity-with-sensor","title":"Ego Vehicle Entity (with sensor)","text":"model3d boundingbox size (m) wheel base(m) front tread(m) rear tread(m) tier diameter(m) max steer(deg) lexus_rx450h width : 1.920 height : 1.700 length : 4.890 2.105 1.640 1.630 0.766 35"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#npc-vehicle-entity","title":"NPC Vehicle Entity","text":"model3d boundingbox size (m) wheel base(m) front tread(m) rear tread(m) tier diameter(m) max steer(deg) taxi width : 1.695 height : 1.515 length : 4.590 2.680 1.460 1.400 0.635 35 truck_2t width : 1.695 height : 1.960 length : 4.685 2.490 1.395 1.240 0.673 40 hatchback width : 1.695 height 1.515 length : 3.940 2.550 1.480 1.475 0.600 35 van width : 1.880 height : 2.285 length : 4.695 2.570 1.655 1.650 0.600 35 small_car width : 1.475 height 1.800 length : 3.395 2.520 1.305 1.305 0.557 35"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#npc-pedestrian-entity","title":"NPC Pedestrian Entity","text":"model3d boundingbox size (m) human width : 0.400 height : 1.800 length : 0.300"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#misc-object-entity","title":"Misc Object Entity","text":"model3d boundingbox size (m) sign_board width : 0.31 height : 0.58 length : 0.21"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#scenarios-limitations","title":"Scenarios limitations","text":"

    Vast majority of features supported by scenario_simulator_v2 are supported with AWSIM Labs as well. Currently supported features are described in the scenario_simulator_v2's documentation.

    Features which are not supported when connected with AWSIM Labs are listed below.

    1. Controller properties used by attach_*_sensor
      • pointcloudPublishingDelay
      • isClairvoyant
      • detectedObjectPublishingDelay
      • detectedObjectPositionStandardDeviation
      • detectedObjectMissingProbability
      • randomSeed

    If those features are curcial for the scenario's execution, the scenario might not work properly.

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#awsim-labs-scene-preparation-to-work-with-scenario_simulator_v2","title":"AWSIM Labs scene preparation to work with scenario_simulator_v2","text":"
    1. Disable or remove random traffic and any pre-spawned NPCs
    2. Disable or remove V2I traffic lights publishing
    3. Disable or remove the clock publisher
    1. Add ScenarioSimulatorConnector prefab to the scene - located in Assets/ScenarioSimulatorConnector
    1. Add Ego Follow Camera object - most likely Main Camera
    1. If necessary update the asset_id to prefab mapping - key in the map can be used in the scenario
    1. Add TimeSourceSelector prefab to the scene - located in Assets/AWSIM-Labs/Scripts/Clock/Prefabs
    1. Configure Type in the TimeSourceSelector component to SS2
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/","title":"Setup Unity project for scenario simulation","text":""},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#running-awsim-labs-from-unity-editor-with-scenario_simulator_v2","title":"Running AWSIM Labs from Unity Editor with scenario_simulator_v2","text":"

    Below you can find instructions on how to setup the scenario execution using scenario_simulator_v2 with AWSIM Labs run from Unity Editor as a simulator The instruction assumes using the Ubuntu OS.

    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#prerequisites","title":"Prerequisites","text":"

    1. Build Autoware by following \"Build Autoware with scenario_simulator_v2\" section from the scenario simulator and AWSIM Labs quick start guide

    2. Follow Setup Unity Project tutorial

    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#running-the-demo","title":"Running the demo","text":"
    1. Open AutowareSimulationScenarioSimulator.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Launch scenario_test_runner. 
      source install/setup.bash\nros2 launch scenario_test_runner scenario_test_runner.launch.py                        \\\narchitecture_type:=awf/universe/20240605  record:=false                                         \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim.yaml'          \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                          \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\" \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#other-sample-scenarios","title":"Other sample scenarios","text":""},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#conventional-traffic-lights-demo","title":"Conventional traffic lights demo","text":"

    This scenario controls traffic signals in the scene based on OpenSCENARIO. It can be used to verify whether traffic light recognition pipeline works well in Autoware.

    ros2 launch scenario_test_runner scenario_test_runner.launch.py                                           \\\narchitecture_type:=awf/universe/20240605  record:=false                                                            \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim_conventional_traffic_lights.yaml' \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                                             \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\"                    \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#v2i-traffic-lights-demo","title":"V2I traffic lights demo","text":"

    This scenario publishes V2I traffic signals information based on OpenSCENARIO. It can be used to verify Autoware responds to V2I traffic lights information correctly.

    ros2 launch scenario_test_runner scenario_test_runner.launch.py                                  \\\narchitecture_type:=awf/universe/20240605  record:=false                                                   \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim_v2i_traffic_lights.yaml' \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                                    \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\"           \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/Sensors/CameraSensor/","title":"Camera Sensor","text":""},{"location":"Components/Sensors/CameraSensor/#camerasensor","title":"CameraSensor","text":""},{"location":"Components/Sensors/CameraSensor/#introduction","title":"Introduction","text":"

    CameraSensor is a component that simulates an RGB camera. Autonomous vehicles can be equipped with many cameras used for various purposes. In the current version of AWSIM, the camera is used primarily to provide the image to the traffic light recognition module in Autoware.

    "},{"location":"Components/Sensors/CameraSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/CameraSensor.prefab\n
    "},{"location":"Components/Sensors/CameraSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The mentioned single CameraSensor has its own frame traffic_light_left_camera/camera_link in which its data is published. The sensor prefab is added to this frame. The traffic_light_left_camera/camera_link link is added to the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/CameraSensor/#camerasensorholder-script","title":"CameraSensorHolder (script)","text":"

    CameraSensorHolder (script) allows the sequential rendering of multiple camera sensors. To utilize it, each CameraSensor object should be attached as a child object of the CameraSensorHolder.

    "},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Camere Sensors - a collection of camera sensors used for rendering
    • Publish Hz - the frequency at which camera rendering, image processing and callbacks are executed
    • Render In Queue - camera sensors rendering sequence type: in queue (one after another) or all at the same frame
    "},{"location":"Components/Sensors/CameraSensor/#camerasensor-components","title":"CameraSensor Components","text":"

    For the CameraSensor to work properly, the GameObject to which the scripts are added must also have:

    • Camera component - the basic component that ensures the functionality of the camera as a device in Unity that capture and display the world to the player.
    • HD Additional Camera Data (script) - additional component that holds HDRP specific parameters for camera. This Component should be added automatically together with Camera component.

    TrafficLights recognition

    In case of problems with the recognition of traffic lights in Autoware, it may help to increase the image resolution and focal length of the camera in AWSIM.

    Camera settings

    If you would like to adjust the image captured by the camera, we encourage you to read this manual.

    The CameraSensor functionality is split into two scripts:

    • Camera Sensor (script) - acquires the image from the Unity camera, transforms it and saves to the BGR8 format, this format along with the camera parameters is its script output - script also calls the callback for it.
    • Camera Ros2 Publisher (script) - provides the ability to publish CameraSensor output as Image and CameraInfo messages type published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Sensors/CameraSensor/*\n

    In the same location there are also *.compute files containing used ComputeShaders.

    "},{"location":"Components/Sensors/CameraSensor/#camerasensor-script","title":"CameraSensor (script)","text":"

    Camera Sensor (script) is a core camera sensor component. It is responsible for applying OpenCV distortion and encoding to BGR8 format. The distortion model is assumed to be Plumb Bob. The script renders the image from the camera to Texture2D and transforms it using the distortion parameters. This image is displayed in the GUI and further processed to obtain the list of bytes in BGR8 format on the script output.

    The script uses two ComputeShaders, they are located in the same location as the scripts:

    • CameraDistortion - to correct the image using the camera distortion parameters,

    • RosImageShader - to encode two pixels color (bgr8 - 3 bytes) into one (uint32 - 4 bytes) in order to produce ROS Image BGR8 buffer.

    API type feature DoRender void Renders the Unity camera, applies OpenCV distortion to rendered image and update output data."},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 10Hz)
    • Image On GUI:
      • Show - if camera image should be show on GUI (default: true)
      • Scale - scale of reducing the image from the camera, 1 - will give an image of real size, 2 - twice smaller, etc. (default: 4)
      • X Axis - position of the upper left corner of the displayed image in the X axis, 0is the left edge (default: 0)
      • Y Axis - position of the upper left corner of the displayed image in the Y axis, 0 is the upper edge (default: 0)
    • Camera parameters
      • Width - image width (default: 1920)
      • Height - image height (default: 1080)
      • K1, K2, P1, P2, K3 - camera distortion coefficients for Plum Bob model(default: 0, 0, 0, 0, 0)
    • Camera Object - reference to the basic Camera component (default: None)
    • Distortion Shader - reference to ComputeShader asset about Distortion Shader functionality (default: None)
    • Ros Image Shader - reference to ComputeShader asset about Ros Image Shader functionality (default: None)
    "},{"location":"Components/Sensors/CameraSensor/#output-data","title":"Output Data","text":"

    The sensor computation output format is presented below:

    Category Type Description ImageDataBuffer byte[ ] Buffer with image data. CameraParameters CameraParameters Set of the camera parameters."},{"location":"Components/Sensors/CameraSensor/#cameraros2publisher-script","title":"CameraRos2Publisher (script)","text":"

    Converts the data output from CameraSensor to ROS2 Image and CameraInfo type messages and publishes them. The conversion and publication is performed using the Publish(CameraSensor.OutputData outputData) method, which is the callback triggered by Camera Sensor (script) for the current output.

    Due to the fact that the entire image is always published, the ROI field of the message is always filled with zeros. The script also ensures that binning is assumed to be zero and the rectification matrix is the identity matrix.

    Warning

    The script uses the camera parameters set in the CameraSensor script - remember to configure them depending on the camera you are using.

    "},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Image Topic - the ROS2 topic on which the Image message is published(default: \"/sensing/camera/traffic_light/image_raw\")
    • Camera Info Topic - the ROS2 topic on which the CameraInfo message is published(default: \"/sensing/camera/traffic_light/camera_info\")
    • Frame id - frame in which data is published, used in Header(default: \"traffic_light_left_camera/camera_link\")
    • Qos Settings - Quality of service profile used in the publication(default: Best effort, Volatile, Keep last, 1)
    "},{"location":"Components/Sensors/CameraSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 10Hz
    • QoS: Best effort, Volatile, Keep last/1
    Category Topic Message type frame_id Camera info /sensing/camera/traffic_light/camera_info sensor_msgs/CameraInfo traffic_light_left_camera/camera_link Camera image /sensing/camera/traffic_light/image_raw sensor_msgs/Image traffic_light_left_camera/camera_link"},{"location":"Components/Sensors/GNSSSensor/","title":"GNSS Sensor","text":""},{"location":"Components/Sensors/GNSSSensor/#gnsssensor","title":"GnssSensor","text":""},{"location":"Components/Sensors/GNSSSensor/#introduction","title":"Introduction","text":"

    GnssSensor is a component which simulates the position of vehicle computed by the Global Navigation Satellite System based on the transformation of the GameObject to which this component is attached. The GnssSensor outputs the position in the MGRS coordinate system.

    "},{"location":"Components/Sensors/GNSSSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/GnssSensor.prefab\n
    "},{"location":"Components/Sensors/GNSSSensor/#link","title":"Link","text":"

    GnssSensor has its own frame gnss_link in which its data is published. The sensor prefab is added to this frame. The gnss_link frame is added to the sensor_kit_base_link in the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/GNSSSensor/#components","title":"Components","text":"

    The GnssSensor functionality is split into two components:

    • Gnss Sensor (script) - it calculates the position as its output and calls the callback for it.
    • Gnss Ros2 Publisher (script) - provides the ability to publish GnssSensor output as PoseStamped and PoseWithCovarianceStamped published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/Gnss/*\n
    "},{"location":"Components/Sensors/GNSSSensor/#gnss-sensor-script","title":"Gnss Sensor (script)","text":"

    This is the main script in which all calculations are performed:

    1. the position of the Object in Unity is read,
    2. this position is transformed to the ROS2 coordinate system (MGRS offset is added here),
    3. the result of the transformation is saved as the output of the component,
    4. for the current output a callback is called (which can be assigned externally).
    "},{"location":"Components/Sensors/GNSSSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 100Hz)
    "},{"location":"Components/Sensors/GNSSSensor/#output-data","title":"Output Data","text":"Category Type Description Position Vector3 Position in the MGRS coordinate system."},{"location":"Components/Sensors/GNSSSensor/#gnss-ros2-publisher-script","title":"Gnss Ros2 Publisher (script)","text":"

    Converts the data output from GnssSensor to ROS2 PoseStamped and PoseWithCovarianceStamped messages. These messages are published on two separate topics for each type. The conversion and publication is performed using the Publish(GnssSensor.OutputData outputData) method, which is the callback triggered by Gnss Sensor (script) for the current output update.

    Covariance matrix

    The row-major representation of the 6x6 covariance matrix is filled with 0 and does not change during the script run.

    "},{"location":"Components/Sensors/GNSSSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Pose Topic - the ROS2 topic on which the message PoseStamped type is published(default: \"/sensing/gnss/pose\")
    • Pose With Covariance Stamped Topic - the ROS2 topic on which the message PoseWithCovarianceStamped type is published(default: \"/sensing/gnss/pose_with_covariance\")
    • Frame id - frame in which data are published, used in Header(default: \"gnss_link\")
    • Qos Settings - Quality of service profile used in the publication(default is assumed as \"system_default\": Reliable, Volatile, Keep last, 1)
    "},{"location":"Components/Sensors/GNSSSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 1Hz
    • QoS: Reliable, Volatile, Keep last/1
    Category Topic Message type frame_id Pose /sensing/gnss/pose geometry_msgs/Pose gnss_link Pose with Covariance /sensing/gnss/pose_with_covariance geometry_msgs/PoseWithCovarianceStamped gnss_link"},{"location":"Components/Sensors/IMUSensor/","title":"IMU Sensor","text":""},{"location":"Components/Sensors/IMUSensor/#imusensor","title":"IMUSensor","text":""},{"location":"Components/Sensors/IMUSensor/#introduction","title":"Introduction","text":"

    IMUSensor is a component that simulates an IMU (Inertial Measurement Unit) sensor. Measures acceleration (\\({m}/{s^2}\\)) and angular velocity (\\({rad}/{s}\\)) based on the transformation of the GameObject to which this component is attached.

    "},{"location":"Components/Sensors/IMUSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/IMUSensor.prefab\n
    "},{"location":"Components/Sensors/IMUSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    IMUSensor has its own frame tamagawa/imu_link in which its data is published. The sensor prefab is added to this frame. The tamagawa/imu_link link is added to the sensor_kit_base_link in the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/IMUSensor/#components","title":"Components","text":"

    The IMUSensor functionality is split into two scripts:

    • IMU Sensor (script) - it calculates the acceleration and angular velocity as its output and calls the callback for it.
    • Imu Ros2 Publisher (script) - provides the ability to publish IMUSensor output as Imu message type published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Sensors/Imu/*\n
    "},{"location":"Components/Sensors/IMUSensor/#imu-sensor-script","title":"IMU Sensor (script)","text":"

    This is the main script in which all calculations are performed:

    • the angular velocity is calculated as the derivative of the orientation with respect to time,
    • acceleration is calculated as the second derivative of position with respect to time,
    • in the calculation of acceleration, the gravitational vector is considered - which is added.

    Warning

    If the angular velocity about any axis is NaN (infinite), then angular velocity is published as vector zero.

    "},{"location":"Components/Sensors/IMUSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 30Hz)
    "},{"location":"Components/Sensors/IMUSensor/#output-data","title":"Output Data","text":"Category Type Description LinearAcceleration Vector3 Measured acceleration (m/s^2) AngularVelocity Vector3 Measured angular velocity (rad/s)"},{"location":"Components/Sensors/IMUSensor/#imu-ros2-publisher-script","title":"Imu Ros2 Publisher (script)","text":"

    Converts the data output from IMUSensor to ROS2 Imu type message and publishes it. The conversion and publication is performed using the Publish(IMUSensor.OutputData outputData) method, which is the callback triggered by IMU Sensor (script) for the current output.

    Warning

    In each 3x3 covariance matrices the row-major representation is filled with 0 and does not change during the script run. In addition, the field orientation is assumed to be {1,0,0,0} and also does not change.

    "},{"location":"Components/Sensors/IMUSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Topic - the ROS2 topic on which the message is published(default: \"/sensing/imu/tamagawa/imu_raw\")
    • Frame id - frame in which data is published, used in Header(default: tamagawa/imu_link\")
    • Qos Settings - Quality of service profile used in the publication(default: Reliable, Volatile, Keep last, 1000)
    "},{"location":"Components/Sensors/IMUSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 30Hz
    • QoS: Reliable, Volatile, Keep last/1000
    Category Topic Message type frame_id IMU data /sensing/imu/tamagawa/imu_raw sensor_msgs/Imu tamagawa/imu_link"},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/","title":"Add New LiDAR","text":""},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#add-a-new-lidar","title":"Add a new LiDAR","text":"

    RGLUnityPlugin (RGL) comes with a number of the most popular LiDARs model definitions and ready-to-use prefabs. However, there is a way to create your custom LiDAR. This section describes how to add a new LiDAR model that works with RGL, then create a prefab for it and add it to the scene.

    Supported LiDARs

    Not all lidar types are supported by RGL. Unfortunately, in the case of MEMs LiDARs, there is a non-repetitive phenomenon - for this reason, the current implementation is not able to reproduce their work.

    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#1-add-a-new-lidar-model","title":"1. Add a new LiDAR model","text":"

    The example shows the addition of a LiDAR named NewLidarModel.

    To add a new LiDAR model, perform the following steps:

    1. Navigate to Assets/RGLUnityPlugin/Scripts/LidarModels.

    2. Add its name to the LidarModels.cs at the end of the enumeration. The order of enums must not be changed to keep existing prefabs working.

    3. Now, it is time to define the laser (also called a channel) distribution of the LiDAR.

      Info

      If your LiDAR:

      - has a uniform laser distribution\n- has the equal range for all of the lasers\n- fire all of the rays (beams) at the same time\n

      You can skip this step and use our helper method to generate a simple uniform laser array definition (more information in the next step).

      1. Laser distribution is represented by LaserArray consists of:

        • centerOfMeasurementLinearOffsetMm - 3D translation from the game object's origin to LiDAR's origin. Preview in 2D:

        • focalDistanceMm - Distance from the sensor center to the focal point where all laser beams intersect.

        • lasers - array of lasers (channels) with a number of parameters:

          • horizontalAngularOffsetDeg - horizontal angle offset of the laser (Azimuth)
          • verticalAngularOffsetDeg - vertical angle offset of the laser (Elevation)
          • verticalLinearOffsetMm - vertical offset of the laser (translation from origin)
          • ringId - Id of the ring (in most cases laser Id)
          • timeOffset - time offset of the laser firing in milliseconds (with reference to the first laser in the array)
          • minRange - minimum range of the laser (set if lasers have different ranges)
          • maxRange - maximum range of the laser (set if lasers have different ranges)

      2. To define a new laser distribution create a new class in the LaserArrayLibrary.cs

        • Add a new public static instance of LaserArray with the definition.

        In this example, NewLidarModel laser distribution consists of 5 lasers with

        - elevations: 15, 10, 0, -10, -15 degrees\n- azimuths: 1.4, -1.4, 1.4, -1.4, 1.4 degrees\n- ring Ids: 1, 2, 3, 4, 5\n- time offsets: 0, 0.01, 0.02, 0.03, 0.04 milliseconds\n- an equal range that will be defined later\n

        Coordinate system

        Keep in mind that Unity has a left-handed coordinate system, while most of the LiDAR's manuals use a right-handed coordinate system. In that case, reverse sign of the values of the angles.

    4. The last step is to create a LiDAR configuration by adding an entry to LidarConfigurationLibrary.cs

      Add a new item to the ByModel dictionary that collects LiDAR model enumerations with their BaseLidarConfiguration choosing one of the implementations:

      • UniformRangeLidarConfiguration - lidar configuration for uniformly distributed rays along the horizontal axis with a uniform range for all the rays (it contains minRange and maxRange parameters additionally)
      • LaserBasedRangeLidarConfiguration - lidar configuration for uniformly distributed rays along the horizontal axis with ranges retrieved from lasers description
      • Or create your custom implementations in LidarConfiguration.cs like:
        • HesaiAT128LidarConfiguration
        • HesaiQT128C2XLidarConfiguration
        • HesaiPandar128E4XLidarConfiguration

      Lidar configuration parameters descrition

      Please refer to this section for the detailed description of all configuration parameters.

    5. Done. New LiDAR preset should be available via Unity Inspector.

      Frame rate of the LiDAR can be set in the Automatic Capture Hz parameter.

      Note: In the real-world LiDARs, frame rate affects horizontal resolution. Current implementation separates these two parameters. Keep in mind to change it manually.

    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#2-create-new-lidar-prefab","title":"2. Create new LiDAR prefab","text":"
    1. Create an empty object and name it appropriately according to the LiDAR model.
    2. Attach script LidarSensor.cs to created object.
    3. Set the new added LiDAR model in Model Preset field, check if the configuration loads correctly. You can now customize it however you like.
    4. (Optional) Attach script PointCloudVisualization.cs for visualization purposes.
    5. For publishing point cloud via ROS2 attach script RglLidarPublisher.cs script to created object.
    6. Set the topics on which you want the data to be published and their frame.
    7. Save the prefab in the project.
    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#3-test-your-prefab","title":"3. Test your prefab","text":"
    1. Create a new scene (remember to add the SceneManager) or use one of the existing sample scenes.

    2. Add the prepared LiDAR prefab by drag the prefab file and drop it into a scene.

    3. A LiDAR GameObject should be instantiated automatically

    4. Now you can run the scene and check how your LiDAR works.

    Success

    We encourage you to develop a vehicle using the new LiDAR you have added - learn how to do this here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/","title":"LiDAR Sensor","text":""},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#lidarsensor","title":"LidarSensor","text":""},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#introduction","title":"Introduction","text":"

    LidarSensor is the component that simulates the LiDAR (Light Detection and Ranging) sensor. LiDAR works by emitting laser beams that bounce off objects in the environment, and then measuring the time it takes for the reflected beams to return, allowing the sensor to create a 3D map of the surroundings. This data is used for object detection, localization, and mapping.

    LiDAR in an autonomous vehicle can be used for many purposes. The ones mounted on the top of autonomous vehicles are primarily used

    • to scan the environment for localization in space
    • to detect and identify obstacles such as approaching vehicles, pedestrians or other objects in the driving path.

    LiDARs placed on the left and right sides of the vehicle are mainly used to monitor the traffic lane and detect vehicles moving in adjacent lanes, enabling safe maneuvers such as lane changing or turning.

    LidarSensor component is a part of RGLUnityPlugin that integrates the external RobotecGPULidar (RGL) library with Unity. RGL also allows to provide additional information about objects, more about it here.

    Use RGL in your scene

    If you want to use RGL in your scene, make sure the scene has an SceneManager component added and all objects meet the usage requirements.

    RGL default scenes

    If you would like to see how LidarSensor works using RGL or run some tests, we encourage you to familiarize yourself with the RGL test scenes section.

    Supported LiDARs

    The current scripts implementation allows you to configure the prefab for any mechanical LiDAR. You can read about how to do it here. MEMS-based LiDARs due to their different design are not yet fully supported.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#prefabs","title":"Prefabs","text":"

    Prefabs can be found under the following path:

    Assets/AWSIM/Prefabs/RobotecGPULidars/*\n

    The table of available prefabs can be found below:

    LiDAR Path Appearance HESAI Pandar40P HesaiPandar40P.prefab HESAI PandarQT64 HesaiPandarQT64.prefab HESAI PandarXT32 HesaiPandarXT32.prefab HESAI QT128C2X HesaiQT128C2X.prefab HESAI Pandar128E4X HesaiPandar128E4X.prefab HESAI AT128 E2X HesaiAT128E2X.prefab Ouster OS1-64 OusterOS1-64.prefab Velodyne VLP-16 VelodyneVLP16.prefab Velodyne VLC-32C VelodyneVLP32C.prefab Velodyne VLS-128-AP VelodyneVLS128.prefab"},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    LidarSensor is configured in default vehicle EgoVehicle prefab. It is added to URDF object as a child of sensor_kit_base_link. LidarSensor placed in this way does not have its own frame, and the data is published relative to sensor_kit_base_link. More details about the location of the sensors in the vehicle can be found here.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    Additional LiDARs

    For a LiDAR placed on the left side, right side or rear, an additional link should be defined.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#components-and-resources","title":"Components and Resources","text":"

    The LiDAR sensor simulation functionality is split into three components:

    • Lidar Sensor (script) - provides lidar configuration, creates RGL pipeline to simulate lidar, and performs native RGL raytrace calls,
    • Rgl Lidar Publisher (script) - extends RGL pipeline with nodes to publish ROS2 messages.
    • Point Cloud Visualization (script) - visualizes point cloud collected by sensor.

    Moreover, the scripts use Resources to provide configuration for prefabs of supported lidar models:

    • LaserModels - provides a list of supported models,
    • LaserArrayLibrary - provides data related to laser array construction for supported models,
    • LaserConfigurationLibrary - provides full configuration, with ranges and noise for supported models.

    These are elements of the RGLUnityPlugin, you can read more here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#lidar-sensor-script","title":"Lidar Sensor (script)","text":"

    This is the main component that creates the RGL node pipeline for the LiDAR simulation. The pipeline consists of:

    • setting ray pattern,
    • transforming rays to represent pose of the sensor on the scene,
    • applying Gaussian noise,
    • performing raytracing,
    • removing non-hits from the result point cloud,
    • transforming point cloud to sensor frame coordinate system.
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Automatic Capture Hz - the rate of sensor processing (default: 10Hz)
    • Model Preset - allows selecting one of the built-in LiDAR models (default: RangeMeter)
    • Apply Distance Gaussian Noise - enable/disable distance Gaussian noise (default: true)
    • Apply Angular Gaussian Noise - enable/disable angular Gaussian noise (default: true)
    • Apply Velocity Distortion - enable/disable velocity distortion (default: false)
    • Configuration:
      • Laser Array - geometry description of lidar's array of lasers, should be prepared on the basis of the manual for a given model of LiDAR (default: loaded from LaserArrayLibrary)
      • Horizontal Resolution - the horiontal resolution of laser array firings
      • Min H Angle - minimum horizontal angle, left (default: 0)
      • Max H Angle - maximum horizontal angle, right (default: 0)
      • Laser Array Cycle Time - time between two consecutive firings of the whole laser array in milliseconds (default: 0); used for velocity distortion feature.
      • Beam Divergence - represents the deviation of photons from a single beam emitted by a LiDAR sensor (in degrees); used for simulating snow only (private feature).
      • Noise Params:
        • Angular Noise Type - angular noise type(default: Ray Based)
        • Angular Noise St Dev - angular noise standard deviation in degree(default: 0.05729578)
        • Angular Noise Mean - angular noise mean in degrees(default: 0)
        • Distance Noise St Dev Base - distance noise standard deviation base in meters(default: 0.02)
        • Distance Noise Rise Per Meter - distance noise standard deviation rise per meter(default: 0)
        • Distance Noise Mean - distance noise mean in meters(default: 0)
      • Additional options (available for some Lidar Model Preset)
        • Min Range - minimum range of the sensor (if not avaiable, the range is different for each laser in Laser Array)
        • Max Range - maximum range of the sensor (if not avaiable, the range is different for each laser in Laser Array)
        • High Resolution Mode Enabled - whether to activate high resolution mode (available for Hesai Pandar 128E4X LiDAR model)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data","title":"Output Data","text":"

    LidarSensor provides public methods to extend this pipeline with additional RGL nodes. In this way, other components can request point cloud processing operations and receive data in the desired format.

    Example of how to get XYZ point cloud data:

    1. To obtain point cloud data from another component you have to create a new RGLNodeSequence with RGL node to yield XYZ field and connect it to LidarSensor: 
      rglOutSubgraph = new RGLNodeSequence().AddNodePointsYield(\"OUT_XYZ\", RGLField.XYZ_F32);\nlidarSensor = GetComponent<LidarSensor>();\nlidarSensor.ConnectToWorldFrame(rglOutSubgraph); // you can also connect to Lidar frame using ConnectToLidarFrame\n// You can add a callback to receive a notification when new data is ready\nlidarSensor.onNewData += HandleLidarDataMethod;\n
    2. To get data from RGLNodeSequence call GetResultData: 
      Vector3[] xyz = new Vector3[0];\nrglOutSubgraph.GetResultData<Vector3>(ref xyz);\n
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#rgl-lidar-publisher-script","title":"Rgl Lidar Publisher (script)","text":"

    RglLidarPublisher extends the main RGL pipeline created in LidarSensor with RGL nodes that produce point clouds in specific format and publish them to the ROS2 topic. Thanks to the ROS2 integration with RGL, point clouds can be published directly from the native library. RGL creates ROS2 node named /RobotecGPULidar with publishers generated by RGL nodes.

    Currently, RglLidarPublisher implements two ROS2 publishers:

    • rosPCL24 - a 24-byte point cloud format used by Autoware
    • rosPCL48 - a 48-byte extended version point cloud format used by Autoware

    Details on the construction of these formats are available in the PointCloudFormats under the following path:

    Assets/AWSIM/Scripts/Sensors/LiDAR/PointCloudFormats.cs\n

    rosPCL48 format

    For a better understanding of the rosPCL48 format, we encourage you to familiarize yourself with the point cloud pre-processing process in Autoware, which is described here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Pcl 24 Topic - the ROS2 topic on which the PointCloud2 message is published(default: \"lidar/pointcloud\")
    • Pcl 48 Topic - the ROS2 topic on which the PointCloud2 message is published(default: \"lidar/pointcloud_ex\")
    • Frame ID - frame in which data are published, used in Header (default: \"world\")
    • Publish PCL24 - if publish cloud PCL24 (default: true)
    • Publish PCL48 - if publish cloud PCL48 (default: true)
    • Qos Settings - Quality of service profile used in the publication(default: Best effort, Volatile, Keep last, 5)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 10Hz
    • QoS: Best effort, Volatile, Keep last/5
    Category Topic Message type frame_id PointCloud 24-byte format /lidar/pointcloud sensor_msgs/PointCloud2 world PointCloud 48-byte format /lidar/pointcloud_ex sensor_msgs/PointCloud2 world"},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#point-cloud-visualization-script","title":"Point Cloud Visualization (script)","text":"

    A component visualizing a point cloud obtained from RGL in the form of a Vector3 list as colored points in the Unity scene. Based on the defined color table, it colors the points depending on the height at which they are located.

    The obtained points are displayed as the vertices of mesh, and their coloring is possible thanks to the use of PointCloudMaterial material which can be found in the following path:

    Assets/RGLUnityPlugin/Resources/PointCloudMaterial.mat\n

    Point Cloud Visualization preview:

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Point Shape - the shape of the displayed points (default: Box)
    • Point Size - the size of the displayed points (default: 0.05)
    • Colors - color list used depending on height(default: 6 colors: red, orange, yellow, green, blue, violet)
    • Auto Compute Coloring Heights - automatic calculation of heights limits for a list of colors (default: false)
    • Min Coloring Height - minimum height value from which color matching is performed, below this value all points have the first color from the list (default: 0)
    • Max Coloring Height - maximum height value from which color matching is performed, above this value all points have the last color from the list (default: 20)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#read-material-information","title":"Read material information","text":"

    To ensure the publication of the information described in this section, GameObjects must be adjusted accordingly. This tutorial describes how to do it.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#intensity-texture","title":"Intensity Texture","text":"

    RGL Unity Plugin allows assigning an Intensity Texture to the GameObjects to produce a point cloud containing information about the lidar ray intensity of hit. It can be used to distinguish different levels of an object's reflectivity.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data_1","title":"Output data","text":"

    Point cloud containing intensity is published on the ROS2 topic via RglLidarPublisher component. The intensity value is stored in the intensity field of the sensor_msgs/PointCloud2 message.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#instance-segmentation","title":"Instance segmentation","text":"

    RGL Unity Plugin allows assigning an ID to GameObjects to produce a point cloud containing information about hit objects. It can be used for instance/semantic segmentation tasks. This tutorial describes how to do it.

    LidarInstanceSegmentationDemo

    If you would like to see how LidarInstanceSegmentationDemo works using RGL or run some tests, we encourage you to familiarize yourself with this section.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data_2","title":"Output data","text":"

    Point cloud containing hit objects IDs is published on the ROS2 topic via RglLidarPublisher component. It is disabled by default. Properties related to this feature are marked below:

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#dictionary-mapping","title":"Dictionary mapping","text":"

    The resulting simulation data contains only the id of objects without their human-readable names. To facilitate the interpretation of such data, a function has been implemented to save a file with a dictionary mapping instance ID to GameObject names. It writes pairs of values in the yaml format:

    • The name of the GameObject
    • Category ID of SemanticCategory component

    To enable saving dictionary mapping set output file path to the Semantic Category Dictionary File property in the Scene Manager component:

    The dictionary mapping file will be saved at the end of the simulation.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/","title":"RGLUnityPlugin","text":""},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#rglunityplugin","title":"RGLUnityPlugin","text":"

    Robotec GPU Lidar (RGL) is an open source high performance lidar simulator running on CUDA-enabled GPUs. It is a cross-platform solution compatible with both Windows and Linux operating systems. RGL utilizes RTX cores for acceleration, whenever they are accessible.

    RGL is used in AWSIM for performance reasons. Thanks to it, it is possible to perform a large number of calculations using the GPU, which is extremely helpful due to the size of the scenes. AWSIM is integrated with RGL out-of-the-box - using RGLUnityPlugin asset.

    Warning

    If you want to use RGL in your scene, make sure the scene has an RGLSceneManager component added and all objects meet the usage requirements.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#concept","title":"Concept","text":"

    Describing the concept of using RGL in AWSIM, we distinguish:

    • Mesh - a handle to the on-GPU data of the 3D model of objects that in AWSIM are provided in the form of Mesh Filter component. RGLUnityPlugin supports two types of meshes: static (rendered by Mesh Renderer) and animated (rendered by Skinned Mesh Renderer). Static meshes could be shared between Entities.
    • Entity - represents a 3D object on the scene with its position and rotation. It consists of a lightweight reference to a Mesh and a transformation matrix of the object.
    • Scene - a location where raytracing occurs. It is a set of entites uploaded by SceneManager script to the RGL Native Library.
    • Node - performs specific operations such as setting rays for raytracing, transforming rays, performing raytracing, and manipulating output formats. In AWSIM, the main sequence of RGL nodes that simulates LiDAR is created in the LidarSensor script. Other scripts usually create nodes to get requested output or preprocess point cloud, and then connect those nodes to the LidarSensor.
    • Graph - a collection of connected Nodes that can be run to calculate results. It allows users to customize functionality and output format by adding or removing Nodes.

    Producing a point cloud is based on the use of a Scene containing Entities with Meshes, and placing an Ego Entity with LiDAR sensor that creates a Graph describing ray pattern and performing raytracing. In subsequent frames of the simulation, SceneManager synchronizes the scene between Unity and RGL, and LiDAR sensor updates rays pose on the scene and triggers Graph to perform raytracing and format desired output.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#package-structure","title":"Package structure","text":"

    RGLUnityPlugin asset contains:

    • Plugins - dynamically loaded libraries for Windows and Linux (*.dll and *.so files).
    • Resources - visualization shader and material.
    • Scripts - scripts for using RGL in the Unity - details below.
    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#scripts","title":"Scripts","text":"
    • SceneManager - responsible for syncing the scene between Unity and RGL.
    • LidarSensor - provide lidar configuration and create RGL pipeline to simulate lidar.
    • PointCloudVisualization - visualize point cloud on the Unity scene.
    • IntensityTexture - adds slot for Intensity Texture ID to the GameObject
    • SemanticCategory - adds category ID to the GameObject
    • RGLDebugger - provides configuration for Native RGL debug tools (logging and tape).
    • A set of classes providing tools to define LiDAR specification (mostly: ray poses):
      • LidarModels - enumeration of some real-world LiDARs names.
      • LidarConfiguration - top-level configuration class, horizontal ranges, distance range, laser array.
      • LidarConfigurationLibrary - provides a number of pre-defined LidarConfigurations.
      • LaserArray - definition of a (vertical) array of lasers.
      • LaserArrayLibrary - provides a number of pre-defined LaserArrays.
      • Laser - describes offsets of a single laser within a LaserArray.
      • LidarNoiseParams - describes a LiDAR noise that can be simulated
    • LowLevelWrappers scripts - provides some convenience code to call Native RGL functions.
    • Utilities scripts - miscellaneous utilities to make rest of the code clearer.
    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#scenemanager","title":"SceneManager","text":"

    Each scene needs SceneManager component to synchronize models between Unity and RGL. On every frame, it detects changes in the Unity's scene and propagates the changes to native RGL code. When necessary, it obtains 3D models from GameObjects on the scene, and when they are no longer needed, it removes them.

    Three different strategies to interact with in-simulation 3D models are implemented. SceneManager uses one of the following policies to construct the scene in RGL:

    • Only Colliders - data is computed based on the colliders only, which are geometrical primitives or simplified Meshes. This is the fastest option, but will produce less accurate results, especially for the animated entities.
    • Regular Meshes And Colliders Instead Of Skinned - data is computed based on the regular meshes for static Entities (with MeshRenderers component) and the colliders for animated Entities (with SkinnedMeshRenderer component). This improves accuracy for static Entities with a negligible additional performance cost.
    • Regular Meshes And Skinned Meshes - uses regular meshes for both static and animated Entities. This incurs additional performance, but produces the most realistic results.
    Mesh Source Strategy Static Entity Animated Entity (NPC) Only Colliders Collider Collider Regular Meshes And Colliders Instead Of Skinned Regular Mesh Collider Regular Meshes And Skinned Meshes Regular Mesh Regular Mesh

    Mesh source can be changed in the SceneManager script properties:

    Performance

    SceneManager performance depends on mesh source option selected.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#usage-requirements","title":"Usage requirements","text":"

    Objects, to be detectable by RGL, must fulfill the following requirements:

    1. Contain one of the components: Collider, Mesh Renderer, or Skinned Mesh Renderer - it depends on SceneManager mesh source parameter.

    2. Be readable from CPU-accessible memory - it can be achieved using the Read/Write Enabled checkbox in mesh settings.

      Readable objects

      Primitive Objects are readable by default.

      Example

      The activated Readable option in the mesh should look like this.

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/","title":"Read Material Information","text":"

    RGL Unity Plugin allows to:

    • assigning an Intensity Texture to the GameObjects to produce a point cloud containing information about the lidar ray intensity of hit. It can be used to distinguish different levels of an object's reflectivity.
    • assigning an ID to GameObjects to produce a point cloud containing information about hit objects. It can be used for instance/semantic segmentation tasks. Below describes how to ensure the publication of this information.
    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#add-intensity-texture-assignment","title":"Add Intensity Texture assignment","text":"

    To enable reading material information, add IntensityTexture component to every GameObject that is expected to have non-default intensity values.

    After that desired texture has to be inserted into the Intensity Texture slot.

    The texture has to be in R8 format. That means 8bit in the red channel (255 possible values).

    When the texture is assigned, the intensity values will be read from the texture and added to the point cloud if and only if the mesh component in the GameObject has a set of properly created texture coordinates.

    The expected number of texture coordinates is equal to the number of vertices in the mesh. The quantity of indices is not relevant. In other cases, the texture will be no read properly.

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#add-id-assignment","title":"Add ID assignment","text":"

    To enable segmentation, add SemanticCategory component to every GameObject that is expected to have a distinct ID. All meshes that belong to a given object will inherit its ID. ID inheritance mechanism allows IDs to be overwritten for individual meshes/objects. This solution also enables the creation of coarse categories (e.g., Pedestrians, Vehicles)

    Example

    SemanticCategory component is assigned to the Taxi GameObject. All meshes in the Taxi GameObject will have the same instance ID as Taxi:*

    Example

    The driver has its own SemanticCategory component, so his instance ID will differ from the rest of the meshes:

    Example

    SemanticCategory component is assigned to the Vehicles GameObject that contains all of the cars on the scene:

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#dictionary-mapping","title":"Dictionary mapping","text":"

    The resulting simulation data contains only the id of objects without their human-readable names. To facilitate the interpretation of such data, a function has been implemented to save a file with a dictionary mapping instance ID to GameObject names. It writes pairs of values in the yaml format:

    • The name of the GameObject
    • Category ID of SemanticCategory component

    To enable saving dictionary mapping set output file path to the Semantic Category Dictionary File property in the Scene Manager component:

    The dictionary mapping file will be saved at the end of the simulation.

    "},{"location":"Components/Sensors/VehicleStatusSensor/","title":"Vehicle Status Sensor","text":""},{"location":"Components/Sensors/VehicleStatusSensor/#vehiclestatussensor","title":"VehicleStatusSensor","text":""},{"location":"Components/Sensors/VehicleStatusSensor/#introduction","title":"Introduction","text":"

    VehicleStatusSensor is a component that is designed to aggregate information about the current state of the vehicle. It aggregates information about:

    • Control mode - currently active control mode, e.g. AUTONOMOUS or MANUAL.
    • Gear status - currently engaged gearbox gear, e.g. DRIVE or REVERSE.
    • Steering status - current angle of the steering tire in radians left, e.g. 0.1745 (10\u00b0).
    • Turn indicators status - current status of the direction indicators, e.g. DISABLE or ENABLE_LEFT.
    • Hazard lights status - current status of the hazard lights, e.g. DISABLE or ENABLE.
    • Velocity status - current lateral, longitudinal and heading velocities values, e.g {0.2, 0.0, 0.0}.
    "},{"location":"Components/Sensors/VehicleStatusSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/VehicleStatusSensor.prefab\n
    "},{"location":"Components/Sensors/VehicleStatusSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    This sensor is added directly to the URDF link in the EgoVehicle prefab.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#components","title":"Components","text":"

    All features are implemented within the Vehicle Report Ros2 Publisher (script) which can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/*\n
    "},{"location":"Components/Sensors/VehicleStatusSensor/#vehicle-report-ros2-publisher-script","title":"Vehicle Report Ros2 Publisher (script)","text":"

    The script is responsible for updating and publishing each of the aggregated data on a separate topic. Therefore, it has 6 publishers publishing the appropriate type of message with a constant frequency - one common for all data.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • * Report Topic - topic on which suitable type of information is published(default: listed in the table below)
    • Publish Hz - frequency of publications on each topic(default: 30Hz)
    • Frame ID - frame in which data is published, used in Header(default: base_link)
    • QoS- Quality of service profile used in the publication(default assumed as \"system_default\": Reliable, Volatile, Keep last/1)
    • Vehicle - the object from which all published data are read(default: None)

    Vehicle configuration

    An important element of the script configuration that must be set is the scene Object (Vehicle). It will be used for reading all the data needed. The appropriate EgoVehicle object should be selected.

    If you can't select the right object, make sure it's set up correctly - it has got added all the scripts needed for EgoVehicle.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#published-topics","title":"Published topics","text":"
    • Frequency: 30Hz
    • QoS: Reliable, Volatile, Keep last/1
    Category Topic Message type frame_id Control mode /vehicle/status/control_mode autoware_vehicle_msgs/ControlModeReport - Gear status /vehicle/status/gear_status autoware_vehicle_msgs/GearReport - Steering status /vehicle/status/steering_status autoware_vehicle_msgs/SteeringReport - Turn indicators status /vehicle/status/turn_indicators_status autoware_vehicle_msgs/TurnIndicatorsReport - Hazard lights status /vehicle/status/hazard_lights_status autoware_vehicle_msgs/HazardLightsReport - Velocity status /vehicle/status/velocity_status autoware_vehicle_msgs/VelocityReport base_line"},{"location":"Components/Traffic/NPCs/Pedestrian/","title":"Pedestrian","text":""},{"location":"Components/Traffic/NPCs/Pedestrian/#introduction","title":"Introduction","text":"

    NPCPedestrian is an object that simulates a human standing or moving on the scene. It can move cyclically in any chosen place thanks to the available scripts. Traffic light tracking will be implemented in the future.

    Sample scene

    If you would like to see how NPCPedestrian works or run some tests, we encourage you to familiarize yourself with the NPCPedestrianSample default scene described in this section.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#prefab-and-fbx","title":"Prefab and Fbx","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Pedestrians/humanElegant.prefab\n
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#visual-elements","title":"Visual elements","text":"

    Prefab is developed using models available in the form of *.fbx file. From this file, the visual elements of the model, Animator and LOD were loaded. The Animator and LOD are added as components of the main-parent GameObject in prefab, while the visual elements of the model are added as its children.

    *.fbx file can be found under the following path:

    Assets/AWSIM/Models/NPCs/Pedestrians/Human/humanElegant.fbx\n

    NPCPedestrian prefab has the following content:

    The ReferencePoint is used by the NPC Pedestrian (script) described here.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    Pedestrians implemented in the scene are usually added in one aggregating object - in this case it is NPCPedestrians. This object is added to the Environment prefab.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#components","title":"Components","text":"

    There are several components responsible for the full functionality of NPCPedestrian:

    • Animator - provides motion animations in the scene, which are composed of clips controlled by the controller.
    • LOD Group - provides level of detail configuration for shaders - affects GPU usage.
    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • NPC Pedestrian (script) - ensures that the movement of the object is combined with animation.
    • Simple Pedestrian Walker Controller (script) - provides pedestrian movement in a specific direction and distance in a cyclical manner.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/NPCs/Pedestrians/*\n
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. In order to connect the animation to the object, the Is Kinematic option must be enabled. By setting Is Kinematic, each NPCPedestrian object will have no physical interaction with other objects - it will not react to a vehicle that hits it. The Use Gravity should be turned off - the correct position of the pedestrian in relation to the ground is ensured by the NPC Pedestrian (script). In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#lod-level-of-detail","title":"LOD (Level of Detail)","text":"

    LOD provides dependence of the level of detail of the object depending on the ratio of the GameObject\u2019s screen space height to the total screen height. The pedestrian model has two object groups: suffixed LOD0 and LOD1. LOD0 objects are much more detailed than LOD1 - they have many more vertices in the Meshes. Displaying complex meshes requires more performance, so if the GameObject is a small part of the screen, less complex LOD1 objects are used.

    In the case of the NPCPedestrian prefab, if its object is less than 25% of the height of the screen then objects with the LOD1 suffix are used. For values less than 1% the object is culled.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#animator","title":"Animator","text":"

    Animator component provides animation assignments to a GameObject in the scene. It uses a developed Controller which defines which animation clips to use and controls when and how to blend and transition between them.

    The AnimationController for humans should have the two float parameters for proper transitions. Transitions between animation clips are made depending on the values of these parameters:

    • moveSpeed - pedestrian movement speed in \\({m}/{s}\\),
    • rotateSpeed - pedestrian rotation speed in \\({rad}/{s}\\).

    Developed controller can be found in the following path: Assets/AWSIM/Models/NPCs/Pedestrians/Human/Human.controller

    Walking to running transition

    The example shows the state of walking and then transitions to running as a result of exceeding the condition \\(\\mathrm{moveSpeed} > 1.6\\)

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#npc-pedestrian-script","title":"NPC Pedestrian (script)","text":"

    The script takes the Rigidbody and Animator components and combines them in such a way that the actual animation depends on the movement of Rigidbody. It provides an inputs that allows the pedestrian to move - change his position and orientation. In addition, the ReferencePoint point is used to ensure that the pedestrian follows the ground plane correctly.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Ray Cast Max Distance - ray-cast max distance for locating the ground.
    • Ray Cast Origin Offset - upward offset of the ray-cast origin from the GameObject local origin for locating the ground.
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#input-data","title":"Input Data","text":"Category Type Description SetPosition Vector3 Move the NPCPedestrian so that the reference point is at the specified coordinates. SetRotation Vector3 Rotate the NPCPedestrian so that the orientation of the reference point becomes the specified one."},{"location":"Components/Traffic/NPCs/Pedestrian/#simple-pedestrian-walker-controller-script","title":"Simple Pedestrian Walker Controller (script)","text":"

    Simple Pedestrian Walker Controller is a script that allows the pedestrian to cyclically move back and forth along a straight line. One-way motion is performed with a fixed time as parameter Duration and a constant linear velocity as parameter Speed. The script obviously uses the NPCPedestrian controls provided by the NPC Pedestrian (script) inputs.

    Pedestrian walking on the sidewalk

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#collider","title":"Collider","text":"

    Collider is an optional pedestrian component. By default, NPCPedestrian doesn't have this component added, It can be added if you want to detect a collision, e.g. with an EgoVehicle. There are several types of colliders, choose the right one and configure it for your own requirements.

    Capsule Collider

    An example of a CapsuleCollider that covers almost the entire pedestrian.

    "},{"location":"Components/Traffic/NPCs/Vehicle/","title":"Vehicle","text":""},{"location":"Components/Traffic/NPCs/Vehicle/#npcvehicle","title":"NPCVehicle","text":""},{"location":"Components/Traffic/NPCs/Vehicle/#introduction","title":"Introduction","text":"

    NPCVehicle is a non-playable object that simulates a vehicle that is stationary or moving around the scene. It can move on roads, more specifically TrafficLanes, thanks to the use of TrafficSimulator - which you can read more about here. Vehicles moving on the scene take into account each other - avoiding collisions, follow traffic lights and have an implemented mechanism of yielding the right of way.

    Sample scene

    If you would like to see how NPCVehicle works or run some tests, we encourage you to familiarize yourself with the NPCVehicleSample default scene described in this section.

    Ego Vehicle

    If you are interested in the most important vehicle on the scene - Ego Vehicle, we encourage you to read this section.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#prefabs-and-fbxs","title":"Prefabs and Fbxs","text":"

    Prefabs can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Vehicles/*\n

    The table shows the available prefabs of the vehicles:

    Hatchback SmallCar Taxi Truck Van Appearance Prefab Hatchback.prefab SmallCar.prefab Taxi-64.prefab Truck_2t.prefab Van.prefab

    NPCVehicle prefab has the following content:

    As you can see, it consists of 2 parents for GameObjects: Visuals - aggregating visual elements, Colliders - aggregating colliders and single object CoM. All objects are described in the sections below.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#visual-elements","title":"Visual elements","text":"

    Prefabs are developed using models available in the form of *.fbx files. For each vehicle, the visuals elements and LOD were loaded from the appropriate *.fbx file. The LOD is always added as components of the main-parent GameObject in prefab, while the visual elements of the model are aggregated and added in object Visuals.

    *.fbx file for each vehicle is located in the appropriate Models directory for the vehicle under the following path:

    Assets/AWSIM/Models/NPCs/Vehicles/<vehicle_name>/Models/<vehicle_name>.fbx\n

    As you can see, the additional visual element is Driver.

    It was also loaded from the *.fbx file which can be found under the following path:

    Assets/AWSIM/Models/NPCs/Vehicles/Driver/Model/Driver.fbx\n

    Vehicle fbx

    The content of a sample *.fbx file is presented below, all elements except Collider have been added to the prefab as visual elements of the vehicle. Collider is used as the Mesh source for the Mesh Collider in the BodyCollider object.

    .

    "},{"location":"Components/Traffic/NPCs/Vehicle/#link","title":"Link","text":"

    The default scene does not have vehicles implemented in fixed places, but they are spawned by RandomTrafficSimulator which is located in the Environment prefab. Therefore, before starting the simulation, no NPCVehicle object is on the scene.

    When you run the simulation, you can see objects appearing as children of RandomTrafficSimulator:

    In each NPCVehicle prefab, the local coordinate system of the vehicle (main prefab link) should be defined in the axis of the rear wheels projected onto the ground - in the middle of the distance between them. This aspect holds significance when characterizing the dynamics of the object, as it provides convenience in terms of describing its motion and control.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#components","title":"Components","text":"

    There are several components responsible for the full functionality of NPCVehicle:

    • LOD Group - provides level of detail configuration for shaders - affects GPU usage.
    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • NPC Vehicle (script) - provides the ability to change the position and orientation of the vehicle, as well as to control the turn signals and brake light.

    Script can be found under the following path:

    Assets/AWSIM/Scripts/NPCs/Vehicles\n
    "},{"location":"Components/Traffic/NPCs/Vehicle/#com","title":"CoM","text":"

    CoM (Center of Mass) is an additional link that is defined to set the center of mass in the Rigidbody. The NPC Vehicle (script) is responsible for its assignment. This measure should be defined in accordance with reality. Most often, the center of mass of the vehicle is located in its center, at the height of its wheel axis - as shown below.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#colliders","title":"Colliders","text":"

    Colliders are used to ensure collision between objects. In NPCVehicle, the main BodyCollider collider and Wheels Colliders colliders for each wheel were added.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#body-collider","title":"Body Collider","text":"

    BodyCollider is a vehicle Object responsible for ensuring collision with other objects. Additionally it can be used to detect these collisions. The MeshCollider uses a Mesh of an Object to build its Collider. The Mesh for the BodyCollider was also loaded from the *.fbx file similarly to the visual elements.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#wheels-colliders","title":"Wheels Colliders","text":"

    WheelsColliders are an essential element from the point of view of driving vehicles on the road. They are the only ones that have contact with the roads and it is important that they are properly configured. Each vehicle, apart from the visual elements related to the wheels, should also have 4 colliders - one for each wheel.

    To prevent inspector entry for WheelCollider the WheelColliderConfig has been developed. It ensures that friction is set to 0 and only wheel suspension and collisions are enabled.

    Wheel Collider Config

    For a better understanding of the meaning of WheelCollider we encourage you to read this manual.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#lod","title":"LOD","text":"

    LOD provides dependence of the level of detail of the object depending on the ratio of the GameObject\u2019s screen space height to the total screen height. Vehicle models have only one LOD0 group, therefore there is no reduction in model complexity when it does not occupy a large part of the screen. It is only culled when it occupies less than 2% of the height.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. The Mass of the vehicle should approximate its actual weight. In order for the vehicle to physically interact with other objects - react to collisions, Is Kinematic must be turned off. The Use Gravity should be turned on - to ensure the correct behavior of the body during movement. In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#npc-vehicle-script","title":"NPC Vehicle (script)","text":"

    The script takes the Rigidbody and provides an inputs that allows the NPCVehicle to move. Script inputs give the ability to set the position and orientation of the vehicle, taking into account the effects of suspension and gravity. In addition, the script uses the CoM link reference to assign the center of mass of the vehicle to the Rigidbody.

    Script inputs are used by RandomTrafficSimulator, which controls the vehicles on the scene - it is described here.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#input-data","title":"Input Data","text":"Category Type Description SetPosition Vector3 Move the NPCVehicle so that its x, z coordinates are same as the specified coordinates. Pitch and roll are determined by physical operations that take effects of suspension and gravity into account. SetRotation Vector3 Rotate the NPCVehicle so that its yaw becomes equal to the specified one. Vertical movement is determined by physical operations that take effects of suspension and gravity into account.

    Visual Object Root is a reference to the parent aggregating visuals, it can be used to disable the appearance of visual elements of the NPCVehicle in the scene.

    Whereas Bounds Represents an axis aligned bounding box of the NPCVehicle. It is used primarily to detect collisions between vehicles in the event of spawning, yielding and others. Moreover, vehicle bounds are displayed by Gizmos.

    The settings of the remaining elements, i.e. the Axle and the Lights, are described here and here.

    No Gizmo visualization

    If you don't see Gizmo's visual elements, remember to turn them on.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#axle-settings","title":"Axle Settings","text":"

    This part of the settings is responsible for the proper connection of visual elements with the collider for each wheel - described earlier. The objects configured in this section are used to control the vehicle - its wheel speed and steering angle, which are calculated based on the input values. Correct configuration is very important from the point of view of the NPCVehicle movement on the road.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#lights-settings","title":"Lights Settings","text":"

    This part of the settings is related to the configuration of materials emission - used when a specific lighting is activated. There are 3 types of lights: Brake, Left Turn Signal and Right Turn Signal. Each of the lights has its visual equivalent in the form of a Mesh. In the case of NPCVehicle all of the lights are included in the Body object Mesh, which has many materials - including those related to lights.

    For each type of light, the appropriate Material Index (equivalent of element index in mesh) and Lighting Color are assigned - yellow for Turn Signals, red for Break.

    Lighting Intensity values are also configured - the greater the value, the more light will be emitted. This value is related to Lighting Exposure Weight parameter that is an exposure weight - the lower the value, the more light is emitted.

    The brake light is switched on depending on the speed of the NPCVehicle, while RandomTrafficSimulator is responsible for switching the turn signals on and off.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/","title":"Add Random Traffic Environment","text":""},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#add-environment-for-random-traffic","title":"Add Environment for Random Traffic","text":"

    This document describes the steps to properly configuer RandomTrafficSimulator in your environment.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#map-preparation","title":"Map preparation","text":"

    The 3D map model should be added to the scene. Please make sure that the Environment component with appropriate mgrsOffsetPosition is attached to the root GameObject.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-traffic-lights","title":"Annotate Traffic Lights","text":"

    Please attach TrafficLight component to all traffic light GameObjects placed on scene.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#load-lanelet","title":"Load Lanelet","text":"

    The lanelet load process can be performed by opening AWSIM -> Random Traffic -> Load Lanelet at the top toolbar of Unity Editor.

    You should be prompted with a similar window to the one presented below. Please adjust the parameters for the loading process if needed.

    Waypoint settings affect the density and accuracy of the generated waypoints. The parameters are described below:

    • Resolution: resolution of resampling. Lower values provide better accuracy at the cost of processing time.
    • Min Delta Length: minimum length(m) between adjacent points.
    • Min Delta Angle: minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve.

    To generate the Lanelet2 map representation in your simulation, please click the Load button. Environment components should be generated and placed as child objects of the Environment GameObject. You can check their visual representation by clicking consecutive elements in the scene hierarchy.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-traffic-intersections","title":"Annotate Traffic Intersections","text":"

    To annotate intersection please, add an empty GameObject named TrafficIntersections at the same level as the TrafficLanes GameObject.

    For each intersection repeat the following steps:

    1. Add an GameObject named TrafficIntersection as a child object of the TrafficIntersections object.
    2. Attach a TrafficIntersection component to it.
    3. Add a BoxCollider as a component of GameObject. It's size and position should cover the whole intersection. This is used for detecting vehicles in the intersection.
    4. Set TrafficLightGroups. Each group is controlled to have different signals, so facing traffic lights should be added to the same group. These groupings are used in traffic signal control.
    5. Specify the signal control pattern.
    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-right-of-ways-on-uncontrolled-intersections","title":"Annotate right of ways on uncontrolled intersections","text":"

    For the vehicles to operate properly it is needed to annotate the right of way of TrafficLane manually on intersections without traffic lights.

    To set the right of way, please:

    • Select a straight lane that is not right of way in the intersection. The selected lane should be highlighted as presented below.
    • Click the Set RightOfWays button to give the lane priority over other lanes.
    • Please check if all lanes that intersect with the selected lane are highlighted yellow. This means that the right of way was applied correctly.
    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-stop-lines","title":"Annotate stop lines","text":"

    For each right turn lane that yields to the opposite straight or left turn lane, a stop line needs to be defined near the center of the intersection. If there is no visible stop line, a StopLine component should be added to the scene, near the center of the intersection and associated with TrafficLane.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#assign-intersection-trafficlanes","title":"Assign Intersection TrafficLanes","text":"

    To make the yielding rules work properly, it is necessary to catagorize the TrafficLanes. The ones that belong to an intersection have the IntersectionLane variable set to true.

    To automate the assignment of the corresponding IntersectionLane to each TrafficLane, the script AssignIntersectionTrafficLanes can be used.

    1. At the time of assignment, add it as a component to some object in the scene (e.g. to the Environment object).
    2. Disable the component (uncheck the checkbox next to the script name).
    3. Assign to TrafficLanesObjectsParent GameObject, which contains all TrafficLanes objects.
    4. Check all 4 options.
    5. Enable the component (check the checkbox next to the script name).

    Check the log to see if all operations were completed:

    As a result, the names of TrafficLane objects should have prefixes with sequential numbers and TrafficLane at intersections should be marked. TrafficLanes with IntersectionLane set to True are displayed by Gizmos in green color, if IntersectionLane is False their color is white.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#check-final-configuration","title":"Check final configuration","text":"

    Once all the components are ready, the simulation can be run. Check carefully if the vehicles are moving around the map correctly. For each intersection, review the settings of the relevant components if vehicles are unable to proceed.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/","title":"Random Traffic Simulator","text":""},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#random-traffic-simulator","title":"Random Traffic Simulator","text":"

    The RandomTrafficSimulator simulates city traffic with respect to all traffic rules. The system allows for random selection of car models and the paths they follow. It also allows adding static vehicles in the simulation.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#getting-started","title":"Getting Started","text":""},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#overview","title":"Overview","text":"

    The random traffic system consists of the following components:

    • RandomTrafficSimulator: manages lifecycle of NPCs and simulates NPC behaviours.
    • TrafficLane, TrafficIntersection and StopLine: represent traffic entities
    • NPCVehicle: vehicle models (NPCs) controlled by RandomTrafficSimulator

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#components-settings","title":"Components Settings","text":"

    The following section describes Unity Editor components settings.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#random-traffic-simulator_1","title":"Random Traffic Simulator","text":"Parameter Description General Settings Seed Seed value for random generator Ego Vehicle Transform of ego vehicle Vehicle Layer Mask LayerMask that masks only vehicle(NPC and ego) colliders Ground Layer Mask LayerMask that masks only ground colliders of the map NPC Vehicle Settings Max Vehicle Count Maximum number of NPC vehicles to be spawned in simulation NPC Prefabs Prefabs representing controlled vehicles. They must have NPCVehicle component attached. Spawnable Lanes TrafficLane components where NPC vehicles can be spawned during traffic simulation Vehicle Config Parameters for NPC vehicle controlSudden Deceleration is a deceleration related to emergency braking Debug Show Gizmos Enable the checkbox to show editor gizmos that visualize behaviours of NPCs"},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#gizmos","title":"Gizmos","text":"

    Gizmos are useful for checking current behavior of NPCs and its causes. Gizmos have a high computational load so please disable them if the simulation is laggy.

    "},{"location":"Components/Traffic/RandomTraffic/YieldingRules/","title":"Yielding Rules","text":""},{"location":"Components/Traffic/RandomTraffic/YieldingRules/#yielding-rules","title":"Yielding rules","text":"

    The RandomTrafficSimulator assumes that there are 10 phases of yielding priority:

    RandomTrafficYielding scene

    If you would like to see how RandomTrafficSimulator with yielding rules works or run some tests, we encourage you to familiarize yourself with the RandomTrafficYielding scene described in this section.

    1. NONE - state in which it is only checked if a vehicle is approaching the intersection. If yes, a transition to state ENTERING_INTERSECTION is made.

    2. ENTERING_INTERSECTION - state in which it is checked if any of the situations LANES_RULES_ENTERING_INTERSECTION, LEFT_HAND_RULE_ENTERING_INTERSECTION, INTERSECTION_BLOCKED occur, if yes the state of the vehicle is changed to one matching the situation - to determine if the vehicle must yield priority. If none of these situations occur only the entry into the intersection will result in a transition to AT_INTERSECTION.

    3. AT_INTERSECTION - state in which it is checked if any of the situations LANES_RULES_AT_INTERSECTION, LEFT_HAND_RULE_AT_INTERSECTION, FORCING_PRIORITY occur, if yes the state of the vehicle is changed to one matching the situation - to determine if the vehicle must yield priority. If none of these situations occur only leaving the intersection will result in a transition to NONE.

    4. INTERSECTION_BLOCKED - when vehicle A is approaching the intersection, it yields priority to vehicle B, which should yield priority, but is forcing it - this refers to a situation in which vehicle B has entered the intersection and has already passed its stop point vehicle B isn\u2019t going to stop but has to leave the intersection. Until now, vehicle A has continued to pass through the intersection without taking vehicle B into account, now it is checking if any vehicle is forcing priority (vehicle A has INTERSECTION_BLOCKED state). (vehicle A is red car with blue sphere, B is the white car to which it points)

    5. LEFT_HAND_RULE_ENTERING_INTERSECTION - vehicle A, before entering the intersection where the traffic lights are off, yields priority to vehicles (ex. B) that are approaching to the intersection and are on the left side of vehicle A. Until now, situations in which the lights are off were not handled. If a vehicle didn't have a red light and was going straight - it just entered the intersection. Now vehicle A checks if the vehicles on the left (ex. B) have a red light, if not it yields them priority. (vehicle A is truck car with gray sphere, B is the white car to which it points)

    6. LEFT_HAND_RULE_AT_INTERSECTION - when vehicle A is already at the intersection, yields priority to vehicles (ex. B) that are also at the intersection and are on its left side - in cases where no other yielding rules are resolved between them (i.e. there are no RightOfWayLanes between them). (vehicle A is red, B is white)

    7. LANES_RULES_ENTERING_INTERSECTION - when vehicle B intends to turn left and is approaching at the intersection where it needs to yield to vehicle A which is going straight ahead, then it goes to state LANES_RULES_ENTERING_INTERSECTION. The introduced changes take into account that a vehicle approaching the intersection considers not only the vehicles at the intersection but also those which are approaching it (at a distance of less than minimumDistanceToIntersection to the intersection). (vehicle B is truck with yellow sphere, A the white car to which it points)

    8. LANES_RULES_AT_INTERSECTION - when vehicle B intends to turn right and is already at the intersection where it needs to yield to vehicle A which is approaching the intersection, then it goes to state LANES_RULES_AT_INTERSECTION. The introduced changes take into account that a vehicle approaching the intersection considers not only the vehicles at the intersection but also those which are approaching it (at a distance of less than minimumDistanceToIntersection to the intersection). (vehicle B is car with red sphere, A the white car to which it points)

    9. FORCING_PRIORITY - state in which some vehicle B should yield priority to a vehicle A but doesn't - for some reason, most likely it could be some unusual situation in which all other rules have failed. Then vehicle A which is at intersection yields priority to a vehicle that is forcing priority. In such a situation, vehicle A transitions to state FORCING_PRIORITY. It is very rare to achieve this state, but it does happen.

    "},{"location":"Components/Traffic/RandomTraffic/YieldingRules/#gizmos-markings","title":"Gizmos Markings","text":"
    • No sphere means the vehicle is in one of the following states - NONE, ENTERING_INTERSECTION or AT_INTERSECTION.
    • The gray sphere means that the vehicle is approaching the intersection and yields priority to the vehicle on the left side - LEFT_HAND_RULE_ENTERING_INTERSECTION.
    • The black sphere means that the vehicle is at the intersection and yields priority to a vehicle on the left side - LEFT_HAND_RULE_AT_INTERSECTION.
    • The yellow sphere means that the vehicle yields due to lanes rules before entering the intersection - LANES_RULES_ENTERING_INTERSECTION.
    • The red sphere means that it yields due to lanes rules but is already at the intersection - LANES_RULES_AT_INTERSECTION.
    • The blue sphere means that a vehicle is approaching the intersection and yields priority to a vehicle that is forcing priority - INTERSECTION_BLOCKED - when the turning vehicle begins to yield, then the blue sphere disappears. However, if the turning vehicle continues to turn (does not yield because it has passed the stopping point), then the vehicle going straight stops before the intersection and allows the turning vehicle to leave the intersection.
    • The pink sphere means that a vehicle is at intersection and yields priority to a vehicle that is forcing priority - FORCING_PRIORITY.
    "},{"location":"Components/Traffic/TrafficComponents/","title":"Traffic Components","text":"

    This section

    This section is still under development!

    This is a section that describes in detail all components related to simulated traffic in the Environment prefab.

    "},{"location":"Components/Traffic/TrafficComponents/#architecture","title":"Architecture","text":"

    The random traffic system consists of the following components:

    • TrafficManager

      It is a top level interface meant to be used on the Unity scene. TrafficManager runs all elements needed for a successful traffic simulation. This component manages all TrafficSimulators so they don't work against each other. It gives you the possibility to configure the TrafficSimulators.

    • TrafficSimulator

      Technically it is not a component, it is crucial to understand what it is and what it does in order to correctly configure the TrafficManager. TrafficSimulator manages NPCVehicles spawning. There can be many TrafficSimulators on the scene. They are added and configured in the TrafficManager component. Every TrafficSimulator manages some part of the traffic it is responsible for - meaning it has spawned the NPCVehicles and set their configuration.

      • RandomTrafficSimulator - spawns and controls NPCVehicles driving randomly
      • RouteTrafficSimulator - spawns and controls NPCVehicles driving on a defined route

      TrafficSimulator inaccessibility

      It is not possible to get direct access to the TrafficSimulator. It should be added and configured through the TrafficManager component.

    • TrafficLane, TrafficIntersection and StopLine

      These components represent traffic entities. They are used to control and manage the traffic with respect to traffic rules and current road situation.

    • NPCVehicle

      The vehicle models (NPCs) spawned by one of the TrafficSimulators. They are spawned according to the TrafficSimulator configuration and either drive around the map randomly (when spawned by a RandomTrafficSimulator) or follow the predefined path (when spawned by a RouteTrafficSimulator). NPCVehicles are managed by one central knowledge base.

    The process of spawning a NPCVehicle and its later behavior control is presented on the following sequence diagram.

    Sequence Diagram Composition

    Please note that the diagram composition has been simplified to the level of GameObjects and chosen elements of the GameObjects for the purpose of improving readability.

    "},{"location":"Components/Traffic/TrafficComponents/#lanelet2","title":"Lanelet2","text":"

    Lanelet2 is a library created for handling a map focused on automated driving. It also supports ROS and ROS2 natively. In AWSIM Lanelet2 is used for reading and handling a map of all roads. Specifically it does contain all TrafficLanes and StopLines. You may also see us referring to the actual map data file (*.osm) as a Lanelet2.

    Lanelet2 official page

    If you want to learn more we encourage to visit the official project page.

    "},{"location":"Components/Traffic/TrafficComponents/#randomtrafficsimulator","title":"RandomTrafficSimulator","text":"

    Nomenclature

    Please note that

    • a GameObject
    • an element spawning NPCVehicles randomly and
    • the whole system of traffic control

    are named RandomTrafficSimulator. Keep this in mind when reading the following page - so you don't get confused.

    RandomTrafficSimulator simulates traffic with respect to all traffic rules. The system allows for random selection of car models and the paths they follow. It also allows adding static vehicles in the simulation.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The RandomTrafficSimulator consists of several GameObjects.

    • RandomTrafficSimulator - this is an Object consisting of a Traffic Manager (script). You can learn more about it here.
    • TrafficIntersections - this is a parent Object for all TrafficIntersections. You can learn more about it here.
    • TrafficLanes - this is a parent Object for all TrafficLanes. You can learn more about it here.
    • StopLines - this is a parent Object for all StopLines. You can learn more about it here.
    "},{"location":"Components/Traffic/TrafficComponents/#components","title":"Components","text":"

    RandomTrafficSimulator only has one component: Traffic Manager (script) which is described below.

    "},{"location":"Components/Traffic/TrafficComponents/#trafficmanager-script","title":"TrafficManager (script)","text":"

    Traffic Manager (script) is responsible for all of top level management of the NPCVehicles. It managed spawning of NPCVehicles on TrafficLanes.

    TrafficManager uses the concept of TrafficSimulators. One TrafficSimulator is responsible for managing its set of NPCVehicles. Every TrafficSimulator spawns its own NPCVehicles independently. The vehicles spawned by one TrafficSimulator do respect its configuration. TrafficSimulators can be interpreted as NPCVehicle spawners with different configurations each. Many different TrafficSimulators can be added to the TrafficManager.

    If a random mode is selected (RandomTrafficSimulator) then NPCVehicles will spawn in random places (from the selected list) and drive in random directions. To be able to reproduce the behavior of the RandomTrafficSimulator a Seed can be specified - which is used for the pseudo-random numbers generation.

    TrafficManager script also configures all of the spawned NPCVehicles, so that they all have common parameters

    • Acceleration - the acceleration used by the vehicles at all times when accelerating.
    • Deceleration - the value of deceleration used in ordinary situations.
    • Sudden Deceleration - deceleration used when standard Deceleration is not sufficient to avoid accident.
    • Absolute Deceleration - value of deceleration used when no other deceleration allows to avoid the accident.

    The Vehicle Layer Mask and Ground Layer Mask are used to make sure all vehicles can correctly interact with the ground to guarantee simulation accuracy.

    Max Vehicle Count specifies how many NPCVehicles can be present on the scene at once. When the number of NPCVehicles on the scene is equal to this value the RandomTrafficSimulator stops spawning new vehicles until some existing vehicles drive away and disappear.

    The EgoVehicle field provides the information about Ego vehicle used for correct behavior ofNPCVehicleswhen interacting with Ego.

    Show Gizmos checkbox specifies whether the Gizmos visualization should be displayed when running the simulation.

    Show Yielding Phase checkbox specifies whether yielding phases should be displayed by Gizmos - in the form of spheres above vehicles, details in the Markings section.

    Show Obstacle Checking checkbox specifies whether obstacle checking should be displayed by Gizmos - in the form of boxes in front of vehicles

    Show Spawn Points checkbox specifies whether spawn points should be displayed by Gizmos - in the form of flat cuboids on roads.

    Gizmos performance

    Gizmos have a high computational load. Enabling them may cause the simulation to lag.

    As mentioned earlier - TrafficManager may contain multiple TrafficSimulators. The two available variants of TrafficSimulator are described below

    • RandomTrafficSimulator
    • RouteTrafficSimulator

    TrafficSimulators should be interpreted as spawning configurations for some group of NPCVehicles on the scene.

    "},{"location":"Components/Traffic/TrafficComponents/#random-traffic","title":"Random Traffic","text":"

    When using RandomTrafficSimulator the NPCVehicle prefabs (NPC Prefabs) can be chosen as well as Spawnable Lanes. The later are the only TrafficLanes on which the NPCVehicles can spawn. Upon spawning one of the Spawnabe Lanes is chosen and - given the vehicle limits are not reached - one random NPCVehicle from the Npc prefabs list is spawned on that lane. After spawning, the NPCVehicle takes a random route until it drives out of the map - then it is destroyed.

    The Maximum Spawns field specifies how many Vehicles should be spawned before this TrafficSimulator stops working. Set to 0 to disable this restriction.

    "},{"location":"Components/Traffic/TrafficComponents/#route-traffic","title":"Route Traffic","text":"

    When using Route traffic Simulator the NPCVehicle prefabs (NPC Prefabs) as well as Route can be chosen. The later is an ordered list of TrafficLanes that all spawned vehicles will drive on. Given the vehicle limit is not reached - the RouteTrafficSimulator will spawn one of the Npc Prefabs chosen randomly on the first Route element (Element 0). After the first vehicle drives off the next one will spawn according to the configuration. It is important for all Route elements to be connected and to be arranged in order of appearance on the map. The NPCVehicle disappears after completing the Route.

    The Maximum Spawns field specifies how many Vehicles should be spawned before this TrafficSimulator stops working. Set to 0 to disable this restriction.

    "},{"location":"Components/Traffic/TrafficComponents/#parameter-explanation","title":"Parameter explanation","text":"Parameter Description General Settings Seed Seed value for random generator Ego Vehicle Transform of ego vehicle Vehicle Layer Mask LayerMask that masks only vehicle(NPC and ego) colliders Ground Layer Mask LayerMask that masks only ground colliders of the map Culling Distance Distance at which NPCs are culled relative to EgoVehicle Culling Hz Culling operation cycle NPCVehicle Settings Max Vehicle Count Maximum number of NPC vehicles to be spawned in simulation NPC Prefabs Prefabs representing controlled vehicles. They must have NPCVehicle component attached. Spawnable Lanes TrafficLane components where NPC vehicles can be spawned during traffic simulation Vehicle Config Parameters for NPC vehicle controlSudden Deceleration is a deceleration related to emergency braking Debug Show Gizmos Enable the checkbox to show editor gizmos that visualize behaviours of NPCs"},{"location":"Components/Traffic/TrafficComponents/#traffic-light-script","title":"Traffic Light (script)","text":"

    Traffic Light (script) is a component added to every TrafficLight on the scene. It is responsible for configuring the TrafficLight behavior - the bulbs and their colors.

    The Renderer filed points to the renderer that should be configured - in this case it is always a TrafficLight renderer.

    Bulbs Emission Config is a list describing available colors for this Traffic Light. Every element of this list configures the following

    • Bulb Color - the name of the configured color that will be used to reference this color
    • Color - the actual color with which a bulb should light up
    • Intensity - the intensity of the color
    • Exposure Weight - how bright should the color be when lighting up

    The Bulb Material Config is a list of available bulbs in a given Traffic Light. Every element describes a different bulb. Every bulb has the following aspects configured

    • Bulb Type - the name that will be usd to reference the configured bulb
    • Material Index - The index of a material of the configured bulb. This is an index of a sub-mesh of the configured bulb in the Traffic Light mesh. The material indices are described in detail here and here.
    "},{"location":"Components/Traffic/TrafficComponents/#trafficintersections","title":"TrafficIntersections","text":"

    TrafficIntersection is a representation of a road intersection. It consists of several components. TrafficIntersection is used in the Scene for managing TrafficLights. All Traffic Lights present on one Traffic Intersection must be synchronized - this is why the logic of TrafficLight operation is included in the TrafficIntersection.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_1","title":"Link in the default Scene","text":"

    Every TrafficIntersection has its own GameObject and is added as a child of the aggregate TrafficIntersections Object. TrafficIntersections are elements of an Environment, so they should be placed as children of an appropriate Environment Object.

    "},{"location":"Components/Traffic/TrafficComponents/#components_1","title":"Components","text":"

    TrafficIntersection has the following components:

    • Box Collider - marks the area of the Traffic Intersection, it should cover the whole intersection area
    • Traffic Intersection (script) - controls all Traffic Lights on the given intersection according to the configuration
    "},{"location":"Components/Traffic/TrafficComponents/#collider","title":"Collider","text":"

    Every TrafficIntersection contains a Box Collider element. It needs to accurately cover the whole area of the TrafficIntersection. Box Collider - together with the Traffic Intersection (script) - is used for detecting vehicles entering the TrafficIntersection.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-intersection-script","title":"Traffic Intersection (script)","text":"

    Traffic Intersection (script) is used for controlling all TrafficLights on a given intersection. The Collider Mask field is a mask on which all Vehicle Colliders are present. It - together with Box Collider - is used for keeping track of how many Vehicles are currently present on the Traffic Intersection. The Traffic Light Groups and Lighting Sequences are described below.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-light-groups","title":"Traffic Light Groups","text":"

    Traffic Light Group is a collection of all Traffic Lights that are in the same state at all times. This includes all redundant Traffic Lights shining in one direction as well as the ones in the opposite direction. In other words - as long as two Traffic Lights indicate exactly the same thing they should be added to the same Traffic Light Group. This grouping simplifies the creation of Lighting Sequences.

    "},{"location":"Components/Traffic/TrafficComponents/#lighting-sequences","title":"Lighting Sequences","text":"

    Lighting Sequences is the field in which the whole intersection Traffic Lights logic is defined. It consists of many different Elements. Each Element is a collection of Orders that should take an effect for the period of time specified in the Interval Sec field. Lighting Sequences Elements are executed sequentially, in order of definition and looped - after the last element sequence goes back to the first element.

    The Group Lighting Orders field defines which Traffic Light Groups should change their state and how. For every Group Lighting Orders Element the Traffic Lights Group is specified with the exact description of the goal state for all Traffic Lights in that group - which bulb should light up and with what color.

    One Lighting Sequences Element has many Group Lighting Orders, which means that for one period of time many different orders can be given. E.g. when Traffic Lights in one direction change color to green - Traffic Lights in the parallel direction change color to red.

    Traffic Light state persistance

    If in the given Lighting Sequences Element no order is given to some Traffic Light Group - this Group will keep its current state. When the next Lighting Sequences Element activates - the given Traffic Light Group will remain in an unchanged state.

    Lighting Sequence Sample - details

    Description Editor Traffic Lights in Pedestrian Group 1change color to flashing green. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Pedestrian Group 1change color to solid red. Other Groups keep theircurrent state. This state lasts for 1 second. Traffic Lights in Vehicle Group 1change color to solid yellow. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Vehicle Group 1change color to solid red. Other Groups keep theircurrent state. This state lasts for 3 seconds. Traffic Lights in Vehicle Group 2change color to solid green. Traffic Lights in Pedestrian Group 2change color to solid green. Other Groups keep theircurrent state. This state lasts for 15 seconds. Traffic Lights in Pedestrian Group 2change color to flashing green. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Pedestrian Group 2change color to solid red. Other Groups keep theircurrent state. This state lasts for 1 second. Traffic Lights in Vehicle Group 2change color to solid yellow. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Vehicle Group 2change color to solid red. Other Groups keep theircurrent state. This state lasts for 3 second. Sequence loops back to thefirst element of the list."},{"location":"Components/Traffic/TrafficComponents/#trafficlanes","title":"TrafficLanes","text":"

    TrafficLane is a representation of a short road segment. It consists of several waypoints that are connected by straight lines. TrafficLanes are used as a base for a RandomTrafficSimulator. They allow NPCVehicles to drive on the specific lanes on the road and perform different maneuvers with respect to the traffic rules. TrafficLanes create a network of drivable roads when connected.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_2","title":"Link in the default Scene","text":"

    Every TrafficLane has its own GameObject and is added as a child of the aggregate TrafficLanes Object. TrafficLanes are an element of an Environment, so they should be placed as children of an appropriate Environment Object.

    TrafficLanes can be imported from the lanelet2 *.osm file.

    "},{"location":"Components/Traffic/TrafficComponents/#components_2","title":"Components","text":"

    TrafficLane consists of an Object containing Traffic Lane (script).

    TrafficLane has a transformation property - as every Object in Unity - however it is not used in any way. All details are configured in the Traffic Lane (script), the information in Object transformation is ignored.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-lane-script","title":"Traffic Lane (script)","text":"

    Traffic Lane (script) defines the TrafficLane structure. The Waypoints field is an ordered list of points that - when connected with straight lines - create a TrafficLane.

    Traffic Lane (script) coordinate system

    Waypoints are defined in the Environment coordinate system, the transformation of GameObject is ignored.

    Turn Direction field contains information on what is the direction of this TrafficLane - whether it is a right or left turn or straight road.

    Traffic lanes are connected using Next Lanes and Prev Lanes fields. This way individual TrafficLanes can create a connected road network. One Traffic Lane can have many Next Lanes and Prev Lanes. This represents the situation of multiple lanes connecting to one or one lane splitting into many - e.g. the possibility to turn and to drive straight.

    Right Of Way Lanes are described below.

    Every TrafficLane has to have a Stop Line field configured when the Stop Line is present on the end of the TrafficLane. Additionally the Speed Limit field contains the highest allowed speed on given TrafficLane.

    "},{"location":"Components/Traffic/TrafficComponents/#right-of-way-lanes","title":"Right Of Way Lanes","text":"

    Right Of Way Lanes is a collection of TrafficLanes. Vehicle moving on the given TrafficLane has to give way to all vehicles moving on every Right Of Way Lane. It is determined based on basic traffic rules. Setting Right Of Way Lanes allows RandomTrafficSimulator to manage all NPCVehicles so they follow traffic rules and drive safely.

    In the Unity editor - when a TrafficLane is selected - aside from the selected TrafficLane highlighted in blue, all Right Of Way Lanes are highlighted in yellow.

    Right Of Way Lanes Sample - details

    The selected TrafficLane (blue) is a right turn on an intersection. This means, that before turning right the vehicle must give way to all vehicles driving from ahead - the ones driving straight as well as the ones turning left. This can be observed as TrafficLanes highlighted in yellow.

    "},{"location":"Components/Traffic/TrafficComponents/#stoplines","title":"StopLines","text":"

    StopLine is a representation of a place on the road where vehicles giving way to other vehicles should stop and wait. They allow RandomTrafficSimulator to manage NPCVehicles in safe and correct way - according to the traffic rules. All possible locations where a vehicle can stop in order to give way to other vehicles - that are enforced by an infrastructure, this does not include regular lane changing - need to be marked with StopLines.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_3","title":"Link in the default Scene","text":"

    Every StopLine has its own GameObject and is added as a child of the aggregate StopLines Object. Stop Lines are an element of an Environment, so they should be placed as children of an appropriate Environment Object.

    StopLines can be imported from the lanelet2 *.osm file.

    "},{"location":"Components/Traffic/TrafficComponents/#components_3","title":"Components","text":"

    StopLine consists of an Object containing Stop Line (script).

    Stop Line has a transformation property - as every Object in Unity - however it is not used in any way. All details are configured in the Traffic Lane (script), the information in Object transformation is ignored.

    "},{"location":"Components/Traffic/TrafficComponents/#stop-line-script","title":"Stop Line (script)","text":"

    Stop Line (script) defines StopLine configuration. The Points field is an ordered list of points that - when connected - create a StopLine. The list of points should always have two elements that create a straight StopLine.

    Stop Line (script) coordinate system

    Points are defined in the Environment coordinate system, the transformation of GameObject is ignored.

    The Has Stop Sign field contains information whether the configured StopLine has a corresponding StopSign on the scene.

    Every Stop Line needs to have a Traffic Light field configured with the corresponding Traffic Light. This information allows the RandomTrafficSimulator to manage the NPCVehicles in such a way that they respect the Traffic Lights and behave on the Traffic Intersections correctly.

    "},{"location":"Components/Traffic/TrafficComponents/#gizmos","title":"Gizmos","text":"

    Gizmos are a in-simulation visualization showing current and future moves of the NPCVehicles. They are useful for checking current behavior of NPCs and its causes. On the Scene they are visible as cuboid contours indicating which TrafficLanes will be taken by each vehicle in the near future.

    Gizmos computing

    Gizmos have a high computational load. Please disable them if the simulation is laggy.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/","title":"Add Vehicle","text":"

    Ego Vehicle Component

    In this tutorial we will create a new EgoVehicle. To learn more about what an EgoVehicle is in AWSIM please visit Ego Vehicle description page.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#cerate-an-object","title":"Cerate an Object","text":"

    Add a child Object to the Simulation called EgoVehicle.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-rigidbody","title":"Add a Rigidbody","text":"

    1. While having a newly created EgoVehicle Object selected, in the Inspector view click on the 'Add Component' button, search for Rigidbody and select it.

    2. Configure Mass and Drag with the correct values for your Vehicle.

    3. Configure Interpolation and Collision Detection.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-visual-elements","title":"Add visual elements","text":"

    For a detailed explanation hwo to add visual elements of your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-canter-of-mass","title":"Add a Canter of Mass","text":"

    To add a center of mass to your vehicle you have to add a CoM child Object to the EgoVehicle Object (the same as in steps before).

    Then just set the position of the CoM Object in the Inspector view to represent real-world center of mass of the Vehicle.

    How do I know what is the Center of Mass of my Vehicle

    The best way is to obtain a Center of Mass information from your Vehicle documentation.

    However, if this is not possible, you can try to estimate the Center of Mass of your vehicle. Best practice is to set the estimated Center of Mass as the following

    • Evenly between the axles of the Vehicle
    • Right in the middle of the Vehicles width
    • Somewhere in the neighborhood of a quarter of the Vehicle height

    Note: This will vary very much depending on your Vehicle construction. For the best possible result please follow the Vehicle specifications.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-reflection-probe","title":"Add a Reflection Probe","text":"

    1. Add a new Object called Reflection Probe as a child to the EgoVehicle Object.

    2. Click on the 'Add Component' button, in the windows that pops-up search for Reflection Probe and select it.

      Note

      Please note that with Reflection Probe there should also be automatically added a `HD Additional Reflection Data Script.

    3. Configure the Reflection Probe as you wish.

      Example Configuration

      Below you can see an example configuration of the Reflection Probe.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-colliders","title":"Add Colliders","text":"

    For a detailed explanation how to add colliders to your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-base-for-sensors-urdf","title":"Add a base for sensors (URDF)","text":"

    You will most certainly want to add some sensors to your EgoVehicle. First you need to create a parent Object for all those sensors called URDF. To do this we will add a child Object URDF to the EgoVehicle Object.

    This Object will be used as a base for all sensors we will add later.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-script","title":"Add a Vehicle Script","text":"

    To be able to control your EgoVehicle you need a Vehicle Script.

    1. Add the Vehicle Script to the EgoVehicle Object.

    2. Configure the Vehicle Script Axle Settings and Center Of Mass Transform.

    Testing

    It is not possible to test this Script alone, but you can test the following

    • Vehicle Keyboard Input Script
    • Vehicle Visual Effects Script
    • Vehicle Ros Input Script

    If components listed above work correctly this means the Vehicle Script works correctly too.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-keyboard-input-script","title":"Add a Vehicle Keyboard Input Script","text":"

    You can control your EgoVehicle in the simulation manually with just one Script called Vehicle Keyboard Input.

    If you want to add it just click the 'Add Component' button on the EgoVehicle Object and search for Vehicle Keyboard Input Script and select it.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-visual-effect-script","title":"Add a Vehicle Visual Effect Script","text":"

    For a visual indication of a Vehicle status you will need a Vehicle Visual Effect Script. To add and configure it follow the steps below.

    1. Add a Vehicle Visual Effect Script by clicking 'Add Component' button, searching for it and selecting it.

    2. Configure the lights.

      Note

      In this step we will configure only Brake Lights, but should repeat this for every Light. The process is almost the same for all Lights - just change the mesh renderer and lighting settings according to your preference.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#how-to-test","title":"How to test","text":"

    After configuring Vehicle Visual Effect Script it is advised to test whether everything works as expected.

    1. Make sure you have a Vehicle Keyboard Input Script added and that it is enabled.

    2. If your scene does not have any models yet please turn the gravity off in Rigidbody configuration so that the Vehicle does not fall down into infinity.

    3. Start the simulation.

    4. Test the Turn Signals.

      You can control the Turn Signals with a Vehicle Keyboard Input Script. Activate the Turn Signals with one of the following keys

      • 1 - Left Turn Signal
      • 2 - Right Turn Signal
      • 3 - Hazard Lights
      • 4 - Turn Off all Signals

    5. Test the Lights.

      You can control the lights by \"driving\" the Vehicle using Vehicle Keyboard Input Script. Although if you have an empty Environment like in this tutorial the Vehicle won't actually drive.

      To test Brake Lights change the gear to Drive by pressing D on the keyboard and activate braking by holding arrow down.

      To test the Reverse Light change the gear to Reverse by pressing R on the keyboard. The Reverse Light should turn on right away.

    Camera tip

    If you have not configured a camera or configured it in such a way that you can't see the Vehicle well you can still test most of the lights by changing views.

    • Turn the Light (or Signal) on by pressing the appropriate key
    • Move to the Scene View by pressing ctrl + 1 - now you can move the camera freely
    • To change the Lights you need to go back to Game View by pressing ctrl + 2

    Pleas note that this method won't work for testing Brake Lights, as for them to work you need to keep the arrow down button pressed all the time.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-ros-input-script","title":"Add a Vehicle Ros Input Script","text":"

    For controlling your Vehicle with autonomous driving software (e.g. Autoware) you need a Vehicle Ros Input Script.

    Disable Vehicle Keyboard Input Script

    If you have added a Vehicle Keyboard Input Script in your Vehicle please disable it when using the Vehicle Ros Input Script.

    Not doing so will lead to the vehicle receiving two different inputs which will cause many problems.

    Add it to the EgoVehicle Object by clicking on the 'Add Component' button, searching for it and selecting it.

    The Script is configured to work with Autoware by default, but you can change the topics and Quality of Service settings as you wish.

    Note

    The Vehicle should be configured correctly, but if you have many Vehicles or something goes wrong, please select the right Vehicle in the Vehicle field by clicking on the small arrow icon and choosing the right item from the list.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#how-to-test_1","title":"How to test","text":"

    The best way to test the Vehicle Ros Input Script is to run Autoware.

    1. Run the Scene same as on this page.
    2. Launch only the Autoware like on this page
    3. Plan a path in Autoware like here, if the Vehicle moves in AWSIM correctly then the Script is configured well.
    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-sensors","title":"Add Sensors","text":"

    For a detailed explanation how to add sensors to your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-to-scene","title":"Add a Vehicle to Scene","text":"

    First you will have to save the Vehicle you created as a prefab, to easily add it later to different Scenes.

    1. Open the Vehicles directory in the Project view (Assets/AWSIM/Prefabs/Vehicles)
    2. Drag the Vehicle Object from the Hierarchy view to the Vehicles directory

    After that, you can add the Vehicle you created to different Scenes by dragging it from Vehicles directory to the Hierarchy of different Scenes.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/","title":"Add Colliders","text":"

    Next you need to add Colliders to your Vehicle. To do this follow the steps below.

    1. Add a child Object called Colliders to the EgoVehicle Object.

    2. Shift parent Object Colliders accordingly as in earlier steps where we shifted Models.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/#add-a-vehicle-collider","title":"Add a Vehicle Collider","text":"

    1. Add a child Object Collider to the Colliders Object.

    2. Add a Mesh Collider component to the Collider Object by clicking on the 'Add Component' button in the Inspector view and searching for it.

    3. Click on the arrow in mesh selection field and from the pop-up window select your collider mesh. Next click on the check-box called Convex, by now your collider mesh should be visible in the editor.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/#add-wheel-colliders","title":"Add Wheel Colliders","text":"

    1. Add a child Object Wheels to the Colliders Object.

    Note

    In this tutorial we will add only one wheel collider, but you should repeat the step for all 4 wheels. That is, follow the instructions that follow this message for every wheel your Vehicle has.

    • Front Left Wheel
    • Front Right Wheel
    • Rear Left Wheel
    • Rear Right Wheel

    1. Add a child Object FrontLeftWheel to the Wheels Object.

    2. Add a Wheel Collider component to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    3. Add a Wheel Script to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    4. Drag FrontLeftWheel Object from the WheelVisuals to the Wheel Visual Transform field.

    5. Add a Wheel Collider Config Script to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    6. Configure the Wheel Collider Config Script so that the Vehicle behaves as you wish.

    7. Set the Transform of FrontLeftWheel Object to match the visuals of your Vehicle.

    Successful configuration

    If you have done everything right your Colliders Object should look similar to the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/","title":"Add Sensors","text":""},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#awsim-sensors","title":"AWSIM Sensors","text":"

    There is a number of different sensors available in AWSIM. Below we present a list of sensors with links to their individual pages.

    • Vehicle Status Sensor
    • GNSS
    • LiDAR
    • IMU
    • Camera
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-links-for-sensors","title":"Add links for sensors","text":"

    Best practice is to replicate a ROS sensors transformations tree in Unity using Objects.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#coordinate-system-conversion","title":"Coordinate system conversion","text":"

    Please note that Unity uses less common left-handed coordinate system. Please keep this in mind while defining transformations. More details about right-handed and left-handed systems can be found here.

    To simplify the conversion process always remember that any point in ROS coordinate system (x, y, z) has an equivalent in the Unity coordinate system being (-y, z, x).

    The same can be done with the rotation. ROS orientation described with roll, pitch and yaw (r, p, y) can be translated to Unity Rotation as follows (p, -y, -r).

    Unit conversion

    Please remember to convert the rotation units. ROS uses radians and Unity uses degrees. The conversion from radians (rad) to degrees (deg) is as follows.

    deg = rad * 180 / PI\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-transformations-tree","title":"Add transformations tree","text":"

    URDF

    Before following this tutorial please make sure you have an URDF Object like it is shown shown in this section.

    First we will have to add a base_link which is the root of all transformations.

    Add a base_link Object as a child to the URDF Object.

    base_link transformation

    Please remember to set an appropriate transformation of the base_link Object so that it is identical as the base_link used in ROS in reference to the Vehicle.

    This is very important, as a mistake here will result in all subsequent sensors being misplaced.

    Inside the base_link we will represent all transformations contained in the ROS transformations tree.

    You will have to check your Vehicle specific configuration. You can do this in many ways, for example:

    • Check the ROS specific .yaml parameter files containing information about each transformation.

      Example

      Here we see an example .yaml file containing transformation from the base_link to the sensor_kit_base_link:

      base_link:\n    sensor_kit_base_link:\n        x: 0.9\n        y: 0.0\n        z: 2.0\n        roll: -0.001\n        pitch: 0.015\n        yaw: -0.0364\n

    • Check the values with ROS command line tools (for more information on these please visit official ROS 2 documentation).

      You can run a command like the following to check a transformation between two frames.

      ros2 run tf2_ros tf2_echo [source_frame] [target_frame]\n

      Example

      Here we see an example command with the output containing transformation from the base_link to the sensor_kit_base_link (note that the line after $ sign is the executed command):

      $ ros2 run tf2_ros tf2_echo base_link sensor_kit_base_link\n[INFO] [1686654712.339110702] [tf2_echo]: Waiting for transform base_link ->  sensor_kit_base_link: Invalid frame ID \"base_link\" passed to canTransform argument target_frame - frame does not exist\nAt time 0.0\n- Translation: [0.900, 0.000, 2.000]\n- Rotation: in Quaternion [-0.000, 0.008, -0.018, 1.000]\n- Rotation: in RPY (radian) [-0.001, 0.015, -0.036]\n- Rotation: in RPY (degree) [-0.057, 0.859, -2.086]\n- Matrix:\n0.999  0.036  0.015  0.900\n-0.036  0.999  0.000  0.000\n-0.015 -0.001  1.000  2.000\n0.000  0.000  0.000  1.000\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-one-sensor-link","title":"Add one sensor link","text":"

    Note

    In this step we will only add one sensor link. You will have to repeat this step for every sensor you want to add to your Vehicle.

    Let's say we want to add a LiDAR that is facing right.

    We have the following configuration files.

    base_link:\n    sensor_kit_base_link:\n        x: 0.9\n        y: 0.0\n        z: 2.0\n        roll: -0.001\n        pitch: 0.015\n        yaw: -0.0364\n
    sensor_kit_base_link:\n    velodyne_right_base_link:\n        x: 0.0\n        y: -0.56362\n        z: -0.30555\n        roll: -0.01\n        pitch: 0.71\n        yaw: -1.580\n

    We can clearly see the structure of transformation tree. The transformations are as follows.

    base_link -> sensor_kit_base_link -> velodyne_right_base_link\n

    We need to start adding these transformation from the root of the tree. We will start with the sensor_kit_base_link, as the base_link already exists in our tree.

    1. The first step is to add an Object named the same as the transformation frame (sensor_kit_base_link).

    2. Next we have to convert the transformation from ROS standard to the Unity standard. This is done with the formulas show in this section.

      The result of conversion of the coordinate systems and units is shown below.

      Position:\n(0.9, 0.0, 2.0)             ->  (0.0, 2.0, 0.9)\nRotation:\n(-0.001, 0.015, -0.0364)    ->  (0.8594, 2.0856, 0.0573)\n

      The resulting sensor_kit_base_link Object transformation is shown below.

    Now the same has to be done with the velodyne_right_base_link.

    1. Add transformation Object (velodyne_right_base_link).

      Info

      Remember to correctly set the child Object, in this case we use sensor_kit_base_link as a child, because this is what the .yaml file says.

    2. Convert the transformation into Unity coordinate system.

      The correct transformation is shown below.

      Position:\n(0, -0.56362, -0.30555)     ->  (0.56362, -0.30555, 0)\nRotation:\n(-0.01, 0.71, -1.580)       ->  (40.68, 90.5273, 0.573)\n

      The final velodyne_right_base_link Object transformation is shown below.

    Success

    If you have done everything right, after adding all of the sensor links your URDF Object tree should look something like the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-sensors","title":"Add sensors","text":"

    After adding links for all sensors you need to add the actual sensors into your Vehicle.

    Sensor position

    Please keep in mind, that we have created the sensor links in order to have an accurate transformations for all of the sensors. This implies that the Sensor Object itself can not have any transformation.

    If one of your Sensors, after adding it to the scene, is mispositioned, check whether the transformation is set to identity (position and rotation are zeros).

    When adding sensors almost all of them will have some common fields.

    • Frame Id

      Frame Id is the name of frame of reference against which the received data will be interpreted by the autonomous driving software stack.

      Remember that the Frame Id must exist internally in the ROS transformations tree.

    • Topics

      Topics are names of broadcasting channels. You can set the names of topics as you like and the data from sensors will be broadcasted on these topics.

      Remember to configure your receiving end to listen on the same topics as broadcasting ones.

    • Quality Of Service settings (QOS settings)

      Quality of service settings allow you to configure the behavior of the source node while broadcasting the sensor data. You can adjust these settings to suit your needs.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-vehicle-status-sensor","title":"Add a Vehicle Status Sensor","text":"

    To add a Vehicle Status Sensor to your Vehicle simply locate the following directory in the Project view and drag a prefab of this Sensor into the URDF Object.

    Assets/AWSIM/Prefabs/Sensors\n

    Next in the Inspector View select your Vehicle.

    ROS message example

    In this example you can see what a valid message from the Vehicle Status Sensor can look like.

    $ ros2 topic echo --once /vehicle/status/velocity_status\nheader:\n  stamp:\n    sec: 17\n    nanosec: 709999604\n  frame_id: base_link\nlongitudinal_velocity: 0.004912620410323143\nlateral_velocity: -0.005416259169578552\nheading_rate: 0.006338323466479778\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-lidar","title":"Add a LiDAR","text":"

    Scene Manager

    Before continuing with this tutorial please check out a dedicated one focused on Scene Manager.

    To add a LiDAR to your Vehicle you will have to drag a model of the LiDAR to the link tree you have created in the earlier step.

    You can use the predefined RGL LiDAR models or any other LiDAR models. In this tutorial we will be using RGL VelodyneVLP16 LiDAR model.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors/RobotecGPULidars\n

    LiDAR noise configuration

    LiDAR Sensor in simulation is returning a perfect result data. This is not an accurate representation of the real-world.

    LiDAR Sensor addresses this issue by applying a simulated noise to the output data. You can configure the noise parameters in the Inspector View under Configuration -> Noise Params fields.

    You can optionally remove the noise simulation by unchecking the Apply Distance/Angular Gaussian Noise.

    You can also change the ranges of the LiDAR detection.

    There is also a possibility to configure the visualization of the Point Cloud generated by the LiDAR. E.g. change the hit-point shape and size.

    ROS message example

    In this example you can see what a valid message from the LiDAR Sensor can look like.

    $ ros2 topic echo --once /lidar/pointcloud\nheader:\n  stamp:\n    sec: 20\n    nanosec: 589999539\n  frame_id: world\nheight: 1\nwidth: 14603\nfields:\n- name: x\n  offset: 0\n  datatype: 7\n  count: 1\n- name: y\n  offset: 4\n  datatype: 7\n  count: 1\n- name: z\n  offset: 8\n  datatype: 7\n  count: 1\n- name: intensity\n  offset: 16\n  datatype: 7\n  count: 1\n- name: ring\n  offset: 20\n  datatype: 4\n  count: 1\nis_bigendian: false\npoint_step: 24\nrow_step: 350472\ndata:\n- 156\n- 218\n- 183\n- 62\n- 0\n- 189\n- 167\n- 187\n- 32\n- 58\n- 173\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 1\n- 0\n- 0\n- 0\n- 198\n- 129\n- 28\n- 63\n- 0\n- 6\n- 230\n- 58\n- 128\n- 184\n- 93\n- 61\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 9\n- 0\n- 0\n- 0\n- 92\n- 2\n- 194\n- 62\n- 0\n- 141\n- 42\n- 187\n- 128\n- 89\n- 139\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 2\n- 0\n- 0\n- 0\n- 187\n- 168\n- 42\n- 63\n- 0\n- 159\n- 175\n- 59\n- 160\n- 243\n- 185\n- 61\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 10\n- 0\n- 0\n- 0\n- 119\n- 186\n- 204\n- 62\n- 0\n- 254\n- 23\n- 59\n- 128\n- 143\n- 41\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 3\n- 0\n- 0\n- 0\n- 65\n- 241\n- 59\n- 63\n- 128\n- 0\n- 252\n- 187\n- '...'\nis_dense: true\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-an-imu","title":"Add an IMU","text":"

    To add an IMU to your Vehicle you will have to drag a model of the IMU to the link tree you have created in the earlier step.

    You can use the provided or your own IMU Sensor. In this tutorial we will be using IMU Sensor provided with AWSIM.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the IMU Sensor can look like.

    $ ros2 topic echo --once /sensing/imu/tamagawa/imu_raw\nheader:\n  stamp:\n    sec: 20\n    nanosec: 589999539\n  frame_id: tamagawa/imu_link\norientation:\n  x: 0.0\n  y: 0.0\n  z: 0.0\n  w: 1.0\norientation_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\nangular_velocity:\n  x: 0.014335081912577152\n  y: 0.008947336114943027\n  z: -0.008393825963139534\nangular_velocity_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\nlinear_acceleration:\n  x: 0.006333829835057259\n  y: -0.005533283110707998\n  z: -0.0018753920448943973\nlinear_acceleration_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-gnss","title":"Add a GNSS","text":"

    To add a GNSS Sensor to your Vehicle you will have to drag a model of the GNSS to the link tree you have created in the earlier step.

    You can use the provided or your own GNSS Sensor. In this tutorial we will be using GNSS Sensor provided with AWSIM.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the GNSS Sensor can look like.

    $ ros2 topic echo --once /sensing/gnss/pose\nheader:\n  stamp:\n    sec: 8\n    nanosec: 989999799\n  frame_id: gnss_link\npose:\n  position:\n    x: 81656.765625\n    y: 50137.5859375\n    z: 44.60169219970703\n  orientation:\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 0.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-camera","title":"Add a Camera","text":"

    To add a Camera Sensor to your Vehicle you will have to drag a model of the Camera to the link tree you have created in the earlier step.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    You can configure some aspects of the Camera to your liking.

    E.g. you can set the field of view (fov) of the camera by changing the Field of View field or manipulating the physical camera parameters like Focal Length.

    The important thing is to configure the Camera Sensor Script correctly.

    Always check whether the correct Camera Object is selected and make sure that Distortion Shader and Ros Image Shader are selected.

    Example Camera Sensor Script configuration

    You can add the live Camera preview onto the Scene. To do this select the Show checkbox. Additionally you can change how the preview is displayed. Change the Scale value to control the size of the preview (how many times smaller the preview will be compared to the actual screen size).

    Move the preview on the screen by changing the X Axis and Y Axis values on the Image On Gui section.

    Camera preview example

    Testing camera with traffic light recognition

    You can test the Camera Sensor traffic light recognition by positioning the vehicle on the Unity Scene in such a way that on the Camera preview you can see the traffic lights.

    Remember to lock the Inspector view on Camera Object before dragging the whole Vehicle - this way you can see the preview while moving the vehicle.

    Run the Scene the same as on this page.

    Launch only the Autoware like on this page.

    By default you should see the preview of traffic light recognition visualization in the bottom left corner of Autoware.

    Traffic lights recognition example in Autoware

    ROS message example

    In this example you can see what a valid message from the Camera Sensor can look like.

    $ ros2 topic echo --once /sensing/camera/traffic_light/image_raw\nheader:\n  stamp:\n    sec: 14\n    nanosec: 619999673\n  frame_id: traffic_light_left_camera/camera_optical_link\nheight: 1080\nwidth: 1920\nencoding: bgr8\nis_bigendian: 0\nstep: 5760\ndata:\n- 145\n- 126\n- 106\n- 145\n- 126\n- 106\n- 145\n- 126\n- 106\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- '...'\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-pose-sensor","title":"Add a Pose Sensor","text":"

    To add a Pose Sensor to your Vehicle simply locate the following directory in the Project view and drag a prefab of this Sensor into the base_link Object.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the Pose Sensor can look like.

    $ ros2 topic echo --once /awsim/ground_truth/vehicle/pose\nheader:\n  stamp:\n    sec: 5\n    nanosec: 389999879\n  frame_id: base_link\npose:\n  position:\n    x: 81655.7578125\n    y: 50137.3515625\n    z: 42.8094367980957\n  orientation:\n    x: -0.03631274029612541\n    y: 0.0392342209815979\n    z: 0.02319677732884884\n    w: 0.9983005523681641\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#test-a-sensor","title":"Test a Sensor","text":"

    You can test whether the Sensor works correctly in several ways.

    1. Check whether the configuration is correct.

      In terminal source ROS with the following line (only if you haven't done so already).

      source /opt/ros/humble/setup.bash\n

      Check the details about the topic that your Sensor is broadcasting to with the following command.

      ros2 topic info -v <topic_name>\n

      Example

      In this example we can see that the message is broadcasted by AWSIM and nobody is listening. We can also examine the Quality of Service settings.

      $ ros2 topic info -v /awsim/ground_truth/vehicle/pose\nType: geometry_msgs/msg/PoseStamped\n\nPublisher count: 1\n\nNode name: AWSIM\nNode namespace: /\nTopic type: geometry_msgs/msg/PoseStamped\nEndpoint type: PUBLISHER\nGID: 01.10.13.11.98.7a.b1.2a.ee.a3.5a.11.00.00.07.03.00.00.00.00.00.00.00.00\nQoS profile:\n  Reliability: RELIABLE\n  History (Depth): KEEP_LAST (1)\n  Durability: VOLATILE\n  Lifespan: Infinite\n  Deadline: Infinite\n  Liveliness: AUTOMATIC\n  Liveliness lease duration: Infinite\n\nSubscription count: 0\n

    2. Check whether correct information is broadcasted.

      In terminal source ROS with the following line (only if you haven't done so already).

      source /opt/ros/humble/setup.bash\n

      View one transmitted message.

      ros2 topic echo --once <topic_name>\n

      Example

      In this example we can see the Vehicles location at the moment of executing the command.

      NOTE: The position and orientation are relative to the frame in the header/frame_id field (base_link in this example).

      $ ros2 topic echo --once /awsim/ground_truth/vehicle/pose\nheader:\n  stamp:\n    sec: 46\n    nanosec: 959998950\n  frame_id: base_link\npose:\n  position:\n    x: 81655.7265625\n    y: 50137.4296875\n    z: 42.53997802734375\n  orientation:\n    x: 0.0\n    y: -9.313260163068549e-10\n    z: -6.36646204504876e-12\n    w: 1.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/","title":"Add Visual Elements","text":"

    Your EgoVehicle needs many individual visual parts. Below we will add all needed visual elements.

    First in EgoVehicle Object add a child Object called Models.

    Inside Models Object we will add all visual models of our EgoVehicle.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-a-body","title":"Add a Body","text":"

    First you will need to add a Body of your Vehicle. It will contain many parts, so first lets create a Body parent Object.

    Next we will need to add Car Body

    1. Add a child Object BodyCar to the Body Object.

    2. To the BodyCar Object add a Mesh Filter.

      Click on the 'Add Component' button, search for Mesh Filter and select it. Next search for mesh of your vehicle and select it in the Mesh field.

    3. To the BodyCar Object add a Mesh Renderer.

      Click on the 'Add Component' button, search for Mesh Filter and select it

    4. Specify Materials.

      You need to specify what materials will be used for rendering your EgoVehicle model. Do this by adding elements to the Materials list and selecting the materials you wish to use as shown below.

      Add as many materials as your model has sub-meshes.

      Tip

      When you add too many materials, meaning there will be no sub-meshes to apply these materials to, you will see this warning. In such a case please remove materials until this warning disappears.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-interactive-body-parts","title":"Add interactive Body parts","text":"

    In this step we will add the following parts

    • Break light
    • Reverse Light
    • Right Turn Signal
    • Left Turn Signal
    • (optional) other visual elements required specifically by your Vehicle.

    Info

    It may seem like all of the elements above can be parts of the Body mesh, but it is important for these parts to be separate, because we need to be able to make them interactive (e.g. flashing turn signals).

    Other good reason for having different meshes for Vehicle parts is that you have a Vehicle model, but for the simulation you need to add e.g. a roof rack with sensors - which can be achieved by adding more meshes.

    Note

    We will illustrate this step only for Break Light, but you should repeat this step of the tutorial for each element of the list above.

    1. Add a child Object to the Body Object.

    2. Add a Mesh Filter and select the mesh (the same as in section before).

    3. Add a Mesh Renderer and select the materials (the same as in section before).

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-wheels","title":"Add Wheels","text":"

    In this step we will add individual visuals for every wheel. This process is very similar to the one before.

    1. Add a child Object to the Models Object called WheelVisuals.

    Note

    In this tutorial we will add only one wheel, but you should repeat the step for all 4 wheels. That is, follow the instructions that follow this message for every wheel your Vehicle has.

    • Front Left Wheel
    • Front Right Wheel
    • Rear Left Wheel
    • Rear Right Wheel

    1. Add a child Object to the WheelVisuals Object called FrontLeftWheel.

    2. Add a child Object to the FrontLeftWheel Object called WheelFrontL. This Object will contain the actual wheel part.

    3. Add a Mesh Filter and select the wheel mesh.

    4. Add a Mesh Renderer and select the wheel materials.

    5. Repeat the steps before to add Breaks.

      The same way you have added the WheelFrontL Object now add the WheelFrontLBreaks. Naturally you will have to adjust the mesh and materials used as they will be different for breaks than for the wheel.

      Your final break configuration should look similar to the one following.

    6. Set the FrontLeftWheel parent Object transformation to position the wheel in correct place.

    Successful configuration

    If you have done everything right your WheelVisuals Object should look similar to the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#move-the-models","title":"Move the models","text":"

    The last step to correctly configure Vehicle models is to shift them so that the EgoVehicle origin is in the center of fixed axis.

    This means you need to shift the whole Models Object accordingly (change the position fields in transformation).

    Tip

    Add a dummy Object as a child to the EgoVehicle Object (the same as in steps before) so it is located in the origin of the EgoVehicle.

    Now move Models around relative to the dummy - change position in the Inspector view. The dummy will help you see when the fixed axis (in case of the Lexus from example it is the rear axis) is aligned with origin of EgoVehicle.

    In the end delete the dummy Object as it is no longer needed.

    "},{"location":"Components/Vehicle/CustomizeSlip/","title":"Customize Slip","text":""},{"location":"Components/Vehicle/CustomizeSlip/#customize-slip","title":"Customize slip","text":"

    By attaching a GroundSlipMutiplier.cs script to a collider (trigger), you can change the slip of the vehicle within the range of that collider.

    "},{"location":"Components/Vehicle/CustomizeSlip/#sample-scene","title":"Sample scene","text":"

    Assets\\AWSIM\\Scenes\\Samples\\VehicleSlipSample.unity

    "},{"location":"Components/Vehicle/CustomizeSlip/#how-to-setup","title":"How to setup","text":"
    1. Create collider
    2. Check IsTrigger
    3. Change properties of FowardSlip and SidewaySlip.
    "},{"location":"Components/Vehicle/DynamicSensorPlacement/","title":"Dynamic Sensor Placement","text":""},{"location":"Components/Vehicle/DynamicSensorPlacement/#dynamic-sensor-placement","title":"Dynamic Sensor Placement","text":"

    This tool allows you to dynamically place sensors on a car using positions and rotations specified in a URDF file.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#follow-the-steps-to-generate-the-urdf-file","title":"Follow the steps to generate the urdf file:","text":"

    1. Build Autoware by following the instruction in https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/.

    2. Modify L3-4 in $HOME/autoware/src/universe/autoware.universe/launch/tier4_vehicle_launch/urdf/vehicle.xacro as the following,

          <xacro:arg name=\"vehicle_model\" default=\"sample_vehicle\"/>\n    <xacro:arg name=\"sensor_model\" default=\"awsim_sensor_kit\"/>\n

    3. Run the following commands:

      source $HOME/autoware/install/setup.bash\n\nros2 run xacro xacro -o awsim_vehicle.urdf $HOME/autoware/src/universe/autoware.universe/launch/tier4_vehicle_launch/urdf/vehicle.xacro\n

    4. You should now have a URDF file named awsim_vehicle.urdf.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#using-the-dynamic-sensor-placement-tool","title":"Using the Dynamic Sensor Placement tool:","text":"

    1. Open up AWSIM and place the generated awsim_vehicle.urdf in the Externals folder so the path will be ./Assets/AWSIM/Externals/awsim_vehicle.urdf.

    2. Now, under open up the Dynamic sensor placement tool under AWSIM menu.

    3. Enter the path to the URDF file

    4. Click \"Place sensors\". All the sensors should be automatically placed on the car.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#note","title":"Note","text":"

    1. Only the game object named sensor_kit_base_link and its direct children will be assigned transforms if they are mentioned in the URDF file as children of sensor_kit_base_link. You will need to manually place the base_link game object.

    2. Ensure the names of the game objects are exactly the same as those mentioned in the URDF file. Look for the name of the child of sensor_kit_base_link in the URDF file under the <joint> tag.

      For example:

      <joint name=\"velodyne_top_base_mount_joint\" type=\"fixed\">\n    <origin rpy=\"0.0 0.0 1.575\" xyz=\"0.0 0.0 0.0\"/>\n    <parent link=\"sensor_kit_base_link\"/>\n    <child link=\"velodyne_top_base_link\"/>\n</joint>\n

    3. Finally, ensure that all the direct children of the sensor game objects have their rotations and positions set to zero.

    "},{"location":"Components/Vehicle/EgoVehicle/","title":"Ego Vehicle","text":""},{"location":"Components/Vehicle/EgoVehicle/#introduction","title":"Introduction","text":"

    EgoVehicle is a playable object that simulates a vehicle that can autonomously move around the scene. It has components (scripts) that make it possible to control it by keyboard or by Autoware (using ROS2 communication). Moreover, it provides sensory data needed for self-localization in space and detection of objects in the surrounding environment.

    The default prefab EgoVehicle was developed using a Lexus RX450h 2015 vehicle model with a configured sample sensor kit.

    Own EgoVehicle prefab

    If you would like to develop your own EgoVehicle prefab, we encourage you to read this tutorial.

    "},{"location":"Components/Vehicle/EgoVehicle/#supported-features","title":"Supported features","text":"

    This vehicle model was created for Autoware simulation, and assuming that Autoware has already created a gas pedal map, this vehicle model uses acceleration as an input value. It has the following features:

    • Longitudinal control by acceleration (\\(\\frac{m}{s^2}\\)).
    • Lateral control by two-wheel model.
    • Yaw, roll and pitch controlled by Physics engine.
    • Mass-spring-damper suspension model (WheelColliders).
    • Logical, not mechanical, automatic gears change.
    • 3D Mesh (*.fbx) as road surface for vehicle driving, gradient resistance.

    AutowareSimulation

    If you would like to see how EgoVehicle works or run some tests, we encourage you to familiarize yourself with the AutowareSimulation scene described in this section.

    "},{"location":"Components/Vehicle/EgoVehicle/#lexus-rx450h-2015-parameters","title":"Lexus RX450h 2015 parameters","text":"Parameter Value Unit Mass \\(1500\\) \\(kg\\) Wheel base \\(2.5\\) \\(m\\) Tread width \\(Ft = 1.8; Rr = 1.8\\) \\(m\\) Center of Mass position \\(x = 0; y = 0.5; z = 0\\) \\(m\\) Moment of inertia \\(\\mathrm{yaw} = 2000; \\mathrm{roll} = 2000; \\mathrm{pitch} = 700\\) \\(kg \\cdot m^2\\) Spring rate \\(Ft = 55000; Rr = 48000\\) \\(N\\) Damper rate \\(Ft = 3000; Rr = 2500\\) \\(\\frac{N}{s}\\) Suspension stroke \\(Ft = 0.2; Rr = 0.2\\) \\(m\\) Wheel radius \\(0.365\\) \\(m\\)

    Vehicle inertia

    In general, measuring the moment of inertia is not easy, and past papers published by NHTSA are helpful. Measured Vehicle Inertial Parameters - NHTSA 1998

    "},{"location":"Components/Vehicle/EgoVehicle/#prefab-and-fbx","title":"Prefab and Fbx","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Vehicles/Lexus RX450h 2015 Sample Sensor.prefab\n

    EgoVehicle name

    In order to standardize the documentation, the name EgoVehicle will be used in this section as the equivalent of the prefab named Lexus RX450h 2015 2015 Sample Sensor.

    EgoVehicle prefab has the following content:

    As you can see, it consists of 3 parents for GameObjects:

    • Models - aggregating visual elements,
    • Colliders - aggregating colliders,
    • URDF - aggregating sensors,
    • and 2 single GameObjects: CoM and Reflection Probe.

    All objects are described in the sections below.

    "},{"location":"Components/Vehicle/EgoVehicle/#visual-elements","title":"Visual elements","text":"

    Prefab is developed using models available in the form of *.fbx files. The visuals elements have been loaded from the appropriate *.fbx file and are aggregated and added in object Models.

    *.fbx file for Lexus RX450h 2015 is located under the following path:

    Assets/AWSIM/Models/Vehicles/Lexus RX450h 2015.fbx\n

    Models object has the following content:

    As you can see, the additional visual element is XX1 Sensor Kit.

    It was also loaded from the *.fbx file which can be found under the following path:

    Assets/AWSIM/Models/Sensors/XX1 Sensor Kit.fbx\n

    Lexus RX450h 2015.fbx

    The content of a sample *.fbx file is presented below, all elements except Collider have been added to the prefab as visual elements of the vehicle. Collider is used as the Mesh source for the Mesh Collider in the BodyCollider object.

    "},{"location":"Components/Vehicle/EgoVehicle/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The default scene contains a single Lexus RX450h 2015 Sample Sensor prefab that is added as a child of the EgoVehicle GameObject.

    In EgoVehicle prefab, the local coordinate system of the vehicle (main prefab link) should be defined in the axis of the rear wheels projected onto the ground - in the middle of the distance between them. This aspect holds significance when characterizing the dynamics of the object, as it provides convenience in terms of describing its motion and control.

    "},{"location":"Components/Vehicle/EgoVehicle/#components","title":"Components","text":"

    There are several components responsible for the full functionality of Vehicle:

    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • Vehicle (script) - provides the ability to set the acceleration of the vehicle and the steering angle of its wheels.
    • Vehicle Keyboard Input (script) - provides the ability to set inputs in the Vehicle (script) via the keyboard.
    • Vehicle Ros Input (script) - provides the ability to set inputs in the Vehicle (script) via subscribed ROS2 topics (outputs from Autoware).
    • Vehicle Visual Effect - provides the ability to simulate vehicle lights, such as turn signals, brake lights, and hazard light.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Vehicles/*\n
    "},{"location":"Components/Vehicle/EgoVehicle/#architecture","title":"Architecture","text":"

    The EgoVehicle architecture - with dependencies - is presented on the following diagram.

    The communication between EgoVehicle components is presented on two different diagrams - a flow diagram and a sequence diagram.

    The flow diagram presents a flow of information between the EgoVehicle components.

    The sequence diagram provides a deeper insight in how the communication is structured and what are the steps taken by each component. Some tasks performed by the elements are presented for clarification.

    Sequence diagram

    Please keep in mind, that Autoware message callbacks and the update loop present on the sequence diagram are executed independently and concurrently. One thing they have in common are resources - the Vehicle (script).

    "},{"location":"Components/Vehicle/EgoVehicle/#com","title":"CoM","text":"

    CoM (Center of Mass) is an additional link that is defined to set the center of mass in the Rigidbody. The Vehicle (script) is responsible for its assignment. This measure should be defined in accordance with reality. Most often, the center of mass of the vehicle is located in its center, at the height of its wheel axis - as shown below.

    "},{"location":"Components/Vehicle/EgoVehicle/#colliders","title":"Colliders","text":"

    Colliders are used to ensure collision between objects. In EgoVehicle, the main Collider collider and colliders in Wheels GameObject for each wheel were added.

    Colliders object has the following content:

    "},{"location":"Components/Vehicle/EgoVehicle/#bodycollider","title":"BodyCollider","text":"

    Collider is a vehicle object responsible for ensuring collision with other objects. Additionally, it can be used to detect these collisions. The MeshCollider takes a Mesh of object and builds its Collider based on it. The Mesh for the Collider was also loaded from the *.fbx file similarly to the visual elements.

    "},{"location":"Components/Vehicle/EgoVehicle/#wheels-colliders","title":"Wheels Colliders","text":"

    WheelsColliders are an essential elements from the point of view of driving vehicles on the road. They are the only ones that have contact with the roads and it is important that they are properly configured. Each vehicle, apart from the visual elements related to the wheels, should also have 4 colliders - one for each wheel.

    Wheel (script) provides a reference to the collider and visual object for the particular wheel. Thanks to this, the Vehicle (script) has the ability to perform certain actions on each of the wheels, such as:

    • update the steering angle in WheelCollider,
    • update the visual part of the wheel depending on the speed and angle of the turn,
    • update the wheel contact information stored in the WheelHit object,
    • update the force exerted by the tire forward and sideways depending on the acceleration (including cancellation of skidding),
    • ensure setting the tire sleep (it is impossible to put Rigidbody to sleep, but putting all wheels to sleep allows to get closer to this effect).

    Wheel Collider Config (script) has been developed to prevent inspector entry for WheelCollider which ensures that friction is set to 0 and only wheel suspension and collisions are enabled.

    Wheel Collider Config

    For a better understanding of the meaning of WheelCollider we encourage you to read this manual.

    "},{"location":"Components/Vehicle/EgoVehicle/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. The Mass of the vehicle should approximate its actual weight. In order for the vehicle to physically interact with other objects - react to collisions, Is Kinematic must be turned off. The Use Gravity should be turned on - to ensure the correct behavior of the body during movement. In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Vehicle/EgoVehicle/#reflection-probe","title":"Reflection Probe","text":"

    Reflection Probe is added to EgoVehicle prefab to simulate realistic reflections in a scene. It is a component that captures and stores information about the surrounding environment and uses that information to generate accurate reflections on objects in real-time. The values in the component are set as default.

    HD Additional Reflection Data (script) is additional component used to store settings for HDRP's reflection probes and is added automatically.

    "},{"location":"Components/Vehicle/EgoVehicle/#urdf-and-sensors","title":"URDF and Sensors","text":"

    URDF (Unified Robot Description Format) is equivalent to the simplified URDF format used in ROS2. This format allows to define the positions of all sensors of the vehicle in relation to its local coordinate system. URDF is built using multiple GameObjects as children appropriately transformed with relation to its parent.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-script","title":"Vehicle (script)","text":"

    Vehicle (script) provides an inputs that allows the EgoVehicle to move. Script inputs provides the ability to set the acceleration of the vehicle and the steering angle of its wheels, taking into account the effects of suspension and gravity. It also provides an input to set the gear in the gearbox and to control the turn signals. Script inputs can be set by one of the following scripts: Vehicle Ros Input (script) or Vehicle Keyboard Input (script).

    The script performs several steps periodically:

    • checks whether the current inputs meet the set limits and adjusts them within them,
    • calculates the current linear velocity, angular velocity vector and local acceleration vector,
    • set the current steering angle in the script for each wheel and perform their updates,
    • if the current gear is PARKING and the vehicle is stopped (its speed and acceleration are below the set thresholds), it puts the vehicle (Rigidbody) and its wheels (Wheel (script)) to sleep,
    • if the vehicle has not been put to sleep, it sets the current acceleration to each with the appropriate sign depending on the DRIVE and REVERSE gear.
    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"

    The script uses the CoM link reference to assign the center of mass of the vehicle to the Rigidbody. In addiction, Use inertia allows to define the inertia tensor for component Rigidbody - by default it is disabled.

    Physics Settings - allows to set values used to control vehicle physics:

    • Sleep Velocity Threshold - velocity threshold used to put vehicle to sleep,
    • Sleep Time Threshold - time threshold for which the vehicle must not exceed the Sleep Velocity Threshold, have contact with the ground and a set acceleration input equal to zero,
    • Skidding Cancel Rate - coefficient that determines the rate at which skidding is canceled, affects the anti-skid force of the wheels - the higher the value, the faster the cancellation of the skid.

    Axles Settings contains references to (Wheel (script)) scripts to control each wheel. Thanks to them, the Vehicle (script) is able to set their steering angle and accelerations.

    Input Settings - allows to set limits for values on script input:

    • Max Steer Angle Input - maximum value of acceleration set by the script (also negative),
    • Max Acceleration Input - maximum steering angle of the wheels set by the script (also negative).

    Inputs - are only used as a preview of the currently set values in the script input:

    "},{"location":"Components/Vehicle/EgoVehicle/#input-data","title":"Input Data","text":"Category Type Description AccelerationInput float Acceleration input (m/s^2). On the plane, output the force that will result in this acceleration. On a slope, it is affected by the slope resistance, so it does not match the input. SteerAngleInput float Vehicle steering input (degree). Negative steers left, positive right AutomaticShiftInput enumeration Vehicle gear shift input (AT).Values: PARKING, REVERSE, NEUTRAL, DRIVE. SignalInput enumeration Vehicle turn signal input.Values: NONE, LEFT, RIGHT, HAZARD."},{"location":"Components/Vehicle/EgoVehicle/#output-data","title":"Output data","text":"Category Type Description LocalAcceleration Vector3 Acceleration(m/s^2) in the local coordinate system of the vehicle Speed float Vehicle speed (m/s). SteerAngle float Vehicle steering angle (degree). Signal enumeration Vehicle turn signal. Velocity Vector3 Vehicle velocity (m/s) LocalVelocity Vector3 Vehicle local velocity (m/s) AngularVelocity Vector3 Vehicle angular velocity (rad/s)

    The acceleration or deceleration of the vehicle is determined by AutomaticShiftInput and AccelerationInput. The vehicle will not move in the opposite direction of the (DRIVE or REVERSE) input.

    Example

    Sample vehicle behaves:

    • Sample 1 - vehicle will accelerate with input values (gradient resistance is received).

      AutomaticShiftInput = DRIVE\nSpeed = Any value\nAccelerationInput > 0\n

    • Sample 2 - vehicle will decelerate (like a brake).

      AutomaticShiftInput = DRIVE\nSpeed > 0\nAccelerationInput < 0\n

    • Sample 3 - vehicle will continuously stop.

      AutomaticShiftInput = DRIVE\nSpeed <= 0\nAccelerationInput < 0\n
    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-ros-script","title":"Vehicle Ros (script)","text":"

    Vehicle Ros (script) is responsible for subscribing to messages that are vehicle control commands. The values read from the message are set on the inputs of the Vehicle (script) script.

    The concept for vehicle dynamics is suitable for Autoware's autoware_control_msgs/Control and autoware_vehicle_msgs/GearCommand messages interface usage. The script sets gear, steering angle of wheels and acceleration of the vehicle (read from the aforementioned messages) to the Vehicle (script) input. In the case of VehicleEmergencyStamped message it sets the absolute acceleration equal to 0. In addition, also through Vehicle (script), the appropriate lights are turned on and off depending on TurnIndicatorsCommand and HazardLightsCommand messages.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • * Command Topic - topic on which suitable type of information is subscribed (default: listed in the table below)
    • QoS- Quality of service profile used in the publication (default assumed as \"system_default\": Reliable, TransientLocal, Keep last/1)
    • Vehicle - reference to a script in the vehicle object where the subscribed values are to be set (default: None)
    "},{"location":"Components/Vehicle/EgoVehicle/#subscribed-topics","title":"Subscribed Topics","text":"
    • QoS: Reliable, TransientLocal, KeepLast/1
    Category Topic Message type Frequency (Autoware dependent) TurnIndicatorsCommand /control/command/turn_indicators_cmd autoware_vehicle_msgs/TurnIndicatorsCommand 10 HazardLightsCommand /control/command/hazard_lights_cmd autoware_vehicle_msgs/HazardLightsCommand 10 AckermannControlCommand /control/command/control_cmd autoware_control_msgs/Control 60 GearCommand /control/command/gear_cmd autoware_vehicle_msgs/GearCommand 10 VehicleEmergencyStamped /control/command/emergency_cmd tier4_vehicle_msgs/msg/VehicleEmergencyStamped 60

    ROS2 Topics

    If you would like to know all the topics used in communication Autoware with AWSIM, we encourage you to familiarize yourself with this section

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-keyboard-script","title":"Vehicle Keyboard (script)","text":"

    Vehicle Keyboard (script) allows EgoVehicle to be controlled by the keyboard. Thanks to this, it is possible to switch on the appropriate gear of the gearbox, turn the lights on/off, set the acceleration and steering of the wheels. It's all set in the Vehicle (script) of the object assigned in the Vehicle field. The table below shows the available control options.

    Button Option d Switch to move forward (drive gear) r Switch to move backwards (reverse gear) n Switch to neutral p Switch to parking gear UP ARROW Forward acceleration DOWN ARROW Reverse acceleration (decelerate) LEFT/RIGHT ARROW Turning 1 Turn left blinker on (right off) 2 Turn right blinker on (left off) 3 Turn on hazard lights 4 Turn off blinker or hazard lights

    WASD

    Controlling the movement of the vehicle with WASD as the equivalent of arrow keys is acceptable, but remember that the d button engages the drive gear.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Max Acceleration- maximum value of acceleration set by the script (also negative)
    • Max Steer Angle - maximum steering angle of the wheels set by the script (also negative)

    Value limits

    Max Acceleration and Max Steer Angle values greater than those set in the Vehicle (script) are limited by the script itself - they will not be exceeded.

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-visual-effect-script","title":"Vehicle Visual Effect (script)","text":"

    This part of the settings is related to the configuration of the emission of materials when a specific lighting is activated. There are 4 types of lights: Brake, Left Turn Signal, Right Turn Signal and Reverse. Each of the lights has its visual equivalent in the form of a Mesh. In the case of EgoVehicle, each light type has its own GameObject which contains the Mesh assigned.

    For each type of light, the appropriate Material Index (equivalent of element index in mesh) and Lighting Color are assigned - yellow for Turn Signals, red for Break and white for Reverse.

    Lighting Intensity values are also configured - the greater the value, the more light will be emitted. This value is related to Lighting Exposure Weight parameter that is a exposure weight - the lower the value, the more light is emitted.

    All types of lighting are switched on and off depending on the values obtained from the Vehicle (script) of the vehicle, which is assigned in the Vehicle field.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_3","title":"Elements configurable from the editor level","text":"
    • Turn Signal Timer Interval Sec - time interval for flashing lights - value \\(0.5\\) means that the light will be on for \\(0.5s\\), then it will be turned off for \\(0.5s\\) and turned on again. (default: 0.5)
    "},{"location":"Components/Vehicle/FollowCamera/","title":"FollowCamera","text":""},{"location":"Components/Vehicle/FollowCamera/#introduction","title":"Introduction","text":"

    The FollowCamera component is designed to track a specified target object within the scene. It is attached to the main camera and maintains a defined distance and height from the target. Additionally, it offers the flexibility of custom rotation around the target as an optional feature.

    "},{"location":"Components/Vehicle/FollowCamera/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":""},{"location":"Components/Vehicle/FollowCamera/#required-member","title":"Required member","text":"
    • Target - the transform component of the tracked object
    "},{"location":"Components/Vehicle/FollowCamera/#base-setttings","title":"Base Setttings","text":"
    • Distance - base distance between the camera and the target object
    • Offset - lateral offset of the camera position
    • Height - base height of the camera above the target object
    • HeightMultiplier - camera height multiplier
    "},{"location":"Components/Vehicle/FollowCamera/#optional-movement-setttings","title":"Optional Movement Setttings","text":"
    • RotateAroundModeToggle - toggle key between rotate around mode and default follow mode
    • RotateAroundSensitivity - mouse movement sensitivity for camera rotation around the target
    • HeightAdjustmentSensitivity - mouse movement sensitivity for camera height adjustment
    • ZoomSensitivity - mouse scroll wheel sensitivity for camera zoom
    • InvertHorzAxis - invert horizontal mouse movement
    • InvertVertAxis - invert vertical mouse movement
    • InvertScrollWheel - invert mouse scroll wheel
    • MaxHeight - maximum value of camera height
    • MinDistance - minimum value of camera distance to target object
    • MaxDistance - maximum value of camera distance to target object
    "},{"location":"Components/Vehicle/FollowCamera/#rotate-around-mode","title":"Rotate Around Mode","text":"

    Camera rotation around the target can be activated by pressing the RotateAroundModeToggle key (default 'C' key). In this mode, the user can manually adjust the camera view at run-time using the mouse. To deactivate the Rotate Around mode, press the RotateAroundModeToggle key once more.

    In the Rotate Around Mode camera view can be controlled as follows:

    • hold left shift + mouse movement: to adjust the camera position,
    • hold left shift + mouse scroll wheel: to zoom in or out of the camera view,
    • left shift + left arrow: to set left camera view,
    • left shift + right arrow: to set right camera view,
    • left shift + up arrow: to set front camera view,
    • left shift + down arrow: to set back camera view.
    "},{"location":"Components/Vehicle/FollowCamera/#optional","title":"Optional","text":"

    An optional prefab featuring a UI panel, located at Assets/Prefabs/UI/MainCameraView.prefab, can be used to showcase a user guide. To integrate this prefab into the scene, drag and drop it beneath the Canvas object. This prefab displays instructions on how to adjust the camera view whenever the Rotate Around Mode is activated.

    "},{"location":"Components/Vehicle/URDFAndSensors/","title":"URDF And Sensors","text":""},{"location":"Components/Vehicle/URDFAndSensors/#urdf-and-sensors","title":"URDF and Sensors","text":"

    This section describes the placement of sensors in EgoVehicle on the example of a Lexus RX450h 2015 Sample Sensor prefab.

    URDF (Unified Robot Description Format) is equivalent to the simplified URDF format used in ROS2. This format allows to define the positions of all sensors of the vehicle in relation to its main parent prefab coordinate system.

    URDF is added directly to the main parent of the prefab and there are no transforms between these objects. It is built using multiple GameObjects as children appropriately transformed with relation to its parent.

    The transforms in the URDF object are defined using the data from the sensor kit documentation used in the vehicle. Such data can be obtained from sensor kit packages for Autoware, for example: awsim_sensor_kit_launch - it is used in the AWSIM compatible version of Autoware. This package contains a description of transforms between coordinate systems (frames) in the form of *.yaml files: sensors_calibration and sensor_kit_calibration.

    In the first file, the transform of the sensor kit frame (sensor_kit_base_link) relative to the local vehicle frame (base_link) is defined. In Unity, this transform is defined in the object Sensor Kit. While the second file contains a definition of the transformations of all sensors with respect to the sensor kit - they are described in the Sensor Kit subsections.

    Transformations

    Please note that the transformation Objects are intended to be a direct reflection of frames existing in ROS2. All frame Objects are defined as children of base_link and consist of nothing but a transformation - analogical to the one present in ROS2 (keep in mind the coordinate system conversion). The sensor Objects are added to the transformation Object with no transformation of their own.

    Coordinate system conventions

    Unity uses a left-handed convention for its coordinate system, while the ROS2 uses a right-handed convention. For this reason, you should remember to perform conversions to get the correct transforms.

    "},{"location":"Components/Vehicle/URDFAndSensors/#base-link","title":"Base Link","text":"

    Base Link (frame named base_link) is the formalized local coordinate system in URDF. All sensors that publish data specified in some frame present in Autoware are defined in relation to base_link. It is a standard practice in ROS, that base_link is a parent transformation of the whole robot and all robot parts are defined in some relation to the base_link.

    If any device publishes data in the base_link frame - it is added as a direct child, with no additional transformation intermediate Object (PoseSensor is an example). However, if this device has its own frame, it is added as a child to its frame Object - which provides an additional transformation. The final transformation can consist of many intermediate transformation Objects. The frame Objects are added to the base_link (GnssSensor and its parent gnss_link are an example).

    "},{"location":"Components/Vehicle/URDFAndSensors/#sensor-kit","title":"Sensor Kit","text":"

    Sensor Kit (frame named sensor_kit_base_link) is a set of objects that consists of all simulated sensors that are physically present in an autonomous vehicle and have their own coordinate system (frame). This set of sensors has its own frame sensor_kit_base_link that is relative to the base_link.

    In the Lexus RX450h 2015 Sample Sensor prefab, it is added to the base_link GameObject with an appropriately defined transformation. It acts as an intermediate frame GameObject. Sensor Kit is located on the top of the vehicle, so it is significantly shifted about the Oy and Oz axes. Sensors can be defined directly in this Object (VelodyneVLP16 is an example), or have their own transformation Object added on top of the sensor_kit_base_link (like GnssSensor mentioned in the base_link section).

    The sensors described in this subsection are defined in relation to the sensor_kit_base_link frame.

    "},{"location":"Components/Vehicle/URDFAndSensors/#lidars","title":"LiDARs","text":"

    LidarSensor is the component that simulates the LiDAR (Light Detection and Ranging) sensor. The LiDARs mounted on the top of autonomous vehicles are primarily used to scan the environment for localization in space and for detection and identification of obstacles. LiDARs placed on the left and right sides of the vehicle are mainly used to monitor the traffic lane and detect vehicles moving in adjacent lanes. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one VelodyneVLP16 prefab sensor configured on the top of the vehicle, mainly used for location in space, but also for object recognition. Since the top LiDAR publishes data directly in the sensor_kit_base_link frame, the prefab is added directly to it - there is no transform. The other two remaining LiDARs are defined, but disabled - they do not provide data from space (but you can enable them!).

    "},{"location":"Components/Vehicle/URDFAndSensors/#top","title":"Top","text":""},{"location":"Components/Vehicle/URDFAndSensors/#left-disabled","title":"Left - disabled","text":""},{"location":"Components/Vehicle/URDFAndSensors/#right-disabled","title":"Right - disabled","text":""},{"location":"Components/Vehicle/URDFAndSensors/#imu","title":"IMU","text":"

    IMUSensor is a component that simulates an IMU (Inertial Measurement Unit) sensor. It measures acceleration and angular velocity of the EgoVehicle. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor has one such sensor located on the top of the vehicle. It is added to an Object tamagawa/imu_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link. This transformation has no transition, but only rotation around the Oy and Oz axes. The transform is defined in such a way that its axis Oy points downwards - in accordance with the gravity vector.

    "},{"location":"Components/Vehicle/URDFAndSensors/#gnss","title":"GNSS","text":"

    GnssSensor is a component which simulates the position of vehicle computed by the Global Navigation Satellite. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one such sensor located on top of the vehicle. It is added to an Object gnss_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link. The frame is slightly moved back along the Oy and Oz axes.

    "},{"location":"Components/Vehicle/URDFAndSensors/#camera","title":"Camera","text":"

    CameraSensor is a component that simulates an RGB camera. Autonomous vehicles can be equipped with many cameras used for various purposes. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one camera, positioned on top of the vehicle in such a way that the cameras field of view provides an image including traffic lights - the status of which must be recognized by Autoware. It is added to an Object traffic_light_left_camera/camera_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link.

    "},{"location":"Components/Vehicle/URDFAndSensors/#pose","title":"Pose","text":"

    PoseSensor is a component which provides access to the current position and rotation of the EgoVehicle - is added as a ground truth.

    The position and orientation of EgoVehicle is defined as the position of the frame base_link in the global frame, so this Object is added directly as its child without a transform.

    "},{"location":"Components/Vehicle/URDFAndSensors/#vehiclesensor","title":"VehicleSensor","text":"

    VehicleStatusSensor is a component that is designed to aggregate information about the current state of the EgoVehicle, such as the active control mode, vehicle speed, steering of its wheels, or turn signal status. A detailed description of this sensor is available in this section.

    This Object is not strictly related to any frame, however, it is assumed as a sensor, therefore it is added to the URDF.

    "},{"location":"DeveloperGuide/Contact/","title":"Contact","text":""},{"location":"DeveloperGuide/Contact/#contact","title":"Contact","text":"

    English/\u65e5\u672c\u8a9e OK

    e-mail : takatoki.makino@tier4.jp

    twitter : https://twitter.com/mackierx111

    "},{"location":"DeveloperGuide/Documentation/","title":"Documentation","text":""},{"location":"DeveloperGuide/Documentation/#documentation","title":"Documentation","text":"

    This document uses Material for MkDocs.

    "},{"location":"DeveloperGuide/Documentation/#local-hosting","title":"Local hosting","text":"

    1 Install Material for MkDocs. 

    $ pip install mkdocs-material\n
    2 Hosting on localhost. 
    $ cd AWSIM\n$ mkdocs serve\nINFO     -  Building documentation...\nINFO     -  Cleaning site directory\nINFO     -  Documentation built in 0.16 seconds\nINFO     -  [03:13:22] Watching paths for changes: 'docs', 'mkdocs.yml'\nINFO     -  [03:13:22] Serving on http://127.0.0.1:8000/\n

    3 Access http://127.0.0.1:8000/ with a web browser.

    For further reference see Material for MkDocs - Getting started.

    "},{"location":"DeveloperGuide/Documentation/#mkdocs-files","title":"MkDocs files","text":"

    Use the following /docs directory and mkdocs.yml for new documentation files. 

    AWSIM\n\u251c\u2500 docs/                // markdown and image file for each document.\n\u2514\u2500 mkdocs.yml           // mkdocs config.\n
    Create one directory per document. For example, the directory structure of this \"Documentation\" page might look like this. 
    AWSIM\n\u2514\u2500 docs/                            // Root of all documents\n    \u2514\u2500 DeveloperGuide               // Category\n        \u2514\u2500 Documentation            // Root of each document\n            \u251c\u2500 index.md             // Markdown file\n            \u2514\u2500 image_0.png          // Images used in markdown file\n
    "},{"location":"DeveloperGuide/Documentation/#deploy-hosting","title":"Deploy & Hosting","text":"

    When docs are pushed to the main branch, they are deployed to GitHub Pages using GitHub Actions. See also Material for MkDocs - Publishing your site

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/","title":"Graphy Asset Setup","text":""},{"location":"DeveloperGuide/EditorSetup/Graphy/#graphy-asset-setup","title":"Graphy Asset Setup","text":""},{"location":"DeveloperGuide/EditorSetup/Graphy/#add-graphy-from-asset-store","title":"Add Graphy from Asset Store","text":"

    1) Go to Unity Asset Store and add Graphy to personal assets.

    Graphy Asset Store link:

    • https://assetstore.unity.com/packages/tools/gui/graphy-ultimate-fps-counter-stats-monitor-debugger-105778
    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#add-graphy-to-the-unity-editor","title":"Add Graphy to the Unity Editor","text":"

    1) Open up the Unity Editor. - Open up a temporary new scene by File -> New Scene -> Empty(Built-in) -> Create - This is due to a bug with Unity crashing on certain Linux configurations. - Once the package is imported, you can open up the desired scene. 2) Go to the Window menu and select Package Manager. 3) Make sure the My Assets tab is selected from the top left of the Package Manager window. 4) Find & select the Graphy from the list and click Download or Import from the bottom left of the Package Manager window. 5) There will be a popup window showing contents of the package. Click Import to add Graphy to the project.

    After the import is complete, you should be able to see Graphy prefab in the Hierarchy window of the AutowareSimulation scene. If it's missing you can add it to scene by following steps below.

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#integrating-graphy-into-custom-scenes","title":"Integrating Graphy into custom scenes","text":"

    Graphy is pre-integrated within the AutowareSimulation scene. To incorporate Graphy into your own custom scenes, please adhere to the following steps:

    1) Go to the Assets folder in the Project window. 2) Open Graphy > Prefab folder. 3) Drag the Graphy prefab into the scene. 4) You can customize your Graphy by selecting the Graphy prefab in the scene and changing the settings in the inspector window.

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#useful-links","title":"Useful links:","text":"

    Unity Package manager:

    • https://docs.unity3d.com/Manual/upm-ui.html

    Graphy Github page:

    • https://github.com/Tayx94/graphy

    Graphy Documentation:

    • https://github.com/Tayx94/graphy/blob/master/Readme!%20-%20Graphy%20-%20Documentation.pdf
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/","title":"Rider Configuration","text":""},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#jetbrains-rider-setup-with-unity","title":"JetBrains Rider setup with Unity","text":""},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#install-jetbrains-rider","title":"Install JetBrains Rider:","text":"

    Follow the steps in:

    • https://www.jetbrains.com/help/rider/Installation_guide.html#snap
    sudo snap install rider --classic\n
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#install-net-sdk","title":"Install .NET SDK:","text":"

    Follow the steps in:

    • https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#register-the-microsoft-package-repository
    # Get Ubuntu version\ndeclare repo_version=$(if command -v lsb_release &> /dev/null; then lsb_release -r -s; else grep -oP '(?<=^VERSION_ID=).+' /etc/os-release | tr -d '\"'; fi)\n\n# Download Microsoft signing key and repository\nwget https://packages.microsoft.com/config/ubuntu/$repo_version/packages-microsoft-prod.deb -O packages-microsoft-prod.deb\n\n# Install Microsoft signing key and repository\nsudo dpkg -i packages-microsoft-prod.deb\n\n# Clean up\nrm packages-microsoft-prod.deb\n\n# Update packages\nsudo apt update\nsudo apt install dotnet-sdk-8.0\n
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#connect-rider-to-unity-editor","title":"Connect Rider to Unity Editor:","text":"

    Follow the steps in:

    • https://www.jetbrains.com/help/rider/Unity.html#8f092cb7_9
    1) Open an existing Unity project in the Unity Editor.\n\n2) Select Edit > Preferences (Unity > Settings on macOS) and open the External Tools page.\n\n3) In the External Script Editor, select a \"Rider\" installation.\n\n4) In the Preferences window, click \"Regenerate project files\" under the External Tools section.\n\n5) While still in the Unity Editor, right-click anywhere in the Project view and select Open C# Project.\n\n6) Rider will start automatically and open the solution related to this Unity project. Once the solution is loaded, Rider and the Unity Editor become connected. The Unity icon on the toolbar shows the current connection status:\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/","title":"VSCode Configuration","text":""},{"location":"DeveloperGuide/EditorSetup/VSCode/#visual-studio-code-setup-with-unity","title":"Visual Studio Code setup with Unity","text":""},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-visual-studio-code","title":"Install Visual Studio Code","text":"

    Follow the steps in: - https://code.visualstudio.com/docs/setup/linux

    # Install the keys and repository\nsudo apt-get install wget gpg\nwget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg\nsudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg\nsudo sh -c 'echo \"deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main\" > /etc/apt/sources.list.d/vscode.list'\nrm -f packages.microsoft.gpg\n\n# Then update the package cache and install the package using:\nsudo apt install apt-transport-https\nsudo apt update\nsudo apt install code\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-the-dotnet-sdk","title":"Install the Dotnet SDK","text":"

    Follow the steps in: - https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#register-the-microsoft-package-repository

    # Get Ubuntu version\ndeclare repo_version=$(if command -v lsb_release &> /dev/null; then lsb_release -r -s; else grep -oP '(?<=^VERSION_ID=).+' /etc/os-release | tr -d '\"'; fi)\n\n# Download Microsoft signing key and repository\nwget https://packages.microsoft.com/config/ubuntu/$repo_version/packages-microsoft-prod.deb -O packages-microsoft-prod.deb\n\n# Install Microsoft signing key and repository\nsudo dpkg -i packages-microsoft-prod.deb\n\n# Clean up\nrm packages-microsoft-prod.deb\n\n# Update packages\nsudo apt update\n\nsudo apt install dotnet-sdk-8.0\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-the-extensions","title":"Install the extensions","text":"

    Follow the steps in: - https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit - https://marketplace.visualstudio.com/items?itemName=VisualStudioToolsForUnity.vstuc - https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp

    Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter. - ext install ms-dotnettools.csdevkit Repeat for: - ext install VisualStudioToolsForUnity.vstuc - ext install ms-dotnettools.csharp

    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#configure-the-unity","title":"Configure the Unity","text":"
    • Open up the Unity Editor
    • Edit -> Preferences -> External Tools -> External Script Editor
    • Select Visual Studio Code
    • If it's not there, click Browse and navigate and select /usr/bin/code

    It should all be configured now. You can either open up a script by double clicking in the Project window in Unity or by opening up the project in VS Code: - Assets -> Open C# Project

    Syntax highlighting and CTRL-click navigation should work out of the box.

    For more advanced features such as debugging, check the Unity Development with VS Code Documentation.

    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#additional-notes","title":"Additional notes","text":"

    In the AWSIM project, the package Visual Studio Editor is already installed to satisfy the requirement from the Unity for Visual Studio Code extension.

    "},{"location":"DeveloperGuide/HowToContribute/","title":"How to Contribute","text":""},{"location":"DeveloperGuide/HowToContribute/#how-to-contribute","title":"How to Contribute","text":"

    Everyone is welcome!

    "},{"location":"DeveloperGuide/HowToContribute/#how-can-i-get-help","title":"How can I get help?","text":"

    Do not open issues for general support questions as we want to keep GitHub issues for confirmed bug reports. Instead, open a discussion in the Q&A category. The trouble shooting page at AWSIM and at Autoware will be also helpful.

    "},{"location":"DeveloperGuide/HowToContribute/#issue","title":"Issue","text":"

    Before you post an issue, please search Issues and Discussions Q&A catecory to check if it is not a known issue.

    This page is helpful how to create an issue from a repository.

    "},{"location":"DeveloperGuide/HowToContribute/#bug-report","title":"Bug report","text":"

    If you find a new bug, please create an issue here

    "},{"location":"DeveloperGuide/HowToContribute/#feature-request","title":"Feature request","text":"

    If you propose a new feature or have an idea, please create an issue here

    "},{"location":"DeveloperGuide/HowToContribute/#task","title":"Task","text":"

    If you have plan to contribute AWSIM Labs, please create an issue here.

    "},{"location":"DeveloperGuide/HowToContribute/#question","title":"Question","text":"
    • If you need a general support, please open a discussion in the Q&A category.
    • You can contribute by Answering questions and supporting other contributors
    "},{"location":"DeveloperGuide/HowToContribute/#pull-requests","title":"Pull requests","text":"

    If you have an idea to improve the simulation, you can submit a pull request. The following process should be followed:

    1. Create a derived branch (feature/***) from the main branch.
    2. Create a pull request to the main branch.

    Please keep the following in mind, while developing new features:

    • Git branching guidelines
    • C# coding convention.
    "},{"location":"DeveloperGuide/License/","title":"License","text":""},{"location":"DeveloperGuide/License/#awsim-licenses","title":"AWSIM Licenses","text":"

    AWSIM License applies to tier4/AWSIM repositories and all content contained in the Releases.

    • AWSIM specific code is distributed under Apache2.0 License. The following extensions are included (*.cs *.compute *.xml)
    • AWSIM specific assets are distributed under CC BY-NC License. The following extensions are included (*.fbx *.pcd *.osm *.png *.anim *.unitypackage *.x86_64)
    "},{"location":"DeveloperGuide/License/#apache20-license","title":"Apache2.0 License","text":"
    **********************************************************************************\n\n                                 Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright 2022 TIER IV, Inc.\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n
    "},{"location":"DeveloperGuide/License/#cc-by-nc-license","title":"CC BY-NC License","text":"
    **********************************************************************************\n\nAttribution-NonCommercial 4.0 International\n\n=======================================================================\n\nCreative Commons Corporation (\"Creative Commons\") is not a law firm and\ndoes not provide legal services or legal advice. Distribution of\nCreative Commons public licenses does not create a lawyer-client or\nother relationship. Creative Commons makes its licenses and related\ninformation available on an \"as-is\" basis. Creative Commons gives no\nwarranties regarding its licenses, any material licensed under their\nterms and conditions, or any related information. Creative Commons\ndisclaims all liability for damages resulting from their use to the\nfullest extent possible.\n\nUsing Creative Commons Public Licenses\n\nCreative Commons public licenses provide a standard set of terms and\nconditions that creators and other rights holders may use to share\noriginal works of authorship and other material subject to copyright\nand certain other rights specified in the public license below. The\nfollowing considerations are for informational purposes only, are not\nexhaustive, and do not form part of our licenses.\n\n     Considerations for licensors: Our public licenses are\n     intended for use by those authorized to give the public\n     permission to use material in ways otherwise restricted by\n     copyright and certain other rights. Our licenses are\n     irrevocable. Licensors should read and understand the terms\n     and conditions of the license they choose before applying it.\n     Licensors should also secure all rights necessary before\n     applying our licenses so that the public can reuse the\n     material as expected. Licensors should clearly mark any\n     material not subject to the license. This includes other CC-\n     licensed material, or material used under an exception or\n     limitation to copyright. More considerations for licensors:\n    wiki.creativecommons.org/Considerations_for_licensors\n\n     Considerations for the public: By using one of our public\n     licenses, a licensor grants the public permission to use the\n     licensed material under specified terms and conditions. If\n     the licensor's permission is not necessary for any reason--for\n     example, because of any applicable exception or limitation to\n     copyright--then that use is not regulated by the license. Our\n     licenses grant only permissions under copyright and certain\n     other rights that a licensor has authority to grant. Use of\n     the licensed material may still be restricted for other\n     reasons, including because others have copyright or other\n     rights in the material. A licensor may make special requests,\n     such as asking that all changes be marked or described.\n     Although not required by our licenses, you are encouraged to\n     respect those requests where reasonable. More considerations\n     for the public:\n    wiki.creativecommons.org/Considerations_for_licensees\n\n=======================================================================\n\nCreative Commons Attribution-NonCommercial 4.0 International Public\nLicense\n\nBy exercising the Licensed Rights (defined below), You accept and agree\nto be bound by the terms and conditions of this Creative Commons\nAttribution-NonCommercial 4.0 International Public License (\"Public\nLicense\"). To the extent this Public License may be interpreted as a\ncontract, You are granted the Licensed Rights in consideration of Your\nacceptance of these terms and conditions, and the Licensor grants You\nsuch rights in consideration of benefits the Licensor receives from\nmaking the Licensed Material available under these terms and\nconditions.\n\n\nSection 1 -- Definitions.\n\n  a. Adapted Material means material subject to Copyright and Similar\n     Rights that is derived from or based upon the Licensed Material\n     and in which the Licensed Material is translated, altered,\n     arranged, transformed, or otherwise modified in a manner requiring\n     permission under the Copyright and Similar Rights held by the\n     Licensor. For purposes of this Public License, where the Licensed\n     Material is a musical work, performance, or sound recording,\n     Adapted Material is always produced where the Licensed Material is\n     synched in timed relation with a moving image.\n\n  b. Adapter's License means the license You apply to Your Copyright\n     and Similar Rights in Your contributions to Adapted Material in\n     accordance with the terms and conditions of this Public License.\n\n  c. Copyright and Similar Rights means copyright and/or similar rights\n     closely related to copyright including, without limitation,\n     performance, broadcast, sound recording, and Sui Generis Database\n     Rights, without regard to how the rights are labeled or\n     categorized. For purposes of this Public License, the rights\n     specified in Section 2(b)(1)-(2) are not Copyright and Similar\n     Rights.\n  d. Effective Technological Measures means those measures that, in the\n     absence of proper authority, may not be circumvented under laws\n     fulfilling obligations under Article 11 of the WIPO Copyright\n     Treaty adopted on December 20, 1996, and/or similar international\n     agreements.\n\n  e. Exceptions and Limitations means fair use, fair dealing, and/or\n     any other exception or limitation to Copyright and Similar Rights\n     that applies to Your use of the Licensed Material.\n\n  f. Licensed Material means the artistic or literary work, database,\n     or other material to which the Licensor applied this Public\n     License.\n\n  g. Licensed Rights means the rights granted to You subject to the\n     terms and conditions of this Public License, which are limited to\n     all Copyright and Similar Rights that apply to Your use of the\n     Licensed Material and that the Licensor has authority to license.\n\n  h. Licensor means the individual(s) or entity(ies) granting rights\n     under this Public License.\n\n  i. NonCommercial means not primarily intended for or directed towards\n     commercial advantage or monetary compensation. For purposes of\n     this Public License, the exchange of the Licensed Material for\n     other material subject to Copyright and Similar Rights by digital\n     file-sharing or similar means is NonCommercial provided there is\n     no payment of monetary compensation in connection with the\n     exchange.\n\n  j. Share means to provide material to the public by any means or\n     process that requires permission under the Licensed Rights, such\n     as reproduction, public display, public performance, distribution,\n     dissemination, communication, or importation, and to make material\n     available to the public including in ways that members of the\n     public may access the material from a place and at a time\n     individually chosen by them.\n\n  k. Sui Generis Database Rights means rights other than copyright\n     resulting from Directive 96/9/EC of the European Parliament and of\n     the Council of 11 March 1996 on the legal protection of databases,\n     as amended and/or succeeded, as well as other essentially\n     equivalent rights anywhere in the world.\n\n  l. You means the individual or entity exercising the Licensed Rights\n     under this Public License. Your has a corresponding meaning.\n\n\nSection 2 -- Scope.\n\n  a. License grant.\n\n       1. Subject to the terms and conditions of this Public License,\n          the Licensor hereby grants You a worldwide, royalty-free,\n          non-sublicensable, non-exclusive, irrevocable license to\n          exercise the Licensed Rights in the Licensed Material to:\n\n            a. reproduce and Share the Licensed Material, in whole or\n               in part, for NonCommercial purposes only; and\n\n            b. produce, reproduce, and Share Adapted Material for\n               NonCommercial purposes only.\n\n       2. Exceptions and Limitations. For the avoidance of doubt, where\n          Exceptions and Limitations apply to Your use, this Public\n          License does not apply, and You do not need to comply with\n          its terms and conditions.\n\n       3. Term. The term of this Public License is specified in Section\n          6(a).\n\n       4. Media and formats; technical modifications allowed. The\n          Licensor authorizes You to exercise the Licensed Rights in\n          all media and formats whether now known or hereafter created,\n          and to make technical modifications necessary to do so. The\n          Licensor waives and/or agrees not to assert any right or\n          authority to forbid You from making technical modifications\n          necessary to exercise the Licensed Rights, including\n          technical modifications necessary to circumvent Effective\n          Technological Measures. For purposes of this Public License,\n          simply making modifications authorized by this Section 2(a)\n          (4) never produces Adapted Material.\n\n       5. Downstream recipients.\n\n            a. Offer from the Licensor -- Licensed Material. Every\n               recipient of the Licensed Material automatically\n               receives an offer from the Licensor to exercise the\n               Licensed Rights under the terms and conditions of this\n               Public License.\n\n            b. No downstream restrictions. You may not offer or impose\n               any additional or different terms or conditions on, or\n               apply any Effective Technological Measures to, the\n               Licensed Material if doing so restricts exercise of the\n               Licensed Rights by any recipient of the Licensed\n               Material.\n\n       6. No endorsement. Nothing in this Public License constitutes or\n          may be construed as permission to assert or imply that You\n          are, or that Your use of the Licensed Material is, connected\n          with, or sponsored, endorsed, or granted official status by,\n          the Licensor or others designated to receive attribution as\n          provided in Section 3(a)(1)(A)(i).\n\n  b. Other rights.\n\n       1. Moral rights, such as the right of integrity, are not\n          licensed under this Public License, nor are publicity,\n          privacy, and/or other similar personality rights; however, to\n          the extent possible, the Licensor waives and/or agrees not to\n          assert any such rights held by the Licensor to the limited\n          extent necessary to allow You to exercise the Licensed\n          Rights, but not otherwise.\n\n       2. Patent and trademark rights are not licensed under this\n          Public License.\n\n       3. To the extent possible, the Licensor waives any right to\n          collect royalties from You for the exercise of the Licensed\n          Rights, whether directly or through a collecting society\n          under any voluntary or waivable statutory or compulsory\n          licensing scheme. In all other cases the Licensor expressly\n          reserves any right to collect such royalties, including when\n          the Licensed Material is used other than for NonCommercial\n          purposes.\n\n\nSection 3 -- License Conditions.\n\nYour exercise of the Licensed Rights is expressly made subject to the\nfollowing conditions.\n\n  a. Attribution.\n\n       1. If You Share the Licensed Material (including in modified\n          form), You must:\n\n            a. retain the following if it is supplied by the Licensor\n               with the Licensed Material:\n\n                 i. identification of the creator(s) of the Licensed\n                    Material and any others designated to receive\n                    attribution, in any reasonable manner requested by\n                    the Licensor (including by pseudonym if\n                    designated);\n\n                ii. a copyright notice;\n\n               iii. a notice that refers to this Public License;\n\n                iv. a notice that refers to the disclaimer of\n                    warranties;\n\n                 v. a URI or hyperlink to the Licensed Material to the\n                    extent reasonably practicable;\n\n            b. indicate if You modified the Licensed Material and\n               retain an indication of any previous modifications; and\n\n            c. indicate the Licensed Material is licensed under this\n               Public License, and include the text of, or the URI or\n               hyperlink to, this Public License.\n\n       2. You may satisfy the conditions in Section 3(a)(1) in any\n          reasonable manner based on the medium, means, and context in\n          which You Share the Licensed Material. For example, it may be\n          reasonable to satisfy the conditions by providing a URI or\n          hyperlink to a resource that includes the required\n          information.\n\n       3. If requested by the Licensor, You must remove any of the\n          information required by Section 3(a)(1)(A) to the extent\n          reasonably practicable.\n\n       4. If You Share Adapted Material You produce, the Adapter's\n          License You apply must not prevent recipients of the Adapted\n          Material from complying with this Public License.\n\n\nSection 4 -- Sui Generis Database Rights.\n\nWhere the Licensed Rights include Sui Generis Database Rights that\napply to Your use of the Licensed Material:\n\n  a. for the avoidance of doubt, Section 2(a)(1) grants You the right\n     to extract, reuse, reproduce, and Share all or a substantial\n     portion of the contents of the database for NonCommercial purposes\n     only;\n\n  b. if You include all or a substantial portion of the database\n     contents in a database in which You have Sui Generis Database\n     Rights, then the database in which You have Sui Generis Database\n     Rights (but not its individual contents) is Adapted Material; and\n\n  c. You must comply with the conditions in Section 3(a) if You Share\n     all or a substantial portion of the contents of the database.\n\nFor the avoidance of doubt, this Section 4 supplements and does not\nreplace Your obligations under this Public License where the Licensed\nRights include other Copyright and Similar Rights.\n\n\nSection 5 -- Disclaimer of Warranties and Limitation of Liability.\n\n  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE\n     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS\n     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF\n     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,\n     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,\n     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR\n     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,\n     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT\n     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT\n     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.\n\n  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE\n     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,\n     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,\n     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,\n     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR\n     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN\n     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR\n     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR\n     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.\n\n  c. The disclaimer of warranties and limitation of liability provided\n     above shall be interpreted in a manner that, to the extent\n     possible, most closely approximates an absolute disclaimer and\n     waiver of all liability.\n\n\nSection 6 -- Term and Termination.\n\n  a. This Public License applies for the term of the Copyright and\n     Similar Rights licensed here. However, if You fail to comply with\n     this Public License, then Your rights under this Public License\n     terminate automatically.\n\n  b. Where Your right to use the Licensed Material has terminated under\n     Section 6(a), it reinstates:\n\n       1. automatically as of the date the violation is cured, provided\n          it is cured within 30 days of Your discovery of the\n          violation; or\n\n       2. upon express reinstatement by the Licensor.\n\n     For the avoidance of doubt, this Section 6(b) does not affect any\n     right the Licensor may have to seek remedies for Your violations\n     of this Public License.\n\n  c. For the avoidance of doubt, the Licensor may also offer the\n     Licensed Material under separate terms or conditions or stop\n     distributing the Licensed Material at any time; however, doing so\n     will not terminate this Public License.\n\n  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public\n     License.\n\n\nSection 7 -- Other Terms and Conditions.\n\n  a. The Licensor shall not be bound by any additional or different\n     terms or conditions communicated by You unless expressly agreed.\n\n  b. Any arrangements, understandings, or agreements regarding the\n     Licensed Material not stated herein are separate from and\n     independent of the terms and conditions of this Public License.\n\n\nSection 8 -- Interpretation.\n\n  a. For the avoidance of doubt, this Public License does not, and\n     shall not be interpreted to, reduce, limit, restrict, or impose\n     conditions on any use of the Licensed Material that could lawfully\n     be made without permission under this Public License.\n\n  b. To the extent possible, if any provision of this Public License is\n     deemed unenforceable, it shall be automatically reformed to the\n     minimum extent necessary to make it enforceable. If the provision\n     cannot be reformed, it shall be severed from this Public License\n     without affecting the enforceability of the remaining terms and\n     conditions.\n\n  c. No term or condition of this Public License will be waived and no\n     failure to comply consented to unless expressly agreed to by the\n     Licensor.\n\n  d. Nothing in this Public License constitutes or may be interpreted\n     as a limitation upon, or waiver of, any privileges and immunities\n     that apply to the Licensor or You, including from the legal\n     processes of any jurisdiction or authority.\n\n=======================================================================\n\nCreative Commons is not a party to its public\nlicenses. Notwithstanding, Creative Commons may elect to apply one of\nits public licenses to material it publishes and in those instances\nwill be considered the \u201cLicensor.\u201d The text of the Creative Commons\npublic licenses is dedicated to the public domain under the CC0 Public\nDomain Dedication. Except for the limited purpose of indicating that\nmaterial is shared under a Creative Commons public license or as\notherwise permitted by the Creative Commons policies published at\ncreativecommons.org/policies, Creative Commons does not authorize the\nuse of the trademark \"Creative Commons\" or any other trademark or logo\nof Creative Commons without its prior written consent including,\nwithout limitation, in connection with any unauthorized modifications\nto any of its public licenses or any other arrangements,\nunderstandings, or agreements concerning use of licensed material. For\nthe avoidance of doubt, this paragraph does not form part of the\npublic licenses.\n\nCreative Commons may be contacted at creativecommons.org\n
    "},{"location":"DeveloperGuide/TroubleShooting/","title":"Trouble shooting","text":""},{"location":"DeveloperGuide/TroubleShooting/#trouble-shooting","title":"Trouble shooting","text":"

    This document describes the most common errors encountered when working with AWSIm or autoware.

    Trouble Solution Massive output of Plugins errors git clone the AWSIM repository again error : RuntimeError: error not set, at C:\\ci\\ws\\src\\ros2\\rcl\\rcl\\src\\rcl\\node.c:262 Set up environment variables and config around ROS2 correctly. For example: - Environment variables - cyclonedds_config.xml $ ros2 topic list is not displayed - your machine ROS_DOMAIN_ID is different- ROS2 is not sourced Using AWSIM on Windows and Autoware on Ubuntu. $ ros2 topic list is not displayed. Allow the communication in Windows Firewall self-driving stops in the middle of the road. Check if your map data is correct (PointCloud, VectorMap, 3D fbx models) Connecting AWSIM and Autoware results in bad network Make ros local host-only. Include the following in the .bashrc (The password will be requested at terminal startup after OS startup.) export ROS_LOCALHOST_ONLY=1export RMW_IMPLEMENTATION=rmw_cyclonedds_cppif [ ! -e /tmp/cycloneDDS_configured ]; thensudo sysctl -w net.core.rmem_max=2147483647sudo ip link set lo multicast ontouch /tmp/cycloneDDS_configuredfi Lidar (colored pointcloud on RViz ) does not show. Reduce processing load by following command. This can only be applied to Autoware's awsim-stable branch. cd <path_to_your_autoware_folder>wget \"https://drive.google.com/uc?export=download&id=11mkwfg-OaXIp3Z5c3R58Pob3butKwE1Z\" -O patch.shbash patch.sh && rm patch.sh Error when starting AWSIM binary. segmentation fault (core dumped) - Check if yourNvidia drivers or Vulkan API are installed correctly - When building binary please pay attantion whether the Graphic Jobs option in Player Settings is disabled. It should be disabled since it may produce segmentation fault errors. Please check forum for more details. Initial pose does not match automatically. Set initial pose manually. Unity crashes and check the log for the cause of the error. Editor log file locationWindows : C:\\Users\\username\\AppData\\Local\\Unity\\Editor\\Editor.logLinux : ~/.config/unity3d/.Editor.log Player log file location Windows : C:\\Users\\username\\AppData\\LocalLow\\CompanyName\\ProductName\\output_log.txtLinux :~/.config/unity3d/CompanyName/ProductName/Player.logSee also : Unity Documentation - Log Files Safe mode dialog appears when starting UnityEditor. or error : No usable version of libssl was found 1. download libssl $ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5.11_amd64.deb 2. install sudo dpkg -i libssl1.0.0_1.0.2n-1ubuntu5.11_amd64.deb (Windows) Unity Editor's error:Plugins: Failed to load 'Assets/RGLUnityPlugin/Plugins/Windows/x86_64/RobotecGPULidar.dll' because one or more of its dependencies could not be loaded. Install Microsoft Visual C++ Redistributable packages for Visual Studio 2015, 2017, 2019, and 2022 (X64 Architecture) (Windows) Built-binary or Unity Editor freeze when simulation started Update/Install latest NIC(NetworkInterfaceCard) drivers for your PC.Especially, if you can find latest drivers provided by chip vendors for the interfaces (not by Microsoft), we recommend vendors' drivers."},{"location":"GettingStarted/QuickStartDemo/","title":"Quick Start Demo","text":""},{"location":"GettingStarted/QuickStartDemo/#quick-start-demo","title":"Quick Start Demo","text":"

    Below you can find instructions on how to setup the self-driving demo of AWSIM simulation controlled by Autoware. The instruction assumes using the Ubuntu OS.

    "},{"location":"GettingStarted/QuickStartDemo/#demo-configuration","title":"Demo configuration","text":"

    The simulation provided in the AWSIM demo is configured as follows:

    AWSIM Demo Settings Vehicle Lexus RX 450h Environment Japan Tokyo Nishishinjuku Sensors GNSSIMU3 x VLP16Traffic Light Camera Traffic Randomized traffic ROS2 humble"},{"location":"GettingStarted/QuickStartDemo/#pc-specs","title":"PC specs","text":"

    Please make sure that your machine meets the following requirements in order to run the simulation correctly:

    Required PC Specs OS Ubuntu 22.04 CPU 6c12t or higher GPU RTX 2080 or higher Nvidia Driver (Ubuntu 22) >=545"},{"location":"GettingStarted/QuickStartDemo/#dds-configuration","title":"DDS configuration","text":"

    In order to run AWSIM Labs with the best performance and without hogging the network, please follow the steps below.

    Add the following lines to ~/.bashrc file:

    if [ ! -e /tmp/cycloneDDS_configured ]; then\n    sudo sysctl -w net.core.rmem_max=2147483647\n    sudo sysctl -w net.ipv4.ipfrag_time=3\n    sudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728     # (128 MB)\n    sudo ip link set lo multicast on\n    touch /tmp/cycloneDDS_configured\nfi\n

    Every time you restart this machine, and open a new terminal, the above commands will be executed.

    Until you restart the machine, they will not be executed again.

    "},{"location":"GettingStarted/QuickStartDemo/#cyclonedds-configuration","title":"CycloneDDS configuration","text":"

    Save the following as cyclonedds.xml in your home directory ~: 

    <?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<CycloneDDS xmlns=\"https://cdds.io/config\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd\">\n    <Domain Id=\"any\">\n        <General>\n            <Interfaces>\n                <NetworkInterface name=\"lo\" priority=\"default\" multicast=\"default\" />\n            </Interfaces>\n            <AllowMulticast>default</AllowMulticast>\n            <MaxMessageSize>65500B</MaxMessageSize>\n        </General>\n        <Internal>\n            <SocketReceiveBufferSize min=\"10MB\"/>\n            <Watermarks>\n                <WhcHigh>500kB</WhcHigh>\n            </Watermarks>\n        </Internal>\n    </Domain>\n</CycloneDDS>\n

    Make sure the following lines are added to the ~/.bashrc file:

    export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp\nexport CYCLONEDDS_URI=/home/your_username/cyclonedds.xml\n

    Replace your_username with your actual username.

    Note

    You should use the absolute path to the cyclonedds.xml file.

    Warning

    A system restart is required for these changes to work.

    Warning

    DO NOT set export ROS_LOCALHOST_ONLY=1. CycloneDDS configuration will be enough.

    "},{"location":"GettingStarted/QuickStartDemo/#start-the-demo","title":"Start the demo","text":""},{"location":"GettingStarted/QuickStartDemo/#running-the-awsim-demo","title":"Running the AWSIM demo","text":"

    To run the simulator, please follow the steps below.

    1. Install Nvidia GPU driver (Skip if already installed).

      1. Add Nvidia driver to apt repository 
        sudo add-apt-repository ppa:graphics-drivers/ppa\nsudo apt update\n
      2. Install the recommended version of the driver. 
        sudo ubuntu-drivers autoinstall\n\n# or install a specific version (following was tested)\nsudo apt install nvidia-driver-550\n
      3. Reboot your machine to make the installed driver detected by the system. 
        sudo reboot\n
      4. Open terminal and check if nvidia-smi command is available and outputs summary similar to the one presented below. 
        $ nvidia-smi\n+-----------------------------------------------------------------------------------------+\n| NVIDIA-SMI 550.54.15              Driver Version: 550.54.15      CUDA Version: 12.4     |\n|-----------------------------------------+------------------------+----------------------+\n| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |\n| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |\n|                                         |                        |               MIG M. |\n|=========================================+========================+======================|\n|   0  NVIDIA GeForce RTX 3080        Off |   00000000:2D:00.0  On |                  N/A |\n| 30%   40C    P8             35W /  320W |    5299MiB /  10240MiB |      7%      Default |\n|                                         |                        |                  N/A |\n+-----------------------------------------+------------------------+----------------------+\n...\n

    2. Install Vulkan Graphics Library (Skip if already installed).

      1. Update the environment. 
        sudo apt update\n
      2. Install the library. 
        sudo apt install libvulkan1\n

    3. Download and Run AWSIM Demo binary.

      1. Download the latest release from:

        AWSIM Labs GitHub Releases Page

      2. Unzip the downloaded file.

      3. Make the file executable.

        Right click the awsim_labs.x86_64 file and check the Execute checkbox

        or execute the command below.

        chmod +x <path to AWSIM folder>/awsim_labs.x86_64\n

      4. Launch awsim_labs.x86_64. 

        ./<path to AWSIM folder>/awsim_labs.x86_64\n

        It may take some time for the application to start the so please wait until image similar to the one presented below is visible in your application window.

    "},{"location":"GettingStarted/QuickStartDemo/#launching-autoware","title":"Launching Autoware","text":"

    In order to configure and run the Autoware software with the AWSIM demo, please:

    1. Download map files (pcd, osm) and unzip them. Download Map files (pcd, osm)

    2. Clone Autoware and move to the directory. 

      git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n
    3. Switch branch to main. 
      git checkout main\n
    4. Configure the environment. (Skip if Autoware environment has been configured before) 
      ./setup-dev-env.sh\n
    5. Create the src directory and clone external dependent repositories into it. 
      mkdir src\nvcs import src < autoware.repos\n
    6. Install dependent ROS packages. 
      source /opt/ros/humble/setup.bash\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n
    7. Build the workspace. 
      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
    8. Launch Autoware. 
      source install/setup.bash\nros2 launch autoware_launch e2e_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=awsim_labs_sensor_kit map_path:=<absolute path of map folder>\n\n# Use the absolute path for the map folder, don't use the ~ operator.\n\n# Example:\nros2 launch autoware_launch e2e_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=awsim_labs_sensor_kit map_path:=/home/your_username/autoware_map/nishishinjuku_autoware_map\n
    "},{"location":"GettingStarted/QuickStartDemo/#lets-run-the-self-driving-simulation","title":"Let's run the self driving simulation","text":"

    1. Launch AWSIM and Autoware according to the steps described earlier in this document.

    2. The Autoware will automatically set its pose estimation as presented below.

    3. Set the navigation goal for the vehicle.

    4. Optionally, you can define an intermediate point through which the vehicle will travel on its way to the destination. The generated path can be seen on the image below.

    5. Enable self-driving.

    To make the vehicle start navigating please engage its operation using the command below.

    cd autoware\nsource install/setup.bash\nros2 topic pub /autoware/engage autoware_vehicle_msgs/msg/Engage '{engage: True}' -1\n

    The self-driving simulation demo has been successfully launched!

    "},{"location":"GettingStarted/QuickStartDemo/#troubleshooting","title":"Troubleshooting","text":"

    In case of any problems with running the sample AWSIM binary with Autoware, start with checking our Troubleshooting page with the most common problems.

    "},{"location":"GettingStarted/QuickStartDemo/#appendix","title":"Appendix","text":"
    • AWSIM ROS2 topic list
    "},{"location":"GettingStarted/SetupUnityProject/","title":"Setup Unity Project","text":""},{"location":"GettingStarted/SetupUnityProject/#setup-unity-project","title":"Setup Unity Project","text":"

    Info

    It is advised to checkout the Quick Start Demo tutorial before reading this section.

    This page is a tutorial for setting up a AWSIM Unity project.

    "},{"location":"GettingStarted/SetupUnityProject/#environment-preparation","title":"Environment preparation","text":""},{"location":"GettingStarted/SetupUnityProject/#system-setup","title":"System setup","text":"Ubuntu 22Windows
    1. Make sure your machine meets the required hardware specifications.
      • NOTE: PC requirements may vary depending on simulation contents which may change as the simulator develops
    2. Prepare a desktop PC with Ubuntu 22.04 installed.
    3. Install Nvidia drivers and Vulkan Graphics API.
    4. Install git.
    5. Follow the DDS configuration guide.
    1. Make sure your machine meets the required hardware specifications.
      • NOTE: PC requirements may vary depending on simulation contents which may change as the simulator develops
    2. Prepare a desktop PC with Windows 10 or 11 (64 bit) installed.
    3. Install git.
    4. Install Microsoft Visual C++ Redistributable packages for Visual Studio 2015, 2017, 2019, and 2022 (X64 Architecture)
    "},{"location":"GettingStarted/SetupUnityProject/#ros-2","title":"ROS 2","text":"

    AWSIM comes with a standalone flavor of Ros2ForUnity. This means that, to avoid internal conflicts between different ROS 2 versions, you shouldn't run the Editor or AWSIM binary with ROS 2 sourced.

    Warning

    Do not run the AWSIM, Unity Hub, or the Editor with ROS 2 sourced.

    Ubuntu 22Windows
    • Make sure that the terminal which you are using to run Unity Hub, Editor, or AWSIM doesn't have ROS 2 sourced.
    • It is common to have ROS 2 sourced automatically with ~/.bashrc or ~/.profile. Make sure it is not obscuring your working environment:
      • Running Unity Hub from the Ubuntu GUI menu takes the environment configuration from ~/.profile.
      • Running Unity Hub from the terminal uses the current terminal configuration from ~/.profile and ~/.bashrc.
      • Running Unity Editor from the UnityHub inherits the environment setup from the Unity Hub.
    • Make sure your Windows environment variables are ROS 2 free.
    "},{"location":"GettingStarted/SetupUnityProject/#unity-installation","title":"Unity installation","text":"

    Info

    AWSIM's Unity version is currently 2022.3.36f1

    Follow the steps below to install Unity on your machine:

    "},{"location":"GettingStarted/SetupUnityProject/#install-unityhub","title":"Install UnityHub:","text":"
    1. Install UnityHub to manage Unity projects. Please go to Unity download page and download latest UnityHub.AppImage.
    2. Install Unity 2022.3.36f1 via UnityHub:
      • Open new terminal, navigate to directory where UnityHub.AppImage is download and execute the following command: 
        ./UnityHub.AppImage\n
    "},{"location":"GettingStarted/SetupUnityProject/#install-unity-editor","title":"Install Unity Editor:","text":"
    1. Click Installs from the left menu and then click the Install Editor button from the top right.
    2. From the new window click the Official releases tab and check for the current version of Unity. - If you can't find the version, click to Archive and search for the version in the Unity archives page. It will direct you to Unity Archive.

    3. After finding the version, click the download/install button to start the installation process. - At this point, your Unity installation process should have started.

      === \"Ubuntu 22\" - *NOTE: If the installation process has not started after clicking the download/install button, please copy the hyperlink (by right clicking the button and selecting Copy link address) and add it as an argument for Unity Hub app. An example command: 

      ./UnityHub.AppImage unityhub://2022.3.21f1/d91830b65d9b\n

    4. After successful installation the version will be available in the Installs tab in Unity Hub.

    "},{"location":"GettingStarted/SetupUnityProject/#open-awsim-project","title":"Open AWSIM project","text":"

    To open the Unity AWSIM project in Unity Editor:

    Using Unity HubUsing Terminal

    1. Make sure you have the AWSIM repository cloned and ROS 2 is not sourced. 

      git clone git@github.com:autowarefoundation/AWSIM.git\n

    2. Launch UnityHub. 

      ./UnityHub.AppImage\n

      Info

      If you are launching the Unity Hub from the Ubuntu applications menu (without the terminal), make sure that system optimizations are set. To be sure, run the terminal at least once before running the Unity Hub. This will apply the OS settings.

    3. Open the project in UnityHub

      • Click the Open button from the Projects tab,
      • Navigate the directory where the AWSIM repository was cloned to and select the directory,
      • The project should be added to Projects tab in Unity Hub. To launch the project in Unity Editor simply click the AWSIM project.
      • The project is now ready to use.
      • The project can be opened by double clicking on the project name or selecting it from the list then clicking the Open button on the top right.

    1. Enter the AWSIM directory (make sure ROS 2 is not sourced). 

      cd AWSIM\n

    2. If your Unity Editor is in default location, run the project using the editor command. 

      ~/Unity/Hub/Editor/[your_editor_version]/Editor/Unity -projectPath .\n

      Info

      Please specify your Unity Editor version in the path. If your Unity Editor is installed in different location, please adjust the path accordingly.

    Warning

    If you get the safe mode dialog when starting UnityEditor, you may need to install openssl.

    1. download libssl $ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5.13_amd64.deb
    2. install sudo dpkg -i libssl1.0.0_1.0.2n-1ubuntu5.13_amd64.deb
    "},{"location":"GettingStarted/SetupUnityProject/#import-external-packages","title":"Import external packages","text":"

    To properly run and use AWSIM project in Unity it is required to download map package which is not included in the repository.

    1. Download and import Nishishinjuku_URP_v0.1.0.unitypackage

      Download Map Package

    2. In Unity Editor, from the menu bar at the top, select Assets -> Import Package -> Custom Package... and navigate the Nishishinjuku_URP.unitypackage file you've downloaded and open.

    3. Click Import button in the popup window to import the package.
    4. Nishishinjuku package should be successfully imported under Assets/AWSIM/Externals/directory. You can access the directory from the Project window in Unity Editor.

    Info

    The Externals directory is added to the .gitignore because the map has a large file size and should not be directly uploaded to the repository.

    "},{"location":"GettingStarted/SetupUnityProject/#import-graphy-asset","title":"Import Graphy Asset","text":"

    Import Graphy by following these instructions: Graphy Asset Setup

    "},{"location":"GettingStarted/SetupUnityProject/#run-the-demo-in-editor","title":"Run the demo in Editor","text":"

    The following steps describe how to run the demo in Unity Editor:

    1. Open the AutowareSimulation.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Now you should see the simulation running in the Editor.

    If you encounter any issues while running the simulation, please refer to the Troubleshooting section or open an issue in the AWSIM Labs GitHub.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/","title":"Using OpenSCENARIO","text":""},{"location":"GettingStarted/UsingOpenSCENARIO/#using-openscenario","title":"Using OpenSCENARIO","text":"

    Warning

    Running AWSIM with scenario_simulator_v2 is still a prototype, so stable running is not guaranteed.

    Below you can find instructions on how to setup the OpenSCENARIO execution using scenario_simulator_v2 with AWSIM as a simulator The instruction assumes using the Ubuntu OS.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/#prerequisites","title":"Prerequisites","text":"
    • Follow Setup Unity Project tutorial
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#build-autoware-with-scenario_simulator_v2","title":"Build Autoware with scenario_simulator_v2","text":"

    In order to configure the Autoware software with the AWSIM Labs demo, please:

    1. Clone the Autoware and move to the directory. 
      git clone git@github.com:autowarefoundation/autoware.git\ncd autoware\n
    2. Check out to the awsim-labs-stable branch (This is a temporary branch, and it will be used in the main branch later on.) 
      git checkout awsim-labs-stable\n
    3. Configure the environment. (Skip if Autoware environment has been configured before) 
      ./setup-dev-env.sh\n
    4. Create the src directory and clone external dependent repositories into it. 
      mkdir src\nvcs import src < autoware.repos\nvcs import src < simulator.repos\n

    5. Download shinjuku_map.zip archive

    6. Unzip it to src/simulator directory 

      unzip <Download directory>/shinjuku_map.zip -d src/simulator\n
    7. Install dependent ROS packages. 
      source /opt/ros/humble/setup.bash\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n
    8. Build the workspace. 
      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"-w\"\n
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#running-the-demo","title":"Running the demo","text":"
    1. Open AutowareSimulationScenarioSimulator.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Launch scenario_test_runner. 
      source install/setup.bash\nros2 launch scenario_test_runner scenario_test_runner.launch.py                        \\\narchitecture_type:=awf/universe/20240605  record:=false                                         \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim.yaml'          \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                          \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\" \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#troubleshooting","title":"Troubleshooting","text":"

    In case of problems, make sure that the regular demo work well with the Autoware built above. Follow the troubleshooting page there if necessary.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/#appendix","title":"Appendix","text":"
    • AWSIM ROS2 topic list
    "},{"location":"Introduction/AWSIM/","title":"AWSIM Labs","text":""},{"location":"Introduction/AWSIM/#awsim-labs","title":"AWSIM Labs","text":"

    AWSIM Labs is a fork of TIER IV/AWSIM, an open-source simulator made with Unity for autonomous driving research and development. It is developed for self-driving software like Autoware. This simulator aims to bridge the gap between the virtual and real worlds, enabling users to train and evaluate their autonomous systems in a safe and controlled environment before deploying them on real vehicles. It provides a realistic virtual environment for training, testing, and evaluating various aspects of autonomous driving systems.

    AWSIM simulates a variety of real-world scenarios, with accurate physics and sensor models. It offers a wide range of sensors, such as: Cameras, GNSS, IMU and LiDARs, allowing developers to simulate their autonomous vehicle's interactions with the environment accurately. The simulator also models dynamic objects, such as pedestrians, other vehicles, and traffic lights, making it possible to study interactions and decision-making in complex traffic scenarios. This enables the testing and evaluation of perception, planning, and control algorithms under different sensor configurations and scenarios.

    AWSIM supports a flexible and modular architecture, making it easy to customize and extend its capabilities. Users can modify the current or add a new environment with their own assets and traffic rules to create custom scenarios to suit their specific research needs. This allows for the development and testing of advanced algorithms in diverse driving conditions.

    Because AWSIM was developed mainly to work with Autoware, it supports:

    • Ubuntu 22.04 and Windows 10/11
    • ROS2 Humble distribution

    Prerequisites

    You can read more about the prerequisites and running AWSIM here.

    Connection with Autoware

    Introduction about how the connection between AWSIM and Autoware works can be read here.

    "},{"location":"Introduction/AWSIM/#why-was-awsim-developed","title":"Why was AWSIM developed?","text":"

    The main objectives of AWSIM are to facilitate research and development in autonomous driving, enable benchmarking of algorithms and systems, and foster collaboration and knowledge exchange within the autonomous driving community. By providing a realistic and accessible platform, AWSIM aims to accelerate the progress and innovation in the field of autonomous driving.

    "},{"location":"Introduction/AWSIM/#architecture","title":"Architecture","text":"

    To describe the architecture of AWSIM, first of all, it is necessary to mention the Scene. It contains all the objects occurring in the simulation of a specific scenario and their configurations. The default AWSIM scene that is developed to work with Autoware is called AutowareSimulation.

    In the scene we can distinguish basics components such like MainCamera, ClockPublisher, EventSystem and Canvas. A detailed description of the scene and its components can be found here.

    Besides the elements mentioned above, the scene contains two more, very important and complex components: Environment and EgoVehicle - described below.

    "},{"location":"Introduction/AWSIM/#environment","title":"Environment","text":"

    Environment is a component that contains all Visual Elements that simulate the environment in the scene and those that provide control over them. It also contains two components Directional Light and Volume, which ensure suitable lighting for Visual Elements and simulate weather conditions. A detailed description of these components can be found here.

    In addition to Visual Elements such as buildings or greenery, it contains the entire architecture responsible for traffic. The traffic involves NPCVehicles that are spawned in the simulation by TrafficSimulator - using traffic components. A quick overview of the traffic components is provided below, however, you can read their detailed description here.

    NPCPedestrians are also Environment components, but they are not controlled by TrafficSimulator. They have added scripts that control their movement - you can read more details here.

    "},{"location":"Introduction/AWSIM/#traffic-components","title":"Traffic Components","text":"

    TrafficLanes and StopLines are elements loaded into Environment from Lanelet2. TrafficLanes have defined cross-references in such a way as to create routes along the traffic lanes. In addition, each TrafficLane present at the intersection has specific conditions for yielding priority. TrafficSimulator uses TrafficLanes to spawn NPCVehicles and ensure their movement along these lanes. If some TrafficLanes ends just before the intersection, then it has a reference to StopLine. Each StopLine at the intersection with TrafficLights has reference to the nearest TrafficLight. TrafficLights belong to one of the visual element groups and provide an interface to control visual elements that simulate traffic light sources (bulbs). A single TrafficIntersection is responsible for controlling all TrafficLights at one intersection. Detailed description of mentioned components is in this section.

    "},{"location":"Introduction/AWSIM/#egovehicle","title":"EgoVehicle","text":"

    EgoVehicle is a component responsible for simulating an autonomous vehicle moving around the scene. It includes:

    • Models and Reflection Probe components related to its visual appearance.
    • Colliders providing collisions and the ability to move on roads.
    • Sensors providing data related to the state of the vehicle, including its position and speed in Environment and the state of its surroundings.
    • Vehicle component that simulates dynamics, controls **Wheel and is responsible for ensuring their movement.
    • Vehicle Ros Input and Vehicle Keyboard Inputcomponents that have a reference to the Vehicle object and set control commands in it.
    • Vehicle Visual Effect provides an interface for Vehicle to control the lighting.

    A detailed description of EgoVehicle and its components mentioned above can be found here. The sensor placement on EgoVehicle used in the default scene is described here. Details about each of the individual sensors are available in the following sections: Pose, GNSS, LiDAR, IMU, Camera, Vehicle Status.

    "},{"location":"Introduction/AWSIM/#fixedupdate-limitation","title":"FixedUpdate Limitation","text":"

    In AWSIM, the sensors' publishing methods are triggered from the FixedUpdate function and the output frequency is controlled by:

    time += Time.deltaTime;\nvar interval = 1.0f / OutputHz;\ninterval -= 0.00001f; // Allow for accuracy errors.\nif (time < interval)\n    return;\ntimer = 0;\n

    Since this code runs within the FixedUpdate method, it's essential to note that Time.deltaTime is equal to Fixed Timestep, as stated in the Unity Time.deltaTime documentation. Consequently, with each invocation of FixedUpdate, the time variable in the sensor script will increment by a constant value of Fixed Timestep, independent of the actual passage of real-time. Additionally, as outlined in the Unity documentation, the FixedUpdate method might execute multiple times before the Update method is called, resulting in extremely small time intervals between successive FixedUpdate calls. The diagram below illustrates the mechanism of invoking the FixedUpdate event function.\"

    During each frame (game tick) following actions are performed:

    • first, the Delta Time is calculated as the difference between the current frame and the previous frame,
    • next, the Delta Time is added to the Time (regular time),
    • afterward, a check is made to determine how much Fixed Time (physics time) is behind the Time,
    • if the difference between Time and Fixed Time is equal to or greater then Fixed Timestep, the Fixed Update event function is invoked,
    • if FixedUpdate function were called, the Fixed Timestep is added to the Fixed Time,
    • once again, a check is performed to assess how much Fixed Time is behind the Time,
    • if necessary, the FixedUpdate function is called again,
    • if the difference between the Time and the Fixed Time is smaller than the Fixed Timestep, the Update method is called, followed be scene rendering and other Unity event functions.

    As a consequence, this engine feature may result in unexpected behavior when FPS (Frames Per Second) are unstable or under certain combinations of FPS, Fixed Timestep, and sensor OutputHz

    In case of low frame rates, it is advisable to reduce the Time Scale of the simulation. The Time Scale value impacts simulation time, which refers to the time that is simulated within the model and might or might not progress at the same rate as real-time. Therefore, by reducing the time scale, the progression of simulation time slows down, allowing the simulation more time to perform its tasks.

    "},{"location":"Introduction/Autoware/","title":"Autoware","text":""},{"location":"Introduction/Autoware/#autoware","title":"Autoware","text":"

    Autoware is an open-source software platform specifically designed for autonomous driving applications. It was created to provide a comprehensive framework for developing and testing autonomous vehicle systems. Autoware offers a collection of modules and libraries that assist in various tasks related to perception, planning, and control, making it easier for researchers and developers to build autonomous driving systems.

    The primary purpose of Autoware is to enable the development of self-driving technologies by providing a robust and flexible platform. It aims to accelerate the research and deployment of autonomous vehicles by offering a ready-to-use software stack. Autoware focuses on urban driving scenarios and supports various sensors such as LiDAR, Radars, and Cameras, allowing for perception of the vehicle's surroundings.

    "},{"location":"Introduction/Autoware/#why-use-awsim-with-autoware","title":"Why use AWSIM with Autoware?","text":"

    Autoware can be used with a AWSIM for several reasons. Firstly, simulators like AWSIM provide a cost-effective and safe environment for testing and validating autonomous driving algorithms before deploying them on real vehicles. Autoware's integration with a simulator allows developers to evaluate and fine-tune their algorithms without the risk of real-world accidents or damage.

    Additionally, simulators enable developers to recreate complex driving scenarios, including difficult conditions or rare events, which may be difficult to replicate in real-world testing with such high fidelity. Autoware's compatibility with a AWSIM allows seamless integration between the software and the simulated vehicle, enabling comprehensive testing and validation of autonomous driving capabilities. By utilizing a simulator, Autoware can be extensively tested under various scenarios to ensure its robustness and reliability.

    Connection with Autoware

    Introduction about how the connection between AWSIM and Autoware works can be read here.

    "},{"location":"Introduction/Autoware/#architecture","title":"Architecture","text":"

    In terms of architecture, Autoware follows a modular approach. It consists of multiple independent modules that communicate with each other through a ROS2. This modular structure allowing users to select and combine different modules based on their specific needs and requirements. The software stack comprises multiple components, including perception, localization, planning, and control modules. Here's a brief overview of each module:

    • Sensing - acquires data from sensors different sensors mounted on the autonomous vehicle such as LiDARs, GNSS, IMU and cameras. It pre-processing received data in order to later extract relevant information about the surrounding environment through the Perception module or about vehicle location by the Localization module. More details here.
    • Perception - performs advanced processing of sensor data (LiDARs, cameras) to extract meaningful information about the surrounding environment. It performs tasks like object detection (other vehicles, pedestrians), lane detection, and traffic lights recognition. More details here.
    • Localization - performs a fusion of data from Sensing module like LiDAR, GNSS, IMU, and odometry sensors to estimate the vehicle's position and orientation accurately. More details here.
    • Planning - generates a safe and feasible trajectory for the autonomous vehicle based on the information gathered from Perception and Localization. It also takes into account various factors from Map like traffic rules and road conditions. More details here.
    • Control - executes the planned trajectory by sending commands to the vehicle's actuators, such as steering, throttle, and braking. It ensures that the vehicle follows the desired trajectory while maintaining safety and stability. More details here.
    • Vehicle Interface - is a crucial component that enables communication and interaction between Autoware software system and a vehicle. It facilitates the exchange of control signals and vehicle information necessary for autonomous driving operations. The vehicle interface ensures that Autoware can send commands to the vehicle, such as acceleration, braking, and steering, while also receiving real-time data from the vehicle, such as speed, position, and sensors data. It acts as a bridge, allowing Autoware to seamlessly interface with the specific characteristics and requirements of the vehicle it is operating with. More details here.
    • Map - the map module creates and maintains a representation of the environment in which the autonomous vehicle operates. It combines data from Lanelet2 (*.osm) and PointCloud (*.pcd) to generate a detailed map. The map contains information about road geometries, lane markings, traffic lights, rules, and other relevant features. Map serves as a crucial reference for planning and decision-making processes. More details here.
    "},{"location":"Introduction/CombinationWithAutoware/","title":"CombinationWithAutoware","text":"

    Autoware is a powerful open-source software platform for autonomous driving. Its modular architecture, including perception, localization, planning, and control modules, provides a comprehensive framework for developing self-driving vehicles. Autoware combined with AWSIM simulator provides safe testing, validation, and optimization of autonomous driving algorithms in diverse scenarios.

    Run with Autoware

    If you would like to know how to run AWSIM with Autoware, we encourage you to read this section.

    "},{"location":"Introduction/CombinationWithAutoware/#features","title":"Features","text":"

    The combination of Autoware and AWSIM provides the opportunity to check the correctness of the vehicle's behavior in various traffic situations. Below are presented some typical features provided by this combination. Moreover, examples of detecting several bad behaviors are included.

    "},{"location":"Introduction/CombinationWithAutoware/#engagement","title":"Engagement","text":"

    • Driving straight through an intersection with priority

    • Turning at the intersection

    "},{"location":"Introduction/CombinationWithAutoware/#traffic-light-recognition","title":"Traffic light recognition","text":"

    • Stopping at a red light

    • Driving on a green light

    • Stopping at yellow light

    • Still driving at yellow light (only when it is too late to stop)

    "},{"location":"Introduction/CombinationWithAutoware/#interaction-with-vehicles","title":"Interaction with vehicles","text":"

    • Yield right-of-way when turning right

    • Following the vehicles ahead

    • Stopping behind the vehicles ahead

    • Cutting-in to a different traffic lane

    "},{"location":"Introduction/CombinationWithAutoware/#interaction-with-pedestrians","title":"Interaction with pedestrians","text":"

    • Giving right of way to a pedestrian crossing at a red light

    • Giving way to a pedestrian crossing beyond a crosswalk

    "},{"location":"Introduction/CombinationWithAutoware/#detecting-bad-behaviors","title":"Detecting bad behaviors","text":"

    • Incorrect and dangerous execution of a lane change

    • Too late detection of a pedestrian entering the roadway

    "},{"location":"Introduction/CombinationWithAutoware/#combination-architecture","title":"Combination Architecture","text":"

    The combination of AWSIM with Autoware is possible thanks to Vehicle Interface and Sensing modules of Autoware architecture. The component responsible for ensuring connection with these modules from the AWSIM side is EgoVehicle. It has been adapted to the Autoware architecture and provides ROS2 topic-based communication. However, the other essential component is ClockPublisher, which provides simulation time for Autoware - also published on the topic - more details here.

    EgoVehicle component provides the publication of the current vehicle status through a script working within Vehicle Status. It provides real-time information such as: current speed, current steering of the wheels or current states of lights - these are outputs from AWSIM.

    On the other hand, Vehicle Ros Input is responsible for providing the values of the outputs from Autoware. It subscribes to the current commands related to the given acceleration, gearbox gear or control of the specified lights.

    Execution of the received commands is possible thanks to Vehicle, which ensures the setting of appropriate accelerations on the **Wheel and controlling the visual elements of the vehicle.

    The remaining data delivered from AWSIM to Autoware are sensors data, which provides information about the current state of the surrounding environment and those necessary to accurately estimate EgoVehicle position.

    More about EgoVehicle and its scripts is described in this section.

    "},{"location":"Introduction/CombinationWithAutoware/#sequence-diagram","title":"Sequence diagram","text":"

    Below is a simplified sequential diagram of information exchange in connection between AWSIM and Autoware. As you can see, the first essential information published from AWSIM is Clock - the simulation time. Next, EgoVehicle is spawned and first sensors data are published, which are used in the process of automatic position initialization on Autoware side. At the same time, the simulation on AWSIM side is updated.

    Next in the diagram is the main information update loop in which:

    • During each cycle there is a synchronization with the time from the simulation.
    • AWSIM publishes data from sensors available in EgoVehicle, which are taken into account in the processes carried out in Autoware.
    • The control commands from Autoware are subscribed by AWSIM, which are executed on AWSIM side and EgoVehicle update is performed.
    • The current state of the EgoVehicle is published.

    The order of information exchange presented in the diagram is a simplification. The exchange of information takes place through the publish-subscribe model and each data is sent with a predefined frequency.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/","title":"Combination with Autoware and Scenario simulator v2","text":""},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#combination-with-autoware-and-scenario-simulator-v2","title":"Combination with Autoware and Scenario simulator v2","text":"

    Scenario Simulator v2 (SS2) is a scenario testing framework specifically developed for Autoware, an open-source self-driving software platform. It serves as a tool for Autoware developers to conveniently create and execute scenarios across different simulators.

    The primary goal of SS2 is to provide Autoware developers with an efficient means of writing scenarios once and then executing them in multiple simulators. By offering support for different simulators and scenario description formats, the framework ensures flexibility and compatibility.

    The default scenario format in this framework is TIER IV Scenario Format version 2.0. The scenario defined on this format is converted by scenario_test_runner to openSCENARIO format, which is then interpreted by openscenario_interpreter. Based on this interpretation, traffic_simulator simulates traffic flow in an urban area. Each NPC has a behavior tree and executes commands from the scenario.

    The framework uses ZeroMQ Inter-Process communication for seamless interaction between the simulator and the traffic_simulator. To ensure synchronous operation of the simulators, SS2 utilizes the Request/Reply sockets provided by ZeroMQ and exchanges binarized data through Protocol Buffers. This enables the simulators to run in a synchronized manner, enhancing the accuracy and reliability of scenario testing.

    QuickStart Scenario simulator v2 with Autoware

    If you would like to see how SS2 works with Autoware using default build-in simulator - simple_sensor_simulator (without running AWSIM) - we encourage you to read this tutorial.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#combination-architecture","title":"Combination Architecture","text":"

    AWSIM scene architecture used in combination with SS2 changes considerably compared to the default scene. Here traffic_simulator from SS2 replaces TrafficSimulator implementation in AWSIM - for this reason it and its StopLines, TrafficLanes and TrafficIntersection components are removed. Also, NPCPedestrian and NPCVehicles are not added as aggregators of NPCs in Environment.

    Instead, their counterparts are added in ScenarioSimulatorConnector object that is responsible for spawning Entities of the scenario. Entity can be: Pedestrian, Vehicle, MiscObject and Ego. EgoEntity is the equivalent of EgoVehicle - which is also removed from the default scene. However, it has the same components - it still communicates with Autoware as described here. So it can be considered that EgoVehicle has not changed and NPCPedestrians and NPCVehicles are now controlled directly by the SS2.

    A detailed description of the SS2 architecture is available here. A description of the communication via ROS2 between SS2 and Autoware can be found here.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#sequence-diagram","title":"Sequence diagram","text":"

    In the sequence diagram, the part responsible for AWSIM communication with Autoware also remained unchanged. The description available here is the valid description of the reference shown in the diagram below.

    Communication between SS2 and AWSIM takes place via Request-Response messages, and is as follows:

    1. Launch - Autoware is started and initialized.
    2. Initialize - the environment in AWSIM is initialized, basic parameters are set.
    3. opt Ego spawn - optional, EgoEntity (with sensors) is spawned in the configuration defined in the scenario.
    4. opt NPC spawn loop - optional, all Entities (NPCs) defined in the scenario are spawned, the scenario may contain any number of each Entity type, it may not contain them at all or it may also be any combination of the available ones.
    5. update loop - this is the main loop where scenario commands are executed, first EgoEntity is updated - SS2 gets its status, and then every other Entity is updated - the status of each NPCs is set according to the scenario. Next, the simulation frame is updated - here the communication between Autoware and AWSIM takes place. The last step of the loop is to update the traffic light state.
    6. despawn loop - after the end of the scenario, all Entities spawned on the scene are despawned (including EgoEnity)
    7. Terminate - Autoware is terminated.

    Documentation of the commands used in the sequence is available here.

    "},{"location":"ProjectGuide/Directory/","title":"Directory","text":""},{"location":"ProjectGuide/Directory/#directory","title":"Directory","text":"

    AWSIM has the following directory structure. Mostly they are grouped by file type.

    AWSIM       //  root directory.\n \u2502\n \u2502\n \u251c\u2500Assets                           // Unity project Assets directory.\n \u2502  \u2502                               // Place external libraries\n \u2502  \u2502                               // under this directory.\n \u2502  \u2502                               // (e.g. RGLUnityPlugin, ROS2ForUnity, etc..)\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u251c\u2500AWSIM                         // Includes assets directly related to AWSIM\n \u2502  |                               // (Scripts, Prefabs etc.)\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Externals                  // Place for large files or\n \u2502  \u2502  |                            // external project dependencies\n \u2502  \u2502  |                            // (e.g. Ninshinjuku map asset).\n \u2502  \u2502  \u2502                            // The directory is added to `.gitignore`\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500HDRPDefaultResources       // Unity HDRP default assets.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Materials                  // Materials used commonly in Project.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Models                     // 3D models\n \u2502  \u2502  \u2502  \u2502                         // Textures and materials for 3D models\n \u2502  \u2502  \u2502  \u2502                         // are also included.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2514\u2500<3D Model>              // Directory of each 3D model.\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u251c\u2500Materials            // Materials used in 3D model.\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2514\u2500Textures             // Textures used in 3D model.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Prefabs                    // Prefabs not dependent on a specific scene.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Scenes                     // Scenes\n \u2502  \u2502  \u2502  \u2502                         // Includes scene-specific scripts, etc.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u251c\u2500Main                    // Scenes used in the simulation.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2514\u2500Samples                 // Sample Scenes showcasing components.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2514\u2500Scripts                    // C# scripts.\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u251c\u2500RGLUnityPlugin        // Robotec GPU LiDAR external Library.\n \u2502  \u2502                       // see: https://github.com/RobotecAI/RobotecGPULidar\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u2514\u2500Ros2ForUnity          // ROS2 communication external Library.\n \u2502                          // see: https://github.com/RobotecAI/ros2-for-unity\n \u2502\n \u251c\u2500Packages         // Unity automatically generated directories.\n \u251c\u2500ProjectSettings  //\n \u251c\u2500UserSettings     //\n \u2502\n \u2502\n \u2514\u2500docs             // AWSIM documentation. Generated using mkdocs.\n                    // see: https://www.mkdocs.org/\n
    "},{"location":"ProjectGuide/ExternalLibraries/","title":"External Libraries","text":""},{"location":"ProjectGuide/ExternalLibraries/#external-libraries","title":"External Libraries","text":"

    List of external libraries used in AWSIM.

    Library Usage URL ros2-for-unity ROS2 communication https://github.com/RobotecAI/ros2-for-unity Robtoec-GPU-LiDAR LiDAR simulation https://github.com/RobotecAI/RobotecGPULidar"},{"location":"ProjectGuide/GitBranch/","title":"Git Branch","text":""},{"location":"ProjectGuide/GitBranch/#git-branch","title":"Git branch","text":"

    The document presents the rules of branching adopted in the AWSIM development process.

    "},{"location":"ProjectGuide/GitBranch/#branches","title":"Branches","text":"branch explain main Stable branch. Contains all the latest releases. feature/*** Feature implementation branch created from main. After implementation, it is merged into main. gh-pages Documentation hosted on GitHub pages."},{"location":"ProjectGuide/GitBranch/#branch-flow","title":"Branch flow","text":"
    1. Create feature/*** branch from main.
    2. Implement in feature/*** branch.
    3. Create a PR from the feature/*** branch to main branch. Merge after review.
    "},{"location":"ProjectGuide/HotkeyList/","title":"Hotkey List","text":""},{"location":"ProjectGuide/HotkeyList/#hotkey-list","title":"Hotkey List","text":""},{"location":"ProjectGuide/HotkeyList/#vehiclekeyboardinputcs","title":"VehicleKeyboardInput.cs","text":"Key Feature D Change drive gear. P Parking gear. R Reverse gear. N Neutral gear. 1 Left turn signal. 2 Right turn signal. 3 Hazard. 4 Turn signal off. Up arrow Accelerate. Left arrow Steering (Left). Right arrow Steering (Right). Down arrow Breaking.

    W,A,S,D keys can also be used to control the vehicle, similar to the arrow keys.

    "},{"location":"ProjectGuide/HotkeyList/#followcameracs","title":"FollowCamera.cs","text":"Key Feature C Camera rotation on/off toggle. Mouse drag Rotate Camera angle. Mouse wheel Zoom in/out of camera."},{"location":"ProjectGuide/HotkeyList/#hotkeyhandlercs","title":"HotkeyHandler.cs","text":"Key Feature Esc Toggle side bar LeftCtrl + R Reset ego vehicle LeftCtrl + T Toggle traffic visibility"},{"location":"ProjectGuide/HotkeyList/#birdeyeviewcs","title":"BirdEyeView.cs","text":"Key Feature B Toggle BEV camera WASD / Arrow Keys Pan BEV camera Mouse Wheel + Drag Pan BEV camera Mouse Wheel Zoom in/out Space Snap camera to vehicle LeftCtrl + Space Follow ego vehicle on/off"},{"location":"ProjectGuide/HotkeyList/#graphy-asset","title":"Graphy Asset","text":"Key Feature F3 Toggle Graphy Visualizer"},{"location":"ProjectGuide/Scenes/","title":"Scenes","text":"

    In the AWSIM Unity project there is one main scene (AutowareSimulation) and several additional ones that can be helpful during development. This section describes the purpose of each scene in the project.

    "},{"location":"ProjectGuide/Scenes/#autowaresimulation","title":"AutowareSimulation","text":"

    The AutowareSimulation scene is the main scene that is designed to run the AWSIM simulation together with Autoware. It allows for effortless operation, just run this scene, run Autoware with the correct map file and everything should work right out of the box.

    "},{"location":"ProjectGuide/Scenes/#pointcloudmapping","title":"PointCloudMapping","text":"

    The PointCloudMapping is a scene that is designed to create a point cloud using the Unity world. Using the RGLUnityPlugin and prefab Environment - on which there are models with Meshes - we are able to obtain a *.pcd file of the simulated world.

    "},{"location":"ProjectGuide/Scenes/#sensorconfig","title":"SensorConfig","text":"

    Scene SensorConfig was developed to perform a quick test of sensors added to the EgoVehicle prefab. Replace the Lexus prefab with a vehicle prefab you developed and check whether all data that should be published is present, whether it is on the appropriate topics and whether the data is correct.

    "},{"location":"ProjectGuide/Scenes/#npcvehiclesample","title":"NPCVehicleSample","text":"

    The NPCVehicleSample was developed to conduct a quick test of the developed vehicle. Replace the taxi prefab with a vehicle prefab you developed (EgoVehicle or NPCVehicle) and check whether the basic things are configured correctly. The description of how to develop your own vehicle and add it to the project is in this section.

    "},{"location":"ProjectGuide/Scenes/#npcpedestriansample","title":"NPCPedestrianSample","text":"

    The NPCPedestrianSample was developed to conduct a quick test of the developed pedestrian. Replace the NPC prefab in NPC Pedestrian Test script with a prefab you developed and check whether the basic things are configured correctly.

    "},{"location":"ProjectGuide/Scenes/#trafficintersectionsample","title":"TrafficIntersectionSample","text":"

    The TrafficIntersectionSample was developed to conduct a quick test of the developed traffic intersection. Replace the intersection configuration with your own and check whether it works correctly. You can add additional groups of lights and create much larger, more complex sequences. A description of how to configure your own traffic intersection is in this section.

    "},{"location":"ProjectGuide/Scenes/#trafficlightsample","title":"TrafficLightSample","text":"

    The TrafficLightSample was developed to conduct a quick test of a developed traffic lights model in cooperation with the script controlling it. Replace the lights and configuration with your own and check whether it works correctly.

    "},{"location":"ProjectGuide/Scenes/#randomtrafficyielding","title":"RandomTrafficYielding","text":"

    The RandomTrafficYielding was developed to conduct a tests of a developed yielding rules at the single intersection.

    "},{"location":"ProjectGuide/Scenes/#randomtrafficyieldingbirdeye","title":"RandomTrafficYieldingBirdEye","text":"

    The RandomTrafficYielding was developed to conduct a tests of a developed yielding rules with multiple vehicles moving around the entire environment.

    "},{"location":"ProjectGuide/Scenes/#rgl-test-scenes","title":"RGL test scenes","text":"

    The scenes described below are used for tests related to the external library RGLUnityPlugin (RGL) - you can read more about it in this section.

    "},{"location":"ProjectGuide/Scenes/#lidarscenedevelop","title":"LidarSceneDevelop","text":"

    The scene LidarSceneDevelop can be used as a complete, minimalistic example of how to setup RGL. It contains RGLSceneManager component, four lidars, and an environment composed of floor and walls.

    "},{"location":"ProjectGuide/Scenes/#lidarskinnedstress","title":"LidarSkinnedStress","text":"

    The scene LidarSkinnedStress can be used to test the performance of RGL. E.g. how performance is affected when using Regular Meshes compared to Skinned Meshes. The scene contains a large number of animated models that require meshes to be updated every frame, thus requiring more resources (CPU and data exchange with GPU).

    "},{"location":"ProjectGuide/Scenes/#lidardisablingtest","title":"LidarDisablingTest","text":"

    The scene LidarDisablingTest can be used to test RGL performance with similar objects but with different configurations. It allows you to check whether RGL works correctly when various components that can be sources of Meshes are disabled (Colliders, Regular Meshes, Skinned Meshes, ...).

    "},{"location":"ProjectGuide/Scenes/#lidarinstancesegmentationdemo","title":"LidarInstanceSegmentationDemo","text":"

    The LidarInstanceSegmentationDemo is a demo scene for instance segmentation feature. It contains a set of GameObjects with ID assigned and sample lidar that publishes output to the ROS2 topic. The GameObjects are grouped to present different methods to assign IDs.

    To run demo scene:

    1. Open scene: Assets/AWSIM/Scenes/Samples/LidarInstanceSegmentationDemo.unity
    2. Run simulation
    3. Open rviz2
    4. Setup rviz2 as follows:
      • Fixed frame: world,
      • PointCloud2 topic: lidar/instance_id,
      • Topic QoS as in the screen above.
      • Channel name: enitity_id,
      • To better visualization disable Autocompute intensity and set min to 0 and max to 50.
    "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#welcome-to-awsim-labs","title":"Welcome to AWSIM Labs","text":"

    AWSIM Labs is currently being developed under the Autoware Labs initiative. Main purpose of this fork is to provide faster implementation of features needed by the users of the AWSIM while also ensuring a high-performance simulation environment for the Autoware.

    This is a fork of TIER IV's AWSIM.

    "},{"location":"#features","title":"Features","text":"
    • Many predefined components included (Vehicle dynamic models, Sensor models, Environment configuration, ROS2 communication, etc)
    • Support for Ubuntu 22.04 and windows10/11
    • ROS2 native communication (humble)
    • Open sourced
    • Made with Unity
    "},{"location":"#feature-differences-from-the-tier-ivawsim","title":"Feature differences from the TIER IV/AWSIM","text":"

    See Feature differences from the TIER IV/AWSIM in the Autoware Documentation.

    "},{"location":"#try-the-simulation-demo-yourself","title":"Try the simulation demo yourself!","text":"

    Run the AWSIM Labs demo with Autoware following the instructions in the Quick start demo.

    "},{"location":"Components/Clock/ClockPublisher/","title":"Clock Publisher","text":""},{"location":"Components/Clock/ClockPublisher/#introduction","title":"Introduction","text":"

    ClockPublisher allows the publication of the simulation time from the clock operating within AWSIM. The current time is retrived from a TimeSource object via the SimulatorROS2Node. The AWSIM provides convenient method for selecting the appropriate time source type as well as the flexibility to implement custom TimeSources tailored to specific user requirements.

    "},{"location":"Components/Clock/ClockPublisher/#setup","title":"Setup","text":"

    To enable the publication of the current time during simulation execution, ClockPublisher must be included as a component within the scene. Moreover, to allow the TimeSource to be set or changed, the TimeSourceSelector object must also be present in the active scene.

    "},{"location":"Components/Clock/ClockPublisher/#selecting-time-source","title":"Selecting Time Source","text":"

    The desired TimeSource can be selected in two ways:

    • Inspector Selection: TimeSource type can be conveniently choosen directly from the editor interface.

    • JSON Configuration File: Alternatively, the TimeSource type can be specified in the JSON configuration file via the TimeSource field. The supported values for this field can be found in the list of available time sources in the \"String Value for JSON Config\" column.

    "},{"location":"Components/Clock/ClockPublisher/#list-of-time-sources","title":"List of Time Sources","text":"Type String Value for JSON Config Description UNITY unity based on the time of the Unity Engine SS2 ss2 driven by an external source, used by the scenario simulator v2 DOTNET_SYSTEM system based on system time, starting with time since UNIX epoch, progressing according to simulation timescale DOTNET_SIMULATION simulation based on system time, starting with zero value, progressing according to simulation timescale ROS2 ros2 based on ROS2 time (system time by default)"},{"location":"Components/Clock/ClockPublisher/#architecture","title":"Architecture","text":"

    The ClockPublisher operates within a dedicated thread called the 'Clock' thread. This design choice offers significant advantages by freeing the publishing process from the constraints imposed by fixed update limits. As a result, ClockPublisher is able to consistently publish time at a high rate, ensuring stability and accuracy.

    "},{"location":"Components/Clock/ClockPublisher/#accessing-time-source","title":"Accessing Time Source","text":"

    Running the clock publisher in a dedicated thread introduced the challenge of accessing shared resources by different threads. In our case, the Main Thread and Clock Thread compete for TimeSoruce resources. The diagram below illustrates this concurrent behaviour, with two distinct threads vying for access to the TimeSource:

    • Main Thread: included publishing message by sensors (on the diagram blueish region labeled sensor loop),
    • Clock Thread: included clock publisher (on the diagram blueish region labeled clock loop).

    Given multiple sensors, each with its own publishing frequency, alongside a clock running at 100Hz, there is a notable competition for TimeSource resources. In such cases, it becomes imperative for the TimeSource class to be thread-safe.

    "},{"location":"Components/Clock/ClockPublisher/#thread-safe-time-source","title":"Thread-Safe Time Source","text":"

    The TimeSource synchronization mechanism employs a mutex to lock the necessary resource for the current thread. The sequence of actions undertaken each time the GetTime() method is called involves:

    • acquiring the lock,
    • getting the current time, e.g. system time since epoch, (this may be different for each type of time source),
    • obtaining the current simulation time-scale,
    • calculating the delta time since previous call, influenced by the time scale,
    • returning the current time,
    • releasing the lock.

    "},{"location":"Components/Clock/ClockPublisher/#extensions","title":"Extensions","text":"

    There are two additional classes used to synchronise the UnityEngine TimeAsDouble and TimeScale values between threads:

    • TimeScaleProvider: facilitates the synchronisation of the simulation time scale value across threads,
    • TimeAsDoubleProvider: provides access to the UnityEngine TimeAsDouble to the threads other than the main thread.
    "},{"location":"Components/Environment/AWSIMEnvironment/","title":"AWSIM Environment","text":""},{"location":"Components/Environment/AWSIMEnvironment/#awsim-environment","title":"AWSIM Environment","text":""},{"location":"Components/Environment/AWSIMEnvironment/#introduction","title":"Introduction","text":"

    Environment is an object that contains all the elements visible on the scene along with components that affect how they are rendered. It contains several objects aggregating static environment objects in terms of their type. Moreover, it contains elements responsible for controlling random traffic.

    Own Environment prefab

    If you would like to develop your own prefab Environment for AWSIM, we encourage you to read this tutorial.

    AutowareSimulation scene

    If you would like to see how Environment with random traffic works or run some tests, we encourage you to familiarize yourself with the AutowareSimulation scene described in this section.

    Prefab Environment is also used to create a point cloud (*.pcd file) needed to locate the EgoVehicle in the simulated AWSIM scene. The point cloud is created using the RGL plugin and then used in Autoware. We encourage you to familiarize yourself with an example scene of creating a point cloud - described here.

    Create PointCloud (*.pcd file)

    If you would like to learn how to create a point cloud in AWSIM using Environment prefab, we encourage you to read this tutorial.

    "},{"location":"Components/Environment/AWSIMEnvironment/#architecture","title":"Architecture","text":"

    The architecture of an Environment - with dependencies between components - is presented on the following diagram.

    "},{"location":"Components/Environment/AWSIMEnvironment/#prefabs","title":"Prefabs","text":"

    Prefabs can be found under the following path:

    Name Description Path Nishishinjuku Only stationary visual elements, no traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku.prefab Nishishinjuku RandomTraffic Stationary visual elements along with random traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku RandomTraffic.prefab Nishishinjuku Traffic Stationary visual elements along with non-random traffic Assets/AWSIM/Prefabs/Environments/Nishishinjuku Traffic.prefab

    Environment prefab

    Due to the similarity of the above prefabs, this section focuses on prefab Nishishinjuku RandomTraffic. The exact differences between Nishishinjuku RandomTraffic and Nishishinjuku Traffic will be described in the future.

    Environment name

    In order to standardize the documentation, the name Environment will be used in this section as the equivalent of the prefab named Nishishinjuku RandomTraffic.

    Nishishinjuku RandomTraffic prefab has the following content:

    As you can see it contains:

    • SJK* objects - which are aggregators for visual models.
    • RandomTrafficSimulator, TrafficIntersections, TrafficLanes, StopLines - which are responsible for random traffic of NPCVehicles.
    • NPCPedestrians - which is an aggregator of NPCPedestrian prefabs added to the scene.
    • Volume, Directional Light - which are components that affect the appearance of objects on the scene.

    All of these objects are described below in this section.

    "},{"location":"Components/Environment/AWSIMEnvironment/#visual-elements","title":"Visual elements","text":"

    Nishishinjuku RandomTraffic prefab contains many visual elements which are described here.

    "},{"location":"Components/Environment/AWSIMEnvironment/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    Nishishinjuku RandomTraffic prefab is added to the Environment object - between which there is rotation about the Oy axis by 90 degrees. This rotation is added because of the differences in coordinate alignments between the Nishishinjuku RandomTraffic prefab objects (which have been modeled as *.fbx files) and the specifics of the GridZone definition (more on this is described here).

    Object Environment is added to AutowareSimulation which is added directly to the main parent of the scene - there are no transformations between these objects.

    "},{"location":"Components/Environment/AWSIMEnvironment/#components","title":"Components","text":"

    Nishishinjuku RandomTraffic (Environment) prefab contains only one component:

    • Environment (script) - which is important for communicating with Autoware and loading elements from Lanelet2. Because it allows to define the location of the environment in relation to the world.
    "},{"location":"Components/Environment/AWSIMEnvironment/#layers","title":"Layers","text":"

    In order to enable the movement of vehicles around the environment, additional layers have been added to the project: Ground and Vehicle.

    All objects that are acting as a ground for NPCVehicles and EgoVehicle to move on have been added to Ground layer - they cannot pass through each other and should collide for the physics engine to calculate their interactions.

    For this purpose, NPCVehicles and EgoVehicle have been added to the Vehicle layer.

    In the project physics settings, it is ensured that collisions between objects in the Vehicle layer are disabled (this applies to EgoVehicle and NPCVehicles - they do not collide with each other):

    "},{"location":"Components/Environment/AWSIMEnvironment/#traffic-components","title":"Traffic Components","text":"

    Due to the specificity of the use of RandomTrafficSimulator, TrafficIntersections, TrafficLanes, StopLines objects, they have been described in a separate section Traffic Components - where all the elements necessary in simulated random traffic are presented.

    "},{"location":"Components/Environment/AWSIMEnvironment/#visual-elements-sjk","title":"Visual Elements (SJK)","text":"

    The visuals elements have been loaded and organized using the *.fbx files which can be found under the path:

    Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_optimized/Models/*\n

    Environment prefab contains several objects aggregating stationary visual elements of space by their category:

    • SJK01_P01 - contains all objects constituting the ground of the environment, these are roads and green fields - each of them contains a MeshColliders and layer set as Ground to ensure collisions with NPCVehicles and EgoVehicle.

    • SJK01_P02 - contains all road surface markings on roads added to the environment. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P03 - contains all the vertical poles added to the environment, such as lamp posts, road signs and traffic light poles. Only TrafficLight poles and PedestrianLight poles have MeshCollider added. The layer for all objects is Default.

    • SJK01_P04 - contains all barriers added to the environment, such as barriers by sidewalks. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P05 - contains all greenery added to the environment, such as trees, shrubs, fragments of greenery next to buildings. The objects of this group do not have MeshColliders and their layer is Default.

    • SJK01_P06 - contains all buildings added to the environment. Objects of this category also have a MeshCollider added, but their layer is Default.

    Scene Manager

    For models (visual elements) added to the prefab to work properly with the LidarSensor sensor using RGL, make sure that the SceneManager component is added to the scene - more about it is described in this section.

    In the scene containing Nishishinjuku RandomTrafficprefab Scene Manager (script) is added as a component to the AutowareSimulation object containing the Environment.

    "},{"location":"Components/Environment/AWSIMEnvironment/#trafficlights","title":"TrafficLights","text":"

    TrafficLights are a stationary visual element belonging to the SJK01_P03 group. The lights are divided into two types, the classic TrafficLights used by vehicles at intersections and the PedestrianLights found at crosswalks.

    Classic traffic lights are aggregated at object TrafficLightA01_Root01_ALL_GP01

    while lights used by pedestrians are aggregated at object TrafficLightB01_Root01_All_GP01.

    TrafficLights and PedestrianLights are developed using models available in the form of *.fbx files, which can be found under the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Models/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#classic-trafficlights","title":"Classic TrafficLights","text":"

    TrafficLights lights, outside their housing, always contain 3 signaling light sources of different colors - from left to right: green, yellow, red. Optionally, they can have additional sources of signaling the ability to drive in a specific direction in the form of one or three signaling arrows.

    In the environment there are many classic lights with different signaling configurations. However, each contains:

    • Transform - defines the position of the lights in the environment relative to the main parent of the group (SJK01_P03).
    • Mesh Filter - contains a reference to the Mesh of the object.
    • Mesh Renderer - enables the rendering of Mesh, including its geometry, textures, and materials, giving it a visual appearance in the scene.
    • Mesh Collider - allows an object to have collision detection based on Mesh.
    • Traffic Light (script) - provides an interface to control signaling by changing the emission of materials. This script is used for simulated traffic, so it is described.
    "},{"location":"Components/Environment/AWSIMEnvironment/#materials","title":"Materials","text":"

    An important element that is configured in the TrafficLights object are the materials in the Mesh Renderer component. Material with index 0 always applies to the housing of the lights. Subsequent elements 1-6 correspond to successive slots of light sources (round luminous objects) - starting from the upper left corner of the object in the right direction, to the bottom and back to the left corner. These indexes are used in script Traffic Light (script) - described here.

    Materials for lighting slots that are assigned in Mesh Renderer can be found in the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Materials/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#pedestrianlights","title":"PedestrianLights","text":"

    PedestrianLights lights, outside their housing, always contain 2 signaling light sources of different colors - red on top and green on the bottom.

    In the environment there are many pedestrian lights - they have the same components as classic TrafficLights, but the main difference is the configuration of their materials.

    "},{"location":"Components/Environment/AWSIMEnvironment/#materials_1","title":"Materials","text":"

    An important element that is configured in the PedestrianLights object are the materials in the Mesh Renderer component. Material with index 0 always applies to the housing of the lights. Subsequent elements 1-2 correspond to successive slots of light sources (round luminous objects) - starting from top to bottom. These indexes are used in script Traffic Light (script) - described here.

    Materials for lighting slots that are assigned in Mesh Renderer can be found in the following path: Assets/AWSIM/Externals/Nishishinjuku/Nishishinjuku_opimized/Models/TrafficLights/Materials/*

    "},{"location":"Components/Environment/AWSIMEnvironment/#volume","title":"Volume","text":"

    Volume is GameObject with Volume component which is used in the High Definition Render Pipeline (HDRP). It defines a set of scene settings and properties. It can be either global, affecting the entire scene, or local, influencing specific areas within the scene. Volumes are used to interpolate between different property values based on the Camera's position, allowing for dynamic changes to environment settings such as fog color, density, and other visual effects.

    In case of prefab Nishishinjuku RandomTraffic volume works in global mode and has loaded Volume profile. This volume profile has a structure that overrides the default properties of Volume related to the following components: Fog, Shadows, Ambient Occlusion, Visual Environment, HDRI Sky. It can be found in the following path: Assets/AWSIM/Prefabs/Environments/Nishishinjuku/Volume Profile.asset

    "},{"location":"Components/Environment/AWSIMEnvironment/#directional-light","title":"Directional Light","text":"

    Directional Light is GameObject with Light component which is used in the High Definition Render Pipeline (HDRP). It controls the shape, color, and intensity of the light. It also controls whether or not the light casts shadows in scene, as well as more advanced settings.

    In case of prefab Nishishinjuku RandomTraffic a Directional type light is added. It creates effects that are similar to sunlight in scene. This light illuminates all GameObjects in the scene as if the light rays are parallel and always from the same direction. Directional light disregards the distance between the Light itself and the target, so the light does not diminish with distance. The strength of the Light (Intensity) is set to 73123.09 Lux. In addition, a Shadow Map with a resolution of 4096 is enabled, which is updated in Every Frame of the simulation. The transform of the Directional Light object is set in such a way that it shines on the environment almost vertically from above.

    "},{"location":"Components/Environment/AWSIMEnvironment/#npcpedestrians","title":"NPCPedestrians","text":"

    NPCPedestrians is an aggregating object for NPCPedestrian objects placed in the environment. Prefab Nishishinjuku RandomTraffic has 7 NPCPedestrian (humanElegant) prefabs defined in selected places. More about this NPCPedestrian prefab you can read in this section.

    "},{"location":"Components/Environment/AWSIMEnvironment/#environment-script","title":"Environment (script)","text":"

    Environment (script) contains the information about how a simulated Environment is positioned in real world. That means it describes what is the real world position of a simulated Environment.

    AWSIM uses part of a Military Grid Reference System (MGRS). To understand this topic, you only need to know, that using MGRS you can specify distinct parts of the globe with different accuracy. For AWSIM the chosen accuracy is a 100x100 km square. Such a square is identified with a unique code like 54SUE (for more information on Grid Zone please see this page).

    Inside this Grid Zone the exact location is specified with the offset calculated from the bottom-left corner of the Grid Zone. You can interpret the Grid Zone as a local coordinate system in which you position the Environment.

    In the Nishishinjuku RandomTraffic prefab, the simulated Environment is positioned in the Grid Zone 54SUE. The offset if equal to 81655.73 meters in the Ox axis, 50137.43 meters in the Oy axis and 42.49998 meters in the Oz axis. In addition to this shift, it is also necessary to rotate the Environment in the scene by 90 degrees about the Oy axis - this is ensured by the transform in the prefab object.

    This means that the 3D models were created in reference to this exact point and because of that the 3D models of Environment align perfectly with the data from Lanelet2.

    The essence of Environment (script)

    The Environment (script) configuration is necessary at the moment of loading data from Lanelet2.

    Internally it shifts the elements from Lanelet2 by the given offset so that they align with the Environment that is located at the local origin with no offset.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/","title":"Add Environment","text":""},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#add-an-environment","title":"Add an Environment","text":"

    Environment is an important part of a Scene in AWSIM. Every aspect of the simulated surrounding world needs to be included in the Environment prefab - in this section you will learn how to develop it. However, first Lanelet2 needs to be developed along with 3D models of the world, which will be the main elements of this prefab.

    Tip

    If you want to learn more about the Environment at AWSIM, please visit this page.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-a-lanelet2","title":"Create a Lanelet2","text":"

    Before you start creating Lanelet2, we encourage you to read the documentation to find out what Lanelet2 is all about. Lanelet2 can be created using VectorMapBuilder (VMP) based on the PCD obtained from real-life LiDAR sensor.

    When working with the VMP, it is necessary to ensure the most accurate mapping of the road situation using the available elements. Especially important are TrafficLanes created in VMB as connected Road Nodes and StopLines created in VMB as Road Surface Stoplines.

    Lanelet2 positioning

    Lanelet2 should be created in MGRS coordinates of the real place you are recreating. Please position your Lanelet2 relative to the origin (bottom left corner) of the MGRS Grid Zone with the 100 km Square ID in which the location lays. More details can be read here.

    You can think of the Grid Zone as a local coordinate system. Instead of making global (0,0) point (crossing of Equator and Prime Median) our coordinate system origin we take a closer one. The MGRS Grid Zone with 100 km Square ID code designates a 100x100 [kmxkm] square on the map and we take its bottom left corner as our local origin.

    Example

    Lets examine one node from an example Lanelet2 map:

    <node id=\"4\" lat=\"35.68855194431519\" lon=\"139.69142711058254\">\n    <tag k=\"mgrs_code\" v=\"54SUE815501\"/>\n    <tag k=\"local_x\" v=\"81596.1357\"/>\n    <tag k=\"local_y\" v=\"50194.0803\"/>\n    <tag k=\"ele\" v=\"34.137\"/>\n</node>\n

    The node with id=\"4\" position is described as absolute coordinates given in the <node>. In this example the coordinates are as follows lat=\"35.68855194431519\" lon=\"139.69142711058254.

    It is also described as local transformation defined as a translation relative to the origin of the MGRS Grid Zone with 100 km Square ID (bottom left corner). The MGRS Grid Zone designation with 100 km Square ID in this case is equal to 54SUE. In this example the offset in the X axis is as follows k=\"local_x\" v=\"81596.1357\" and the offset in the Y axis is as follows k=\"local_y\" v=\"50194.0803\".

    Note that elevation information is also included.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-3d-models","title":"Create 3D models","text":"

    You can create 3D models of an Environment as you wish. It is advised however, to prepare the models in form of .fbx files. Additionally you should include materials and textures in separate directories. Many models are delivered in this format. This file format allows you to import models into Unity with materials and replace materials while importing. You can learn more about it here.

    You can see a .fbx model added and modified on the fly in the example of this section.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#guidelines","title":"Guidelines","text":"

    To improve the simulation performance of a scene containing your Environment prefab, please keep in mind some of these tips when creating 3D models:

    1. Prefer more smaller models over a few big ones.

      In general it is beneficial for performance when you make one small mesh of a object like tree and reuse it on the scene placing many prefabs instead of making one giant mesh containing all trees on the given scene. It is beneficial even in situations when you are not reusing the meshes. Lets say you have a city with many buildings - and every one of those buildings is different - it is still advised to model those building individually and make them separate GameObjects.

    2. Choose texture resolution appropriately.

      Always have in mind what is the target usage of your texture. Avoid making a high resolution texture for a small object or the one that will always be far away from the camera. This way you can save some computing power by not calculating the details that will not be seen because of the screen resolution.

      Practical advice

      You can follow these simple rules when deciding on texture quality (texel density):

      • For general objects choose 512px/m (so the minimum size of texture is 512/512)
      • For important objects that are close to the camera choose 1024px/m (so the minimum size of texture is 1024/1024)

    3. (optional) Add animation.

      Add animations to correct objects. If some element in the 3D model are interactive they should be divided into separate parts.

    What's more, consider these tips related directly to the use of 3D models in AWSIM:

    1. Creating a 3D model based on actual point cloud data makes it more realistic.
    2. AWSIM is created using HDRP (High Definition Rendering Pipeline) which performs better when object meshes are merged.
    3. Occlusion culling and flutter culling cannot be used because the sensors detection target will disappear.
    4. Each traffic light should have a separate GameObject. Also, each light in the traffic light should be split into separate materials.
    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#create-an-environment-prefab","title":"Create an Environment prefab","text":"

    In this part, you will learn how to create a Environment prefab - that is, develop a GameObject containing all the necessary elements and save it as a prefab.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#1-add-3d-models","title":"1. Add 3D models","text":"

    In this section we will add roads, buildings, greenery, signs, road markings etc. to our scene.

    Most often your models will be saved in the .fbx format. If so, you can customize the materials in the imported model just before importing it. Sometimes it is necessary as models come with placeholder materials. You can either

    • replace materials for every added GameObject into the Scene,
    • or replace materials for one GameObject and save this object as a prefab to easily load it later.

    In order to add 3D models from the .fbx file to the Scene please do the following steps:

    1. In the Project view navigate to the directory where the model is located and click on the model file.
    2. Now you can customize the materials used in the model in the Inspector view.
    3. Drag the model into the Scene where you want to position it.
    4. Move the Object in the Hierarchy tree appropriately.
    5. (optional) Now you can save this model configuration as a prefab to easily reuse it. Do this by dragging the Object from the Scene into the Project view. When you get a warning make sure to select you want to create an original new prefab.

    Example

    An example video of the full process of importing a model, changing the materials, saving new model as a prefab and importing the new prefab.

    When creating a complex Environment with many elements you should group them appropriately in the Hierarchy view. This depends on the individual style you like more, but it is a good practice to add all repeating elements into one common Object. E.g. all identical traffic lights grouped in TrafficLights Object. The same can be done with trees, buildings, signs etc. You can group Objects as you like.

    Object hierarchy

    When adding elements to the Environment that are part of the static world (like 3D models of buildings, traffic lights etc.) it is good practice to collect them in one parent GameObject called Map or something similar.

    By doing this you can set a transformation of the parent GameObject Map to adjust the world pose in reference to e.g. loaded objects from Lanelet2.

    Remember to unpack

    Please remember to unpack all Object added into the scene. If you don't they will change materials together with the .fbx model file as demonstrated in the example below.

    This is unwanted behavior. When you import a model and change some materials, but leave the rest default and don't unpack the model, then your instances of this model on the scene may change when you change the original fbx model settings.

    See the example below to visualize what is the problem.

    Example

    In this example we will

    • Place the model on the Scene.
    • Then intentionally not unpack the model
    • Only then change the materials of the original fbx model, not the instance on the scene

    Watch what happens, the instance on the Scene changes the materials together with the model. This only happens if you don't unpack the model.

    Example Environment after adding 3D models

    After completing this step you should have an Environment Object that looks similar to the one presented below.

    The Environment with 3D models can look similar to the one presented below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#2-add-an-environment-script","title":"2. Add an Environment Script","text":"

    Add an Environment Script as component in the Environment object (see the last example in section before). It does not change the appearance of the Environment, but is necessary for the simulation to work correctly.

    1. Click on the Add Component button in the Environment object.

    2. Search for Environment and select it.

    3. Set the MGRS to the offset of your Environment as explained in this section.

    Info

    Due to the differences between VectorMapBuilder and Unity, it may be necessary to set the transform of the Environment object. The transform in Environment should be set in such a way that the TrafficLanes match the modeled roads. Most often it is necessary to set the positive 90 degree rotation over Y axis.

    This step should be done after importing items from lanelet2. Only then will you know if you have Environment misaligned with items from lanelet2.

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#3-add-a-directional-light","title":"3. Add a Directional Light","text":"

    1. Create a new child Object of the Environment and name it Directional Light.

    2. Click Add Component button, search for Light and select it.

    3. Change light Type to Directional.

    4. Now you can configure the directional light as you wish. E.g. change the intensity or orientation.

    Tip

    For more details on lighting check out official Unity documentation.

    Example Environment after adding Directional Light

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#4-add-a-volume","title":"4. Add a Volume","text":"

    1. Create a new child object of the Environment and name it Volume.

    2. Click Add Component search for Volume and select it.

    3. Change the Profile to Volume Profile and wait for changes to take effect.

    4. Now you can configure the Volume individually as you wish.

    Tip

    For more details on volumes checkout official Unity documentation.

    Example Environment after adding Volume

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#5-add-npcpedestrians","title":"5. Add NPCPedestrians","text":"

    1. Make NPCPedestrians parent object.

    2. Open Assets/AWSIM/Prefabs/NPCs/Pedestrians in Project view and drag a humanElegant into the NPCPedestrians parent object.

    3. Click Add Component in the humanElegant object and search for Simple Pedestrian Walker Controller Script and select it.

      This is a simple Script that makes the pedestrian walk straight and turn around indefinitely. You can configure pedestrian behavior with 2 parameters.

      • Duration - how long will the pedestrian walk straight
      • Speed - how fast will the pedestrian walk straight

      Tip

      The Simple Pedestrian Walker Controller Script is best suited to be used on pavements.

    4. Finally position the NPCPedestrian on the scene where you want it to start walking.

      Warning

      Remember to set correct orientation, as the NPCPedestrian will walk straight from the starting position with the starting orientation.

    Example Environment after adding NPC Pedestrians

    "},{"location":"Components/Environment/AddNewEnvironment/AddEnvironment/#6-save-an-environment-prefab","title":"6. Save an Environment prefab","text":"

    After doing all the previous steps and having your Environment finished you can save it to prefab format.

    1. Find an Environments directory in the Project view (Assets/AWSIM/Prefabs/Environments).
    2. Drag the Environment Object into the Project view.
    3. (optional) Change the prefab name to recognize it easily later.

    Success

    Once you've added the Environment, you need to add and configure TrafficLights. For details please visit this tutorial.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/","title":"Add Random Traffic","text":"

    To add a Random Traffic to your scene you need the Random Traffic Simulator Script.

    1. Create a new Game Object as a child of Environment and call it RandomTrafficSimulator.

    2. Click a button Add Component in the Inspector to add a script.

    3. A small window should pop-up. Search for RandomTrafficSimulator script and add it by double clicking it or by pressing enter.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#basic-configuration","title":"Basic Configuration","text":"

    After clicking on the newly created RandomTrafficSimulator object in the Scene tree you should see something like this in the Inspector view.

    Random Traffic Simulator, as the name suggests, generates traffic based on random numbers. To replicate situations you can set a specific seed.

    You can also set Vehicle Layer Mask and Ground Layer Mask. It is important to set these layers correctly, as they are a base for vehicle physics. If set incorrectly the vehicles may fall through the ground into the infinity.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#add-npcvehicles","title":"Add NPCVehicles","text":"

    Random Traffic Simulator Script moves, spawns and despawns vehicles based on the configuration. These settings can to be adjusted to your preference.

    1. Setting Max Vehicle Count.

      This parameter sets a limit on how many vehicles can be added to the scene at one time.

    2. NPC Prefabs

      These are models of vehicles that should be spawned on the scene, to add NPC Prefabs please follow these steps:

      1. To do this click on the \"+\" sign and in the new list element at the bottom and click on the small icon on the right to select a prefab.

      2. Change to the Assets tab in the small windows that popped-up.

      3. Search for the Vehicle prefab you want to add, e.g. Hatchback.

      Available NPC prefabs are shown in the NPC Vehicle section.

      Control NPC Vehicle spawning

      Random Traffic Simulator Script will on random select one prefab from Npc Prefabs list every time when there are not enough vehicles on the scene (the number of vehicles on the scene is smaller than the number specified in the Max Vehicle Count field).

      You can control the odds of selecting one vehicle prefab over another by adding more than one instance of the same prefab to this list.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#add-spawnable-lanes","title":"Add spawnable lanes","text":"

    Spawnable lanes are the lanes on which new vehicles can be spawned by the Random Traffic Simulator Script. Best practice is to use beginnings of the lanes on the edges of the map as spawnable lanes.

    Warning

    Make sure you have a lanelet added into your scene. The full tutorial on this topic can be found here.

    Adding spawnable lanes is similar to Adding NPC Prefabs.

    1. Add an element to the Spawnable Lanes list by clicking on the \"+\" symbol or by selecting number of lanes directly.

    2. Now you can click on the small icon on the right of the list element and select a Traffic Lane you are interested in.

      Unfortunately all Traffic Lanes have the same names so it can be difficult to know which one to use. Alternatively you can do the following to add a traffic lane by visually selecting it in the editor:

      • Lock RandomTrafficSimulator in the Inspector view.

      • Select the Traffic Lane you are interested in on the Scene and as it gets highlighted in the Hierarchy view you can now drag and drop this Traffic Lane into the appropriate list element.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddRandomTraffic/#vehicles-configuration","title":"Vehicles configuration","text":"

    The last thing to configure is the behavior of NPCVehicles. You can specify acceleration rate of vehicles and three values of deceleration.

    • Acceleration

      This value is used for every acceleration the vehicle performs (after stop line or traffic lights).

    • Deceleration

      This deceleration value is used for most casual traffic situations like slowing down before stop line.

    • Sudden Deceleration

      This deceleration rate is used for emergency situations - when using standard deceleration rate is not enough to prevent some accident from happening (e.g. vehicle on the intersection didn't give way when it was supposed to).

    • Absolute Deceleration

      This deceleration rate is a last resort for preventing a crash from happening. When no other deceleration is enough to prevent an accident this value is used. This should be set to the highest value achievable by a vehicle.

    Question

    This configuration is common for all vehicles managed by the Random Traffic Simulator Script.

    Success

    The last thing that needs to be done for RandomTraffic to work properly is to add intersections with traffic lights and configure their sequences. Details here.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/","title":"Add Traffic Intersection","text":"

    Every TrafficIntersection on the scene needs to be added as a GameObject. Best practice is to create a parent object TrafficIntersections and add all instances of TrafficIntersection as its children. You can do this the same as with Random Traffic Simulator.

    Traffic Lights configuration

    Before performing this step, check all TrafficLights for correct configuration and make sure that TrafficLights have added scripts. If you want to learn how to add and configure it check out this tutorial.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#add-a-box-collider","title":"Add a Box Collider","text":"

    1. TrafficIntersection needs to be marked with a box collider. First click on the Add Component button.

    2. In the window that popped up search for Box Collider and select it.

    3. Then set the position and orientation and size of the Box Collider. You can do this by manipulating Box Collider properties Center and Size in the Inspector view.

      Traffic Intersection Box Collider guidelines

      When adding a Box Collider marking your Traffic Intersection please make sure that

      • It is not floating over the ground - there is no gap between the Box Collider and The Traffic Intersection
      • It is high enough to cover all Vehicles that will be passing through the Intersection
      • It accurately represents the shape, position and orientation of the Traffic Intersection
    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#add-a-traffic-intersection-script","title":"Add a Traffic Intersection Script","text":"

    1. Click on the Add Component button.

    2. In the window that popped up search for Traffic Intersection and select it.

    3. You need to set a proper Collider Mask in order for the script to work.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#create-traffic-light-groups","title":"Create traffic light groups","text":"

    Traffic Light Groups are groups of traffic lights that are synchronized, meaning they light up with the same color and pattern at all times.

    Traffic lights are divided into groups to simplify the process of creating a lighting sequence. By default you will see 4 Traffic Light Groups, you can add and remove them to suit your needs.

    1. First choose from the drop-down menu called Group the Traffic Light Group name you want to assign to your Traffic Light Group.

    2. Then add as many Traffic Lights as you want your group to have. From the drop-down menu select the Traffic Lights you want to add.

      Select Traffic Lights visually

      If you have a lot of Traffic Lights it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#create-lighting-sequences","title":"Create lighting sequences","text":"

    Lighting Sequences is a list of commands based on which the Traffic Lights will operate on an intersection. The elements in the Lighting Sequences list are changes (commands) that will be executed on the Traffic Light Groups.

    Group Lighting Order should be interpreted as a command (or order) given to all Traffic Lights in selected Traffic Light Group. In Group Lighting Orders you can set different traffic light status for every Traffic Light Group (in separate elements). Lighting sequences list is processed in an infinite loop.

    It should be noted that changes applied to one Traffic Light Group will remain the same until the next Group Lighting Order is given to this Traffic Light Group. This means that if in one Group Lighting Order no command is sent to a Traffic Light Group then this Group will remain its current lighting pattern (color, bulb and status).

    For every Lighting Sequences Element you have to specify the following

    1. Interval Sec

      This is the time for which the sequence should wait until executing next order, so how long this state will be active.

    2. For every element in Group Lighting Orders there needs to be specified

      1. Group to which this order will be applied

      2. List of orders (Bulb Data)

        In other words - what bulbs should be turned on, their color and pattern.

        • Type - What type of bulb should be turned on
        • Color - What color this bulb should have (in most cases this will be the same as color of the bulb if specified)
        • Status - How the bulb should light up (selecting SOLID_OFF is necessary only when you want to turn the Traffic Light completely off, meaning no bulb will light up)

        Note

        When applying the change to a Traffic Light

        • First all bulbs are turned off
        • Only after that changes made in the order are applied

        This means it is only necessary to supply the data about what bulbs should be turned on. E.g. you don't have to turn off a red bulb when turning on the green one.

    Warning

    The first Element in the Lighting Sequences (in most cases) should contain bulb data for every Traffic Light Group. Traffic Light Groups not specified in the first Element will not light up at the beginning of the scene.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#example","title":"Example","text":"

    Lets consider the following lighting sequence element.

    In the Lighting Sequence Element 5 we tell all Traffic Lights in the Vehicle Traffic Light Group 2 to light up their Green Bulb with the color Green and status Solid On which means that they will be turned on all the time. We also implicitly tell them to turn all other Bulbs off.

    In the same time we tell all Traffic Lights in the Pedestrian Traffic Light Group 2 to do the very same thing.

    This state will be active for the next 15 seconds, and after that Traffic Intersection will move to the next Element in the Sequence.

    Now lets consider the following Lighting Sequences Element 6.

    Here we order the Traffic Lights in the Pedestrian Traffic Light Group 2 to light up their Green Bulb with the color Green and status Flashing. We also implicitly tell them to turn all other bulbs off, which were already off from the implicit change in Element 5, so this effectively does nothing.

    Note that Lighting Sequences Element 6 has no orders for Vehicle Traffic Light Group 2. This means that Traffic Lights in the Vehicle Traffic Light Group 2 will hold on to their earlier orders.

    This state will be active for 5 seconds, which means that Traffic Lights in the Vehicle Traffic Light Group 2 will be lighting solid green for the total of 20 seconds.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/AddTrafficIntersection/#how-to-test","title":"How to test","text":"

    To test how your Traffic Intersection behaves simply run the Scene as shown here (but don't launch Autoware). To take a better look at the Traffic Lights you can change to the Scene view by pressing ctrl + 1 - now you can move the camera freely (to go back to the Game view simply press ctrl + 2).

    As the time passes you can examine whether your Traffic Intersection is configured correctly.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/","title":"Load Items From Lanelet","text":""},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#load-items-from-lanelet2","title":"Load items from lanelet2","text":"

    To add RandomTraffic to the Environment, it is necessary to load elements from the lanelet2. As a result of loading, TrafficLanes and StopLines will be added to the scene. Details of these components can be found here.

    Warning

    Before following this tutorial make sure you have added an Environment Script and set a proper MGRS offset position. This position is used when loading elements from the lanelet2!

    1. Click on the AWSIM button in the top menu of the Unity editor and navigate to AWSIM -> Random Traffic -> Load Lanelet.

    2. In the window that pops-up select your osm file, change some Waypoint Settings to suit your needs and click Load.

      Waypoint Settings explanation

      • Resolution - resolution of resampling. Lower values provide better accuracy at the cost of processing time
      • Min Delta Length - minimum length(m) between adjacent points
      • Min Delta Angle - minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve

    3. Traffic Lanes and Stop Lanes should occur in the Hierarchy view. If they appear somewhere else in your Hierarchy tree, then move them into the Environment object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#complete-loaded-trafficlanes","title":"Complete loaded TrafficLanes","text":"

    The Traffic Lanes that were loaded should be configures accordingly to the road situation. The aspects you can configure

    • Right of way

      The right of way has to be configured so that Vehicles know how ot behave in the traffic. To configure this please visit a dedicated section in Add a Traffic Lane. After you have set right of way to all traffic lanes please follow this final step.

    • Stop Line

      Assuming you have all Stop Lines loaded from the lanelet you have to add them to the Traffic Lanes. For detailed instruction please visit a dedicated section in Add a Traffic Lane.

      If - for any reason - you don't have all the Stop Lines added, please follow this dedicated section.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#how-to-test","title":"How to test","text":"

    If you want to test your Traffic Lanes you have to try running a Random Traffic. To verify one particular Traffic Lane or Traffic Lane connection you can make a new spawnable lane next to the Traffic Lane you want to test. This way you can be sure NPCVehicles will start driving on the Traffic Lane you are interested in at the beginning.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#add-a-stopline-manually","title":"Add a StopLine manually","text":"

    When something goes wrong when loading data from lanelet2 or you just want to add another StopLine manually please do the following

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#1-add-a-gameobject","title":"1. Add a GameObject","text":"

    Add a new GameObject StopLine in the StopLines parent object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#2-add-a-stopline-script","title":"2. Add a StopLine Script","text":"

    Add a StopLine Script by clicking 'Add Component' and searching for Stop Line.

    Example

    So far your Stop Line should look like the following

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#3-set-points","title":"3. Set points","text":"

    Set the position of points Element 0 and Element 1. These Elements are the two end points of a Stop Line. The Stop Line will span between these points.

    You don't need to set any data in the 'Transform' section as it is not used anyway.

    StopLine coordinate system

    Please note that the Stop Line Script operates in the global coordinate system. The transformations of StopLine Object and its parent Objects won't affect the Stop Line.

    Example

    In this example you can see that the Position of the Game Object does not affect the position and orientation of the Stop Line.

    For a Game Object in the center of the coordinate system.

    The stop Line is in the specified position.

    However with the Game Object shifted in X axis.

    The Stop Line stays in the same position as before, not affected by any transformations happening to the Game Object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#4-has-stop-sign","title":"4. Has Stop Sign","text":"

    Select whether there is a Stop Sign.

    Select the Has Stop Sign tick-box confirming that this Stop Line has a Stop Sign. The Stop Sign can be either vertical or horizontal.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#5-select-a-traffic-light","title":"5. Select a Traffic Light","text":"

    Select from the drop-down menu the Traffic Light that is on the Traffic Intersection and is facing the vehicle that would be driving on the Traffic Lane connected with the Stop Line you are configuring.

    In other words select the right Traffic Light for the Lane on which your Stop Line is placed.

    Select Traffic Lights visually

    If you have a lot of Traffic Lights it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#6-configure-the-traffic-lane","title":"6. Configure the Traffic Lane","text":"

    Every Stop Line has to be connected to a Traffic Lane. This is done in the Traffic Lane configuration. For this reason please check the Traffic Lane section for more details.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#add-a-trafficlane-manually","title":"Add a TrafficLane manually","text":"

    It is possible that something may go wring when reading a lanelet2 and you need to add an additional Traffic Lane or you just want to add it. To add a Traffic Lane manually please follow the steps below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#1-add-a-gameobject_1","title":"1. Add a GameObject","text":"

    Add a new Game Object called TrafficLane into the TrafficLanes parent Object.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#2-add-a-traffic-lane-script","title":"2. Add a Traffic Lane Script","text":"

    Click the 'Add Component' button and search for the Traffic lane script and select it.

    Example

    So far your Traffic Lane should look like the following.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#3-configure-waypoints","title":"3. Configure Waypoints","text":"

    Now we will configure the 'Waypoints' list. This list is an ordered list of nest points defining the Traffic Lane. When you want to add a waypoint to a Traffic Lane just click on the + button or specify the number of waypoints on the list in the field with number to the right from 'Waypoints' identifier.

    The order of elements on this list determines how waypoints are connected.

    Traffic Lane coordinate system

    Please note that the Traffic Lane waypoints are located in the global coordinate system, any transformations set to a Game Object or paren Objects will be ignored.

    This behavior is the same as with the Stop Line. You can see the example provided in the Stop Line tutorial.

    General advice

    • Two waypoints should not be too far away from each other.
    • When creating a turn that is a curvature please keep in mind the angle that is created between two next waypoints connected. The angles should be fairly small - this will translate to a smooth motion of vehicles.
    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#4-select-the-turn-direction","title":"4. Select the Turn Direction","text":"

    You also need to select the Turn Direction. This field describes what are the vehicles traveling on ths Traffic Lane doing in reference to other Traffic Lanes. You need to select whether the vehicles are

    • Driving straight (STRAIGHT)
    • Turning right (RIGHT)
    • Turning left (LEFT)

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#5-configure-next-lanes","title":"5. Configure Next Lanes","text":"

    You need to add all Traffic Lanes that have their beginning in the end of this Traffic Lane into the Next Lanes list. In other words if the vehicle can choose where he wants to drive (e.g. drive straight or drive left with choice of two different Traffic Lines).

    To do this click the + sign in the Next Lanes list and in the element that appeared select the correct Traffic Lane.

    Next Lane example

    Lets consider the following Traffic Intersection.

    In this example we will consider the Traffic Lane driving from the bottom of the screen and turning right. After finishing driving in this Traffic Lane the vehicle has a choice of 4 different Traffic Lanes each turning into different lane on the parallel road.

    All 4 Traffic Lanes are connected to the considered Traffic Lane. This situation is reflected in the Traffic Lane configuration shown below.

    Select Traffic Lanes visually

    If you have a lot of Traffic Lanes it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#6-configure-previous-lanes","title":"6. Configure Previous Lanes","text":"

    Traffic Lane has to have previous Traffic Lanes configured. This is done in the exact same way as configuring next lanes which was shown in the previous step. Please do the same, but add Traffic Lanes that are before the configured one instead of the ones after into the Prev Lanes list.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#7-configure-right-of-way","title":"7. Configure Right Of Way","text":"

    Now we will configure the Right Of Way Lanes. The Right Of Way Lanes is a list of Traffic Lanes that have a priority over the configured one. The process of adding the Right Of Way Lanes is the same as with adding Next Lanes. For this reason we ask you to see the aforementioned step for detailed description on how to do this (the only difference is that you add Traffic Lanes to the Right Of Way Lanes list).

    Right of way example

    In this example lets consider the Traffic Lane highlighted in blue from the Traffic Intersection below.

    This Traffic Lane has to give way to all Traffic Lanes highlighted on yellow. This means all of the yellow Traffic Lanes have to be added to the 'Right Of Way Lanes' list which is reflected on the configuration shown below.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#8-add-stop-line","title":"8. Add Stop Line","text":"

    Adding a Stop Line is necessary only when at the end of the configured Traffic Lane the Stop Line is present. If so, please select the correct Stop Line from the drop-down list.

    Select Stop Line visually

    If you have a lot of Stop Lines it can be challenging to add them from the list. You can select them visually from the Scene the same as you had selected Traffic Lanes in the Random Traffic Simulator.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#9-add-speed-limit","title":"9. Add Speed Limit.","text":"

    In the field called Speed Limit simply write the speed limit that is in effect on the configured Traffic Lane.

    "},{"location":"Components/Environment/AddNewEnvironment/AddRandomTraffic/LoadItemsFromLanelet/#10-set-the-right-of-ways","title":"10. Set the Right of Ways","text":"

    To make the Right Of Ways list you configured earlier take effect simply click the 'Set RightOfWays' button.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/","title":"Add TrafficLights","text":""},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#add-trafficlights","title":"Add TrafficLights","text":"

    To add TrafficLights into your Environment follow steps below.

    Tip

    In the Environment you are creating there will most likely be many TrafficLights that should look and work the same way. To simplify the process of creating an environment it is advised to create one TrafficLight of each type with this tutorial and then save them as prefabs that you will be able to reuse.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#1-add-trafficlight-object","title":"1. Add TrafficLight Object","text":"

    Into your Map object in the Hierarchy view add a new Child Object and name it appropriately.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#2-add-a-mesh-filter-and-select-meshes","title":"2. Add a Mesh Filter and select meshes","text":"

    1. Click on the Add Component button.

    2. Search for Mesh filter and select it by clicking on it.

    3. For each TrafficLight specify the mesh you want to use.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#3add-a-mesh-renderer-and-specify-materials","title":"3.Add a Mesh Renderer and specify materials","text":"

    1. The same way as above search for Mesh Renderer and select it.

    2. Now you need to specify individual component materials.

      For example in the Traffic.Lights.001 mesh there are four sub-meshes that need their individual materials.

      To specify a material click on the selection button on Materials element and search for the material you want to use and select it.

      Repeat this process until you specify all materials. When you add one material more than there are sub-meshes you will see this warning. Then just remove the last material and the TrafficLight is prepared.

      Info

      Different material for every bulb is necessary for the color changing behavior that we expect from traffic lights. Even though in most cases you will use the same material for every Bulb, having them as different elements is necessary. Please only use models of TrafficLights that have different Materials Elements for every Bulb.

      Materials order

      When specifying materials remember the order in which they are used in the mesh. Especially remember what Materials Elements are associated with every Bulb in the TrafficLight. This information will be needed later.

      Example

      In the case of Traffic.Lights.001 the bulb materials are ordered starting from the left side with index 1 and increasing to the right.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#4-add-a-mesh-collider","title":"4. Add a Mesh Collider","text":"

    The same way as above search for Mesh Collider and select it. Collider may not seem useful, as the TrafficLight in many cases will be out of reach of vehicles. It is however used for LiDAR simulation, so it is advised to always add colliders to Objects that should be detected by LiDARs.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#5-position-trafficlight-in-the-environment","title":"5. Position TrafficLight in the Environment","text":"

    Finally after configuring all visual aspects of the TrafficLight you can position it in the environment. Do this by dragging a TrafficLight with a square representing a plane or with an arrow representing one axis.

    "},{"location":"Components/Environment/AddNewEnvironment/AddTrafficLights/#6-add-trafficlight-script","title":"6. Add TrafficLight Script","text":"

    The Traffic Light Script will enable you to control how the TrafficLight lights up and create sequences.

    1. Click on Add Component, search for the Traffic Light script and select it.

    2. You should see the Bulb Emission config already configured. These are the colors that will be used to light up the Bulbs in TrafficLight. You may adjust them to suit your needs.

    3. You will have to specify Bulb material config, in which you should add elements with fields:

      • Bulb Type - One of the predefined Bulb types that describes the Bulb (its color and pattern).
      • Material Index - Index of the material that you want to be associated with the Bulb Type. This is where you need to use the knowledge from earlier where we said you have to remember what Materials Element corresponds to which bulb sub-mesh.

      Bulb configuration example

      Here we specify an element Type as RED_BULB and associate it with Material that has an index 3. This will result in associating the right most bulb with the name RED_BULB. This information will be of use to us when specifying TrafficLights sequences.

    Success

    Once you have added TrafficLights to your Environment, you can start configuring RandomTraffic which will add moving vehicles to it! Details here.

    "},{"location":"Components/Environment/CreatePCD/","title":"Create PCD","text":""},{"location":"Components/Environment/CreatePCD/#create-pcd","title":"Create PCD","text":"

    This section

    This section is still under development!

    "},{"location":"Components/Environment/CreatePCD/#pointcloudmapper","title":"PointCloudMapper","text":""},{"location":"Components/Environment/CreatePCD/#description","title":"Description","text":"

    PointCloudMapper is a tool for a vehicle based point cloud mapping in a simulation environment. It is very useful when you need a point cloud based on some location, but don't have the possibility to physically map the real place. Instead you can map the simulated environment.

    "},{"location":"Components/Environment/CreatePCD/#required-data","title":"Required Data","text":"

    To properly perform the mapping, make sure you have the following files downloaded and configured:

    • Lanelet2 format OSM data (*.osm file)

    • 3D model map of the area

      How to obtain a map

      You can obtain the 3D model of the area by using a Environment prefab prepared for AWSIM or by creating your own. You can learn how to create you own Environment prefab in this tutorial.

    • Configured in-simulation vehicle object with sensors attached (only the LiDAR is necessary)

      Vehicle model

      For the sake of creating a PCD the vehicle model doesn't have to be accurate. It will be just a carrier for LiDAR. The model can even be a simple box as shown earlier in this tutorial. Make sure it is not visible to the LiDAR, so it does not break the sensor readings.

    "},{"location":"Components/Environment/CreatePCD/#import-osm","title":"Import OSM","text":"

    1. Drag and drop an OSM file into Unity project.

    2. OSM file will be imported as OsmDataContainer.

    "},{"location":"Components/Environment/CreatePCD/#setup-an-environment","title":"Setup an Environment","text":"

    For mapping an Environment prefab is needed. The easiest way is to create a new Scene and import the Environment prefab into it. Details on how to do this can be found on this tutorial page.

    "},{"location":"Components/Environment/CreatePCD/#setup-a-vehicle","title":"Setup a Vehicle","text":"

    Create a Vehicle GameObject in the Hierarchy view.

    "},{"location":"Components/Environment/CreatePCD/#add-visual-elements-optional","title":"Add visual elements (optional)","text":"

    Add vehicle model by adding a Geometry Object as a child of Vehicle and adding all visual elements as children.

    Visual elements

    You can learn how to add visual elements and required components like Mesh Filter or Mesh Renderer in this tutorial.

    "},{"location":"Components/Environment/CreatePCD/#add-a-camera-optional","title":"Add a Camera (optional)","text":"

    Add a Camera component for enhanced visuals by adding a Main Camera Object as a child of Vehicle Object and attaching a Camera Component to it.

    1. Add a Main Camera Object.

    2. Add a Camera Component by clicking 'Add Component' button, searching for it and selecting it.

    3. Change the Transform for an even better visual experience.

      Camera preview

      Observe how the Camera preview changes when adjusting the transformation.

    "},{"location":"Components/Environment/CreatePCD/#setup-vehicle-sensors-rgl","title":"Setup Vehicle Sensors (RGL)","text":"

    This part of the tutorial shows how to add a LiDAR sensor using RGL.

    RGL Scene Manager

    Please make sure that RGLSceneManager is added to the scene. For more details and instruction how to do it please visit this tutorial page.

    1. Create an empty Sensors GameObject as a child of the Vehicle Object.

    2. Create a Lidar GameObject as a child of the Sensors Object.

    3. Attach Lidar Sensor (script) to previously created Lidar Object by clicking on the 'Add Component' button, searching for the script and selecting it.

      Point Cloud Visualization

      Please note that Point Cloud Visualization (script) will be added automatically with the Lidar Sensor (script).

    4. Configure LiDAR pattern, e.g. by selecting one of the available presets.

      Example Lidar Sensor configuration

      Gaussian noise

      Gaussian noise should be disabled to achieve a more accurate map.

    5. Attach RGL Mapping Adapter (script) to previously created Lidar Object by clicking on the 'Add Component' button, searching for the script and selecting it.

    6. Configure RGL Mapping Adapter - e.g. set Leaf Size for filtering.

      Example RGL Mapping Adapter configuration

      Downsampling

      Please note that downsampling is applied on the single LiDAR scans only. If you would like to filter merged scans use the external tool described below.

    "},{"location":"Components/Environment/CreatePCD/#effect-of-leaf-size-to-point-cloud-data-pcd-generation","title":"Effect of Leaf Size to Point Cloud Data (PCD) generation","text":"

    Downsampling aims to reduce PCD size which for large point clouds may achieve gigabytes in exchange for map details. It is essential to find the best balance between the size and acceptable details level.

    A small Leaf Size results in a more detailed PCD, while a large Leaf Size could result in excessive filtering such that objects like buildings are not recorded in the PCD.

    In the following examples, it can be observed that when a Leaf Size is 1.0, point cloud is very detailed. When a Leaf Size is 100.0, buildings are filtered out and results in an empty PCD. A Leaf Size of 10.0 results in a reasonable PCD in the given example.

    Leaf Size = 1.0 Leaf Size = 10.0 Leaf Size = 100.0"},{"location":"Components/Environment/CreatePCD/#setup-pointcloudmapper","title":"Setup PointCloudMapper","text":"

    1. Create a PointCloudMapper GameObject in the Hierarchy view.

    2. Attach Point Cloud Mapper script to previously created Point Cloud Mapper Object by clicking on the 'Add Component' button, searching for the script and selecting it.

    3. Configure the Point Cloud Mapper fields:

      • Osm Container - the OSM file you imported earlier

      • World Origin - MGRS position of the origin of the scene

        World Origin coordinate system

        Use ROS coordinate system for World Origin, not Unity.

      • Capture Location Interval - Distance between consecutive capture points along lanelet centerline
      • Output Pcd File Path - Output relative path from Assets folder
      • Target Vehicle - The vehicle you want to use for point cloud capturing that you created earlier

      Example Point Cloud Mapper configuration

      Lanelet visualization

      It is recommended to disable Lanelet Visualizer by setting Material to None and Width equal to zero. Rendered Lanelet is not ignored by the LiDAR so it would be captured in the PCD.

    "},{"location":"Components/Environment/CreatePCD/#effect-of-capture-location-interval-to-pcd-generation","title":"Effect of Capture Location Interval to PCD generation","text":"

    If the Capture Location Interval is too small, it could result in a sparse PCD where some region of the map is captured well but the other regions aren't captured at all.

    In the below example, Leaf Size of 0.2 was used. Please note that using a different combination of leaf size and Capture Location Interval may result in a different PCD.

    Capture Location Interval = 6 Capture Location Interval = 20 Capture Location Interval = 100"},{"location":"Components/Environment/CreatePCD/#capture-and-generate-pcd","title":"Capture and Generate PCD","text":"

    If you play simulation with a scene prepared with the steps above, PointCloudMapper will automatically start mapping. The vehicle will warp along centerlines by intervals of CaptureLocationInterval and capture point cloud data. PCD file will be written when you stop your scene or all locations in the route are captured.

    If the Vehicle stops moving for longer and you see the following message in the bottom left corner - you can safely stop the scene.

    The Point cloud *.pcd file is saved to the location you specified in the Point Cloud Mapper.

    "},{"location":"Components/Environment/CreatePCD/#pcd-postprocessing","title":"PCD postprocessing","text":"

    Install required tool

    The tool (DownsampleLargePCD) required for PCD conversion can be found under the link. README contains building instruction and usage.

    The generated PCD file is typically too large. Therefore you need to downsample it. Also, it should be converted to ASCII format because Autoware accepts only this format. PointCloudMapper returns PCD in binary format.

    1. Change the working directory to the location with DownsampleLargePCD tool.

    2. Use this tool to downsample and save PCD in ASCII format. 

      ./DownsampleLargePCD -in <PATH_TO_INPUT_PCD> -out <PATH_TO_OUTPUT_PCD> -leaf 0.2,0.2,0.2\n
      • Assuming input PCD is in your working directory and named in_cloud.pcd and output PCD is to be named out_cloud.pcd the command will be: 
        ./DownsampleLargePCD -in in_cloud.pcd -out out_cloud.pcd -leaf 0.2,0.2,0.2\n
      • You can also save PCD in binary format by adding -binary 1 option.

    3. Your PCD is ready to use.

    Converting PCD format without downsampling

    If you don't want to downsample your PCD you can convert PCD file to ASCII format with pcl_convert_pcd_ascii_binary tool. This tool is available in the pcl-tools package and can be installed on Ubuntu with the following command: 

    sudo apt install pcl-tools\n
    To convert your PCD use command: 
    pcl_convert_pcd_ascii_binary <PATH_TO_INPUT_PCD> <PATH_TO_OUTPUT_PCD> 0\n
    "},{"location":"Components/Environment/CreatePCD/#verify-the-pcd","title":"Verify the PCD","text":"

    To verify your PCD you can launch the Autoware with the PCD file specified.

    1. Copy your PCD from the AWSIM project directory to the Autoware map directory.

      cp <PATH_TO_PCD_FILE> <PATH_TO_AUTOWARE_MAP>/\n

    2. Source the ROS and Autoware

      source /opt/ros/humble/setup.bash\nsource <PATH_TO_AUTOWARE>/install/setup.bash\n

    3. Launch the planning simulation with the map directory path (map_path) and PCD file (pointcloud_map_file) specified.

      PCD file location

      The PCD file needs to be located in the Autoware map directory and as a pointcloud_map_file parameter you only supply the file name, not the path.

      Absolute path

      When launching Autoware never use ~/ to specify the home directory. Either write the full absolute path ot use $HOME environmental variable.

      ros2 launch autoware_launch planning_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit map_path:=<ABSOLUTE_PATH_TO_AUTOWARE_MAP> pointcloud_map_file:=<PCD_FILE_NAME>\n

    4. Wait for the Autoware to finish loading and inspect the PCD visually given the Effect of Leaf Size and Effect of Capture Location Interval.

    "},{"location":"Components/Environment/CreatePCD/#sample-scene","title":"Sample Scene","text":"

    PointCloudMapping.unity is a sample scene for PointCloudMapper showcase. It requires setup of OSM data and 3D model map of the area according to the steps above.

    Sample Mapping Scene

    In this example you can see a correctly configured Point Cloud Mapping Scene.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/","title":"LaneletBoundsVisualizer","text":""},{"location":"Components/Environment/LaneletBoundsVisualizer/#lanelet-bounds-visualizer","title":"Lanelet Bounds Visualizer","text":"

    Lanelet Bounds Visualizer is an Unity Editor extension allowing the user to load the left and right bounds of Lanelet to the Unity scene.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/#usage","title":"Usage","text":"

    The lanelet bounds load process can be performed by opening AWSIM -> Visualize -> Load Lanelet Bounds at the top toolbar of Unity Editor.

    A window shown below will pop up. Select your Osm Data Container to specify which OSM data to load the Lanelet from.

    The user can select whether to load the raw Lanelet or to adjust the resolution of the Lanelet by specifying the waypoint settings.

    To load the raw Lanelet, simply click the Load Raw Lanelet button.

    If the user wishes to change the resolution of the Lanelet, adjust the parameters of the Waypoint Settings as described below, and click the Load with Waypoint Settings button.

    • Resolution : resolution of resampling. Lower values provide better accuracy at the cost of processing time.
    • Min Delta Length : minimum length(m) between adjacent points.
    • Min Delta Angle : minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve.

    Once the Lanelet is successfully loaded, Lanelet bounds will be generated as a new GameObject named LaneletBounds.

    To visualize the LaneletBounds, make sure Gizmos is turned on and select the LaneletBounds GameObject.

    "},{"location":"Components/Environment/LaneletBoundsVisualizer/#important-notes","title":"Important Notes","text":"

    Generally speaking, visualizing Lanelet Bounds will result in a very laggy simulation. Therefore, it is recommended to hide the LaneletBounds GameObject when not used. The lag of the simulation becomes worse as you set the resolution of the Lanelet Bounds higher, so it is also recommended to set the resolution within a reasonable range.

    It is also important to note that no matter how high you set the resolution to be, it will not be any better than the original Lanelet (i.e. the raw data). Rather, the computational load will increase and the simulation will become more laggy. If the user wishes to get the highest quality of Lanelet Bounds, it is recommended to use the Load Raw Lanelet button.

    In short, Waypoint Setting parameters should be thought of as parameters to decrease the resolution from the original Lanelet to decrease the computational load and thus, reducing the lag of the simulation.

    Higher Resolution Raw Lanelet Lower Resolution"},{"location":"Components/Environment/SmokeSimulator/","title":"SmokeSimulator","text":""},{"location":"Components/Environment/SmokeSimulator/#smoke-simulator","title":"Smoke Simulator","text":"

    Simulating smoke in AWSIM may be useful when one wants to simulate exhaust gases from vehicles, smoke from emergency flare, etc.

    In Unity, it is common to use Particle System to simulate smokes. However, smoke simulated by Particle System cannot be sensed by RGL in AWSIM although in reality, smokes are detected by LiDAR.

    Smoke Simulator was developed to simulate smokes that can be detected by RGL in Unity. Smoke Simulator works by instantiating many small cubic GameObjects called Smoke Particles and allows each particle to be detected by RGL.

    This document describes how to use the Smoke Simulator.

    "},{"location":"Components/Environment/SmokeSimulator/#setting-smoke-simulator","title":"Setting Smoke Simulator","text":"

    1.Create an empty GameObject

    2.Attach SmokeGenerator.cs to the previously created GameObject.

    3.Adjust the parameters of the SmokeGenerator as described below:

    • Max Particle: Specifies the maximum number of particles created by the Smoke Generator
    • Particle Range Radius: Specifies the radius of a circle, centered at the GameObject, which defines the region in which Smoke Particles are generated in
    • Particle Size: Specifies the edge of a Smoke Particle
    • Average Lifetime: Specifies the average lifetime of a Smoke Particle

    • Variation Lifetime: Specifies the variation of lifetime of Smoke Particles.

      The lifetime of a Smoke Particle is calculated as follows:

      `lifetime` = `Average Lifetime` + Random.Range(-`Variation Lifetime`, `Variation Lifetime`)\n
    • Physics: These parameters can be adjusted to specify the behavior of the smoke particles.
      • Initial Plane Velocity: Specifies the velocity of a SmokeParticle in the x-z plane
      • Initial Vertical Velocity: Specifies the velocity of a SmokeParticle in the vertical direction
      • Plane Acceleration: Specifies the acceleration of a SmokeParticle in the x-z plane
      • Vertical Acceleration: Specifies the acceleration of a SmokeParticle in the vertical direction

    4.(Optional): You may also specify the Material of Smoke Particles. If this field is unspecified, a default material is used

    "},{"location":"Components/Environment/SmokeSimulator/#example-of-different-smokes","title":"Example of Different Smokes","text":""},{"location":"Components/Environment/SmokeSimulator/#thin-smoke","title":"Thin Smoke","text":""},{"location":"Components/Environment/SmokeSimulator/#heavy-smoke","title":"Heavy Smoke","text":""},{"location":"Components/Environment/V2I/","title":"V2I","text":""},{"location":"Components/Environment/V2I/#v2i-vehicle-to-infrastructure","title":"V2I (Vehicle-to-Infrastructure)","text":"

    V2I is a component that simulates V2I communication protocol which allows to exchange data between vehicles and road infrastructure. In the current version of AWSIM, the V2I component publishes information about traffic lights.

    "},{"location":"Components/Environment/V2I/#how-to-add-v2i-to-the-environment","title":"How to add V2I to the environment","text":""},{"location":"Components/Environment/V2I/#assign-lanelet2-wayid-and-relationid-to-trafficlight-object","title":"Assign Lanelet2 WayID and RelationID to TrafficLight object","text":"

    1. Load items from lanelet2 following the instruction

    2. Verify if Traffic Light Lanelet ID component has been added to Traffic Light game objects.

    3. Verify if WayID and RelationID has been correctly assigned. You can use Vector Map Builder as presented below

    "},{"location":"Components/Environment/V2I/#add-manually-traffic-light-lanelet-id-component-alternatively","title":"Add manually Traffic Light Lanelet ID component (alternatively)","text":"

    If for some reason, Traffic Light Lanelet ID component is not added to Traffic Light object.

    1. Add component manually

    2. Fill Way ID

    3. Fill Relation ID

    "},{"location":"Components/Environment/V2I/#add-v2i-prefab","title":"Add V2I prefab","text":""},{"location":"Components/Environment/V2I/#select-ego-transform","title":"Select EGO transform","text":""},{"location":"Components/Environment/V2I/#parameters","title":"Parameters","text":"Name Type Description Output Hz int Topic publication frequency Ego Vehicle Transform transform Ego Vehicle object transform Ego Distance To Traffic Signals double Maximum distance between Traffic Light and Ego Traffic Signal ID enum Possibility to select if as traffic_signal_id field in msg is Relation ID or Way ID Traffic Signals Topic string Topic name

    Note

    V2I feature can be used as Traffic Light ground truth information, and for that usage Way ID is supposed to be selected.

    "},{"location":"Components/ROS2/AddACustomROS2Message/","title":"Add custom ROS2 msg","text":""},{"location":"Components/ROS2/AddACustomROS2Message/#add-a-custom-ros2-message","title":"Add a custom ROS2 message","text":"

    If you want to use custom message in AWSIM, you need to generate the appropriate files, to do this you have to build ROS2ForUnity yourself - please follow the steps below. Remember to start with prerequisities though.

    ROS2ForUnity role

    For a better understanding of the role of ROS2ForUnity and the messages used, we encourage you to read this section.

    custom_msgs

    In order to simplify this tutorial, the name of the package containing the custom message is assumed to be custom_msgs - remember to replace it with the name of your package.

    "},{"location":"Components/ROS2/AddACustomROS2Message/#prerequisites","title":"Prerequisites","text":"

    ROS2ForUnity depends on a ros2cs - a C# .NET library for ROS2. This library is already included so you don't need to install it, but there are a few prerequisites that must be resolved first.

    Please select your system and resolve all prerequisites:

    UbuntuWindows
    • ros2cs prerequisites for Ubuntu
    • ROS2 version is humble and is located in /opt/ros/humble
    • Your package with custom message is located in the home directory ~/custom_msgs or is hosted on git repository.
    • Shell - commands have to be executed from the bash shell

    • ros2cs prerequisites for Windows

      Question

      Tests are not working ('charmap' codec can't decode byte) on Windows - look at troubleshooting here

    • ROS2 version is humble and is located in C:\\ros2_humble
    • Your package with custom message package is located in the home directory C:\\custom_msgs or is hosted on git repository.
    • Shell - commands should be executed from the powershell shell
    "},{"location":"Components/ROS2/AddACustomROS2Message/#1-workspace-preparation","title":"1. Workspace preparation","text":"

    1. Clone ROS2ForUnity repository by execute command:

      UbuntuWindows 
      git clone https://github.com/RobotecAI/ros2-for-unity ~/\n

      Warning

      The cloned ROS 2 For Unity repository must be located in the home directory ~/.

      git clone https://github.com/RobotecAI/ros2-for-unity /C\n

      Warning

      The cloned ROS 2 For Unity repository must be located in the home directory C:\\.

    2. Pull dependent repositories by execute commands:

      UbuntuWindows 
      cd ~/ros2-for-unity\n. /opt/ros/humble/setup.bash\n./pull_repositories.sh\n
      cd C:\\ros2-for-unity\nC:\\ros2_humble\\local_setup.ps1\n.\\pull_repositories.ps1\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#2-setup-custom_msgs-package","title":"2. Setup custom_msgs package","text":"

    The method to add a custom package to build depends on where it is located. The package can be on your local machine or just be hosted on a git repository. Please, choose the appropriate option and follow the instructions.

    "},{"location":"Components/ROS2/AddACustomROS2Message/#21-package-contained-on-local-machine","title":"2.1. Package contained on local machine","text":"

    1. Copy the custom_msgs package with custom message to the folder to src/ros2cs/custom_messages directory

      UbuntuWindows 
      cp -r ~/custom_msgs ~/ros2-for-unity/src/ros2cs/custom_messages/\n
      Copy-Item 'C:\\custom_msgs' -Destination 'C:\\ros2-for-unity\\src\\custom_messages'\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#22-package-hosted-on-git-repository","title":"2.2. Package hosted on git repository","text":"
    1. Open ros2-for-unity/ros2_for_unity_custom_messages.repos file in editor.

    2. Modify the contents of the file shown below, uncomment and set:

      • <package_name> - to your package name - so in this case custom_msgs,
      • <repo_url> - to repository address,
      • <repo_branch> - to desired branch. 
        repositories:\n#  src/ros2cs/custom_messages/<package_name>:\n#    type: git\n#    url: <repo_url>\n#    version: <repo_branch>\n

      Example

      Below is an example of a file configured to pull 2 packages (custom_msgs,autoware_msgs) of messages hosted on a git repository. 

      # NOTE: Use this file if you want to build with custom messages that reside in a separate remote repo.\n# NOTE: use the following format\n\nrepositories:\n    src/ros2cs/custom_messages/custom_msgs:\n        type: git\n        url: https://github.com/tier4/custom_msgs.git\n        version: main\n    src/ros2cs/custom_messages/autoware_msgs:\n        type: git\n        url: https://github.com/tier4/autoware_msgs.git\n        version: tier4/main\n

    3. Now pull the repositories again (also the custom_msgs package repository)

      UbuntuWindows 
      cd ~/ros2-for-unity\n./pull_repositories.sh\n
      cd C:\\ros2-for-unity\n.\\pull_repositories.ps1\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#3-build-ros-2-for-unity","title":"3. Build ROS 2 For Unity","text":"

    Build ROS2ForUnity with custom message packages using the following commands:

    UbuntuWindows 
    cd ~/ros2-for-unity\n./build.sh --standalone\n
    cd C:\\ros2-for-unity\n.\\build.ps1 -standalone\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#4-install-custom_msgs-to-awsim","title":"4. Install custom_msgs to AWSIM","text":"

    New ROS2ForUnity build, which you just made in step 3, contains multiple libraries that already exist in the AWSIM. To install custom_msgs and not copy all other unnecessary files, you should get the custom_msgs related libraries only.

    You can find them in following directories and simply copy to the analogous directories in AWSIM/Assets/Ros2ForUnity folder, or use the script described here.

    UbuntuWindows
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins which names matches custom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Linux/x86_64/ which names matches libcustom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins which names matches custom_msgs_*
    • ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Windows/x86_64/ which names matches custom_msgs_*
    "},{"location":"Components/ROS2/AddACustomROS2Message/#automation-of-copying-message-files","title":"Automation of copying message files","text":"UbuntuWindows

    To automate the process, you can use a script that copies all files related to your custom_msgs package.

    1. Create a file named copy_custom_msgs.sh in directory ~/ros2-for-unity/ and paste the following content into it. 
      #!/bin/bash\necho \"CUSTOM_MSGS_PACKAGE_NAME: $1\"\necho \"AWSIM_DIR_PATH: $2\"\nfind ./install/asset/Ros2ForUnity/Plugins -maxdepth 1 -name \"$1*\"    -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins \\;\nfind ./install/asset/Ros2ForUnity/Plugins/Linux/x86_64 -maxdepth 1 -name     \"lib$1*\" -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins/Linux/x86_64 \\;\n
    2. Save the file and give it executable rights with the command: 
      chmod a+x copy_msgs.sh\n
    3. Run the script with two arguments: 
      ./copy_custom_msgs.sh <CUSTOM_MSGS_PACKAGE_NAME> <AWSIM_DIR_PATH>\n
    • <CUSTOM_MSGS_PACKAGE_NAME> - the first one which is the name of the package with messages - in this case custom_msgs,
    • <AWSIM_DIR_PATH> - the second which is the path to the cloned AWSIM repository.

    Example

    ./copy_custom_msgs.sh custom_msgs ~/unity/AWSIM/\n

    To automate the process, you can use these commands with changed:

    • <CUSTOM_MSGS_PACKAGE_NAME> - the name of your package with messages - in this case custom_msgs,
    • <AWSIM_DIR_PATH> - to path to the cloned AWSIM repository 
      Get-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\\Assets\\Ros2ForUnity\\Plugins\nGet-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\Windows\\x86_64\\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\\Assets\\Ros2ForUnity\\Plugins\\Windows\\x86_64\n

    Example

    Get-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\* -Include @('custom_msgs*') | Copy-Item -Destination C:\\unity\\AWSIM\\Assets\\Ros2ForUnity\\Plugins\nGet-ChildItem C:\\ros2-for-unity\\install\\asset\\Ros2ForUnity\\Plugins\\Windows\\x86_64\\* -Include @('custom_msgs*') | Copy-Item -Destination C:\\unity\\AWSIM\\Assets\\Ros2ForUnity\\Plugins\\Windows\\x86_64\n
    "},{"location":"Components/ROS2/AddACustomROS2Message/#5-test","title":"5. Test","text":"

    Make sure that the package files custom_msgs have been properly copied to the AWSIM/Assets/Ros2ForUnity. Then try to create a message object as described in this section and check in the console of Unity Editor if it compiles without errors.

    "},{"location":"Components/ROS2/ROS2ForUnity/","title":"ROS2 For Unity","text":""},{"location":"Components/ROS2/ROS2ForUnity/#ros2-for-unity","title":"ROS2 For Unity","text":"

    Ros2ForUnity (R2FU) module is a communication solution that effectively connects Unity and the ROS2 ecosystem, maintaining a strong integration. Unlike other solutions, it doesn't rely on bridging communication but rather utilizes the ROS2 middleware stack (specifically the rcl layer and below), enabling the inclusion of ROS2 nodes within Unity simulations.

    R2FU is used in AWSIM for many reasons. First of all, because it offers high-performance integration between Unity and ROS2, with improved throughput and lower latencies compared to bridging solutions. It provides real ROS2 functionality for simulation entities in Unity, supports standard and custom messages, and includes convenient abstractions and tools, all wrapped as a Unity asset. For a detailed description, please see README.

    "},{"location":"Components/ROS2/ROS2ForUnity/#prerequisites","title":"Prerequisites","text":"

    This asset can be prepared in two flavours:

    • standalone mode - where no ROS2 installation is required on target machine, e.g., your Unity simulation server. All required dependencies are installed and can be used e.g. as a complete set of Unity plugins.
    • overlay mode - where the ROS2 installation is required on target machine. Only asset libraries and generated messages are installed therefore ROS2 instance must be sourced.

    By default, asset R2FU in AWSIM is prepared in standalone mode.

    Warning

    To avoid internal conflicts between the standalone libraries, and sourced ones, ROS2 instance shouldn't be sourced before running AWSIM or the Unity Editor.

    Can't see topics

    There are no errors but I can't see topics published by R2FU

    • Make sure your DDS (Localhost settings) config is correct.
    • Sometimes ROS2 daemon brakes up when changing network interfaces or ROS2 version.

    Try to stop it forcefully (pkill -9 ros2_daemon) and restart (ros2 daemon start).

    "},{"location":"Components/ROS2/ROS2ForUnity/#concept","title":"Concept","text":"

    Describing the concept of using R2FU in AWSIM, we distinguish:

    • ROS2Node - it is the equivalent of a node in ROS2, it has its own name, it can have any number of subscribers, publishers, service servers and service clients. In the current AWSIM implementation, there is only one main node.
    • ROS2Clock - it is responsible for generating the simulation time using the selected source.
    • SimulatorROS2Node - it is a class that is directly responsible for AWSIM<->ROS2 communication, and contains one instance each of ROS2Node and ROS2Clock, so it creates the main AWSIM node in ROS2 and simulates the time from the selected source (currently UnityTimeSource is used). It is initialized at the moment of running the scene in Unity - thanks to the RuntimeInitializeOnLoadMethod mark.
    • Publisher - it is the equivalent of the publisher in ROS2, it uses a single topic on which it can publish a selected type of message, and it has a selected QoS profile. Each publisher in AWSIM is created in ROS2Node object of class SimulatorROS2Node.
    • Subscriber - it is the equivalent of the subscriber in ROS2, it uses a single topic from which it subscribes to the selected type of message, and it has a selected QoS profile. Each subscriber in AWSIM is created in ROS2Node object of class SimulatorROS2Node.

    The SimulatorROS2Node implementation, thanks to the use of R2FU, allows you to add communication via ROS2 to any Unity component. For example, we can receive control commands from any other ROS2 node and publish the current state of Ego, such as its position in the environment.

    Simulation time

    If you want to use system time (ROS2 time) instead of Unity time, use ROS2TimeSource instead of UnityTimeSource in the SimulatorROS2Node class.

    "},{"location":"Components/ROS2/ROS2ForUnity/#package-structure","title":"Package structure","text":"

    Ros2ForUnity asset contains:

    • Plugins - dynamically loaded libraries for Windows and Linux (*.dll and *.so files). In addition to the necessary libraries, here are the libraries created as a result of generation the types of ROS2 messages that are used in communication.
    • Scripts - scripts for using R2FU in Unity - details below.
    • Extension Scripts - scripts for using R2FU in AWSIM, provide abstractions of a single main Node and simplify the interface - details below. These scripts are not in the library itself, but directly in the directory Assets/AWSIM/Scripts/ROS/**.
    "},{"location":"Components/ROS2/ROS2ForUnity/#scripts","title":"Scripts","text":"
    • ROS2UnityCore - the principal class for handling ROS2 nodes and executables. Spins and executes actions (e.g. clock, sensor publish triggers) in a dedicated thread.
    • ROS2UnityComponent - ROS2UnityCore adapted to work as a Unity component.
    • ROS2Node - a class representing a ROS2 node, it should be constructed through ROS2UnityComponent class, which also handles spinning.
    • ROS2ForUnity - an internal class responsible for handling checking, proper initialization and shutdown of ROS2 communication,
    • ROS2ListenerExample - an example class provided for testing of basic ROS2->Unity communication.
    • ROS2TalkerExample - an example class provided for testing of basic Unity->ROS2 communication.
    • ROS2PerformanceTest - an example class provided for performance testing of ROS2<->Unity communication.
    • Sensor - an abstract base class for ROS2-enabled sensor.
    • Transformations - a set of transformation functions between coordinate systems of Unity and ROS2.
    • PostInstall - an internal class responsible for installing R2FU metadata files.
    • Time scripts - a set of classes that provide the ability to use different time sources:
      • ROS2Clock - ROS2 clock class that for interfacing between a time source (Unity or ROS2 system time) and ROS2 messages.
      • ROS2TimeSource - acquires ROS2 time (system time by default).
      • UnityTimeSource - acquires Unity time.
      • DotnetTimeSource - acquires Unity DateTime based clock that has resolution increased using Stopwatch.
      • ITimeSource - interface for general time extraction from any source.
      • TimeUtils - utils for time conversion.
    "},{"location":"Components/ROS2/ROS2ForUnity/#extension-scripts","title":"Extension Scripts","text":"

    Additionally, in order to adapt AWSIM to the use of R2FU, the following scripts are used:

    • SimulatorROS2Node - it is a class that is directly responsible for AWSIM<->ROS2 communication.

    • ClockPublisher - allows the publication of the simulation time from the clock running in the SimulatorROS2Node. It must be added as a component to the scene in order to publish the current time when the scene is run.

    • QoSSettings - it is the equivalent of ROS2 QoS, which allows to specify the QoS for subscribers and publishers in AWSIM. It uses the QualityOfServiceProfile implementation from the Ros2cs library.
    • ROS2Utility - it is a class with utils that allow, for example, to convert positions in the ROS2 coordinate system to the AWSIM coordinate system.
    • DiagnosticsManager - prints diagnostics for desired elements described in *.yaml config file.
    "},{"location":"Components/ROS2/ROS2ForUnity/#default-message-types","title":"Default message types","text":"

    The basic ROS2 msgs types that are supported in AWSIM by default include:

    • common_interfaces:
      • std_msgs.
      • geometry_msgs,
      • sensor_msgs,
      • nav_msgs,
      • diagnostic_msgs,
    • rcl_interfaces:
      • builtin_interfaces,
      • action_msgs,
      • rosgraph_msgs,
      • test_msgs.
    • autoware_msgs:
      • autoware_common_msgs,
      • autoware_control_msgs,
      • autoware_localization_msgs,
      • autoware_map_msgs,
      • autoware_perception_msgs,
      • autoware_planning_msgs,
      • autoware_sensing_msgs,
      • autoware_system_msgs,
      • autoware_vehicle_msgs.
    • tier4_autoware_msgs:
      • tier4_control_msgs,
      • tier4_vehicle_msgs.
    • Others:
      • tf2_msgs,
      • unique_identifier_msgs.

    In order for the message package to be used in Unity, its *.dll and *.so libraries must be generated using R2FU.

    Custom message

    If you want to generate a custom message to allow it to be used in AWSIM please read this tutorial.

    "},{"location":"Components/ROS2/ROS2ForUnity/#use-of-generated-messages-in-unity","title":"Use of generated messages in Unity","text":"

    Each message type is composed of other types - which can also be a complex type. All of them are based on built-in C# types. The most common built-in types in messages are bool, int, double and string. These types have their communication equivalents using ROS2.

    A good example of a complex type that is added to other complex types in order to specify a reference - in the form of a timestamp and a frame - is std_msgs/Header. This message has the following form:

    builtin_interfaces/msg/Time stamp\nstring frame_id\n

    ROS2 directive

    In order to work with ROS2 in Unity, remember to add the directive using ROS2; at the top of the file to import types from this namespace.

    "},{"location":"Components/ROS2/ROS2ForUnity/#create-an-object","title":"Create an object","text":"

    The simplest way to create an object of Header type is:

    var header = new std_msgs.msg.Header()\n{\n    Frame_id = \"map\"\n}\n

    It is not required to define the value of each field. As you can see, it creates an object, filling only frame_id field - and left the field of complex builtin_interfaces/msg/Time type initialized by default. Time is an important element of any message, how to fill it is written here.

    "},{"location":"Components/ROS2/ROS2ForUnity/#accessing-and-filling-in-message-fields","title":"Accessing and filling in message fields","text":"

    As you might have noticed in the previous example, a ROS2 message in Unity is just a structure containing the same fields - keep the same names and types. Access to its fields for reading and filling is the same as for any C# structure.

    var header2 = new std_msgs.msg.Header();\nheader2.Frame_id = \"map\";\nheader2.Stamp.sec = \"1234567\";\nDebug.Log($\"StampSec: {header2.Stamp.sec} and Frame: {header2.Frame_id}\");\n

    Field names

    There is one always-present difference in field names. The first letter of each message field in Unity is always uppercase - even if the base ROS2 message from which it is generated is lowercase.

    "},{"location":"Components/ROS2/ROS2ForUnity/#filling-a-time","title":"Filling a time","text":"

    In order to complete the time field of the Header message, we recommend the following methods in AWSIM:

    1. When the message has no Header but only the Time type:

      var header2 = new std_msgs.msg.Header();\nheader2.Stamp = SimulatorROS2Node.GetCurrentRosTime();\n

    2. When the message has a Header - like for example autoware_vehicle_msgs/VelocityReport:

      velocityReportMsg = new autoware_vehicle_msgs.msg.VelocityReport()\n{\n    Header = new std_msgs.msg.Header()\n    {\n        Frame_id = \"map\",\n    }\n};\nvar velocityReportMsgHeader = velocityReportMsg as MessageWithHeader;\nSimulatorROS2Node.UpdateROSTimestamp(ref velocityReportMsgHeader);\n

    These methods allow to fill the Time field in the message object with the simulation time - from ROS2Clock

    "},{"location":"Components/ROS2/ROS2ForUnity/#create-a-message-with-array","title":"Create a message with array","text":"

    Some message types contain an array of some type. An example of such a message is nav_msgs/Path, which has a PoseStamped array. In order to fill such an array, you must first create a List<T>, fill it and then convert it to a raw array.

    var posesList = new List<geometry_msgs.msg.PoseStamped>();\nfor(int i=0; i<=5;++i)\n{\n    var poseStampedMsg = new geometry_msgs.msg.PoseStamped();\n    poseStampedMsg.Pose.Position.X = i;\n    poseStampedMsg.Pose.Position.Y = 5-i;\n    var poseStampedMsgHeader = poseStampedMsg as MessageWithHeader;\n    SimulatorROS2Node.UpdateROSTimestamp(ref poseStampedMsgHeader);\n    posesList.Add(poseStampedMsg);\n}\nvar pathMsg = new nav_msgs.msg.Path(){Poses=posesList.ToArray()};\nvar pathMsgHeader = pathMsg as MessageWithHeader;\nSimulatorROS2Node.UpdateROSTimestamp(ref pathMsgHeader);\n// pathMsg is ready\n
    "},{"location":"Components/ROS2/ROS2ForUnity/#publish-on-the-topic","title":"Publish on the topic","text":"

    In order to publish messages, a publisher object must be created. The static method CreatePublisher of the SimulatorROS2Node makes it easy. You must specify the type of message, the topic on which it will be published and the QoS profile. Below is an example of autoware_vehicle_msgs.msg.VelocityReport type message publication with a frequency of 30Hz on /vehicle/status/velocity_status topic, the QoS profile is (Reliability=Reliable, Durability=Volatile, History=Keep last, Depth=1):

    using UnityEngine;\nusing ROS2;\n\nnamespace AWSIM\n{\n    public class VehicleReportRos2Publisher : MonoBehaviour\n    {\n        float timer = 0;\n        int publishHz = 30;\n        QoSSettings qosSettings = new QoSSettings()\n        {\n            ReliabilityPolicy = ReliabilityPolicy.QOS_POLICY_RELIABILITY_RELIABLE,\n            DurabilityPolicy = DurabilityPolicy.QOS_POLICY_DURABILITY_VOLATILE,\n            HistoryPolicy = HistoryPolicy.QOS_POLICY_HISTORY_KEEP_LAST,\n            Depth = 1,\n        };\n        string velocityReportTopic = \"/vehicle/status/velocity_status\";\n        autoware_vehicle_msgs.msg.VelocityReport velocityReportMsg;\n        IPublisher<autoware_vehicle_msgs.msg.VelocityReport> velocityReportPublisher;\n\n        void Start()\n        {\n            // Create a message object and fill in the constant fields\n            velocityReportMsg = new autoware_vehicle_msgs.msg.VelocityReport()\n            {\n                Header = new std_msgs.msg.Header()\n                {\n                    Frame_id = \"map\",\n                }\n            };\n\n            // Create publisher with specific topic and QoS profile\n            velocityReportPublisher = SimulatorROS2Node.CreatePublisher<autoware_vehicle_msgs.msg.VelocityReport>(velocityReportTopic, qosSettings.GetQoSProfile());\n        }\n\n         bool NeedToPublish()\n        {\n            timer += Time.deltaTime;\n            var interval = 1.0f / publishHz;\n            interval -= 0.00001f;\n            if (timer < interval)\n                return false;\n            timer = 0;\n            return true;\n        }\n\n        void FixedUpdate()\n        {\n            // Provide publications with a given frequency\n            if (NeedToPublish())\n            {\n                // Fill in non-constant fields\n                velocityReportMsg.Longitudinal_velocity = 1.00f;\n                velocityReportMsg.Lateral_velocity = 0.00f;\n                velocityReportMsg.Heading_rate = 0.00f;\n\n                // Update Stamp\n                var velocityReportMsgHeader = velocityReportMsg as MessageWithHeader;\n                SimulatorROS2Node.UpdateROSTimestamp(ref velocityReportMsgHeader);\n\n                // Publish\n                velocityReportPublisher.Publish(velocityReportMsg);\n            }\n        }\n    }\n}\n
    "},{"location":"Components/ROS2/ROS2ForUnity/#upper-limit-to-publish-rate","title":"Upper limit to publish rate","text":"

    The above example demonstrates the implementation of the 'publish' method within the FixedUpdate Unity event method. However, this approach has certain limitations. The maximum output frequency is directly tied to the current value of Fixed TimeStep specified in the Project Settings. Considering that the AWSIM is targeting a frame rate of 60 frames per second (FPS), the current Fixed TimeStep is set to 1/60s. And this impose 60Hz as a limitation on the publish rate for any sensor, which is implemented within FixedUpdate method. In case a higher output frequency be necessary, an alternative implementation must be considered or adjustments made to the Fixed TimeStep setting in the Editor->Project Settings->Time.

    The table provided below presents a list of sensors along with examples of topics that are constrained by the Fixed TimeStep limitation.

    Object Topic GNSS Sensor /sensing/gnss/pose IMU Sensor /sensing/imu/tamagawa/imu_raw Traffic Camera /sensing/camera/traffic_light/image_raw Pose Sensor /awsim/ground_truth/vehicle/pose OdometrySensor /awsim/ground_truth/localization/kinematic_state LIDAR /sensing/lidar/top/pointcloud_raw Vehicle Status /vehicle/status/velocity_status

    If the sensor or any other publishing object within AWSIM does not have any direct correlation with physics (i.e., does not require synchronization with physics), it can be implemented without using the FixedUpdate method. Consequently, this allows the bypass of upper limits imposed by the Fixed TimeStep.

    The table presented below shows a list of objects that are not constrained by the Fixed TimeStep limitation.

    Object Topic Clock /clock"},{"location":"Components/ROS2/ROS2ForUnity/#subscribe-to-the-topic","title":"Subscribe to the topic","text":"

    In order to subscribe messages, a subscriber object must be created. The static method CreateSubscription of the SimulatorROS2Node makes it easy. You must specify the type of message, the topic from which it will be subscribed and the QoS profile. In addition, the callback must be defined, which will be called when the message is received - in particular, it can be defined as a lambda expression. Below is an example of std_msgs.msg.Bool type message subscription on /vehicle/is_vehicle_stopped topic, the QoS profile is \u201csystem default\u201d: 

    using UnityEngine;\nusing ROS2;\n\nnamespace AWSIM\n{\n    public class VehicleStoppedSubscriber : MonoBehaviour\n    {\n        QoSSettings qosSettings = new QoSSettings();\n        string isVehicleStoppedTopic = \"/vehicle/is_vehicle_stopped\";\n        bool isVehicleStopped = false;\n        ISubscription<std_msgs.msg.Bool> isVehicleStoppedSubscriber;\n\n        void Start()\n        {\n            isVehicleStoppedSubscriber = SimulatorROS2Node.CreateSubscription<std_msgs.msg.Bool>(isVehicleStoppedTopic, VehicleStoppedCallback, qosSettings.GetQoSProfile());\n        }\n\n        void VehicleStoppedCallback(std_msgs.msg.Bool msg)\n        {\n            isVehicleStopped = msg.Data;\n        }\n\n        void OnDestroy()\n        {\n            SimulatorROS2Node.RemoveSubscription<std_msgs.msg.Bool>(isVehicleStoppedSubscriber);\n        }\n    }\n}\n
    "},{"location":"Components/ROS2/ROS2TopicList/","title":"ROS2 topic list","text":""},{"location":"Components/ROS2/ROS2TopicList/#ros2-topic-list","title":"ROS2 topic list","text":"

    The following is a summary of the ROS2 topics that the AWSIM node subscribes to and publishes on.

    Ros2ForUnity

    AWSIM works with ROS2 thanks to the use of Ros2ForUnity - read the details here. If you want to generate a custom message to allow it to be used in AWSIM please read this tutorial.

    "},{"location":"Components/ROS2/ROS2TopicList/#list-of-subscribers","title":"List of subscribers","text":"Category Topic Message type frame_id Hz QoS

    Control

    Ackermann Control /control/command/control_cmd autoware_control_msgs/msg/Control - 60 Reliable, TransientLocal, KeepLast/1 Gear /control/command/gear_cmd autoware_vehicle_msgs/msg/GearCommand - 10 Reliable, TransientLocal, KeepLast/1 Turn Indicators /control/command/turn_indicators_cmd autoware_vehicle_msgs/TurnIndicatorsCommand - 10 Reliable, TransientLocal, KeepLast/1 Hazard Lights /control/command/hazard_lights_cmd autoware_vehicle_msgs/HazardLightsCommand - 10 Reliable, TransientLocal, KeepLast/1 Emergency /control/command/emergency_cmd tier4_vehicle_msgs/msg/VehicleEmergencyStamped - 60 Reliable, TransientLocal, KeepLast/1"},{"location":"Components/ROS2/ROS2TopicList/#list-of-publishers","title":"List of publishers","text":"Category Topic Message type frame_id Hz QoS

    Clock

    /clock rosgraph_msgs/Clock - 100 Best effort,Volatile,Keep last/1

    Sensors

    Camera /sensing/camera/traffic_light/camera_info sensor_msgs/CameraInfo traffic_light_left_camera/camera_link 10 Best effort,Volatile,Keep last/1 Camera /sensing/camera/traffic_light/image_raw sensor_msgs/Image traffic_light_left_camera/camera_link 10 Best effort,Volatile,Keep last/1 GNSS /sensing/gnss/pose geometry_msgs/Pose gnss_link 1 Reliable,Volatile,Keep last/1 GNSS /sensing/gnss/pose_with_covariance geometry_msgs/PoseWithCovarianceStamped gnss_link 1 Reliable,Volatile,Keep last/1 IMU /sensing/imu/tamagawa/imu_raw sensor_msgs/Imu tamagawa/imu_link 30 Reliable,Volatile,Keep last/1000 Top LiDAR /sensing/lidar/top/pointcloud_raw sensor_msgs/PointCloud2 sensor_kit_base_link 10 Best effort,Volatile,Keep last/5 Top LiDAR /sensing/lidar/top/pointcloud_raw_ex sensor_msgs/PointCloud2 sensor_kit_base_link 10 Best effort,Volatile,Keep last/5

    Vehicle Status

    Velocity /vehicle/status/velocity_status autoware_vehicle_msgs/VelocityReport base_line 30 Reliable,Volatile,Keep last/1 Steering /vehicle/status/steering_status autoware_vehicle_msgs/SteeringReport - 30 Reliable,Volatile,Keep last/1 Control Mode /vehicle/status/control_mode autowar_vehicle_msgs/ControlModeReport - 30 Reliable,Volatile,Keep last/1 Gear /vehicle/status/gear_status autoware_vehicle_msgs/GearReport - 30 Reliable,Volatile,Keep last/1 Turn Indicators /vehicle/status/turn_indicators_status autoware_vehicle_msgs/TurnIndicatorsReport - 30 Reliable,Volatile,Keep last/1 Hazard Lights /vehicle/status/hazard_lights_status autoware_vehicle_msgs/HazardLightsReport - 30 Reliable,Volatile,Keep last/1

    Ground Truth

    Pose /awsim/ground_truth/vehicle/pose geometry_msgs/PoseStamped base_link 100 Reliable,Volatile,Keep last/1 V2I /perception/traffic_light_recognition/external/traffic_signals autoware_perception_msgs/msg/TrafficLightGroupArray - 10 Reliable,Volatile,Keep last/1"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/","title":"Preparing the connection between AWSIM and scenario_simulator_v2","text":""},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#preparing-the-connection-between-awsim-and-scenario_simulator_v2","title":"Preparing the connection between AWSIM and scenario_simulator_v2","text":"

    This tutorial describes: - how to modify scenario to work with AWSIM Labs - how to prepare the AWSIM Labs scene to work with scenario_simulator_v2

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#scenario-preparation-to-work-with-awsim-labs","title":"Scenario preparation to work with AWSIM Labs","text":"

    To run the created scenario with AWSIM Labs, necessary adjustments need to be made. After opening the generated .yaml file with a text editor of your choice, follow the steps below:

    1. CatalogLocation: [ ] should be removed and replaced with lines specifying the vehicle's properties. 
         VehicleCatalog:\n   Directory:\n   path: $(ros2 pkg prefix --share openscenario_experimental_catalog)/vehicle\n
    2. The file locations of the vector map and pointcloud map need to be changed. 
        RoadNetwork:\n    LogicFile:\n      filepath: /home/your-username/projects/autoware/src/simulator/shinjuku_map/map/lanelet2_map.osm\n    SceneGraphFile:\n      filepath: /home/your-username/projects/autoware/src/simulator/shinjuku_map/map/lanelet2_map.osm\n
    3. In order for the added NPC to be created by AWSIM Labs, the model3d: definition and the name of the desired prefab to be used should be entered.

        - name: Npc1\n        Vehicle:\n          name: ''\n          vehicleCategory: car\n          model3d: \"small_car\"\n
    4. The BoundingBox values should also be updated according to the preferred NPC model.\"Default AWSIM Labs asset catalog\" section provides features that can be utilized to use default models."},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#default-awsim-labs-asset-catalog","title":"Default AWSIM Labs asset catalog","text":"

    AWSIM Labs currently supports the following asset key values.

    The list can be extended if required. Appropriate values should be added to asst key list in the ScenarioSimulatorConnector component and the vehicle parameters in scenario simulator should match them.

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#ego-vehicle-entity-with-sensor","title":"Ego Vehicle Entity (with sensor)","text":"model3d boundingbox size (m) wheel base(m) front tread(m) rear tread(m) tier diameter(m) max steer(deg) lexus_rx450h width : 1.920 height : 1.700 length : 4.890 2.105 1.640 1.630 0.766 35"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#npc-vehicle-entity","title":"NPC Vehicle Entity","text":"model3d boundingbox size (m) wheel base(m) front tread(m) rear tread(m) tier diameter(m) max steer(deg) taxi width : 1.695 height : 1.515 length : 4.590 2.680 1.460 1.400 0.635 35 truck_2t width : 1.695 height : 1.960 length : 4.685 2.490 1.395 1.240 0.673 40 hatchback width : 1.695 height 1.515 length : 3.940 2.550 1.480 1.475 0.600 35 van width : 1.880 height : 2.285 length : 4.695 2.570 1.655 1.650 0.600 35 small_car width : 1.475 height 1.800 length : 3.395 2.520 1.305 1.305 0.557 35"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#npc-pedestrian-entity","title":"NPC Pedestrian Entity","text":"model3d boundingbox size (m) human width : 0.400 height : 1.800 length : 0.300"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#misc-object-entity","title":"Misc Object Entity","text":"model3d boundingbox size (m) sign_board width : 0.31 height : 0.58 length : 0.21"},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#scenarios-limitations","title":"Scenarios limitations","text":"

    Vast majority of features supported by scenario_simulator_v2 are supported with AWSIM Labs as well. Currently supported features are described in the scenario_simulator_v2's documentation.

    Features which are not supported when connected with AWSIM Labs are listed below.

    1. Controller properties used by attach_*_sensor
      • pointcloudPublishingDelay
      • isClairvoyant
      • detectedObjectPublishingDelay
      • detectedObjectPositionStandardDeviation
      • detectedObjectMissingProbability
      • randomSeed

    If those features are curcial for the scenario's execution, the scenario might not work properly.

    "},{"location":"Components/ScenarioSimulation/PreparingTheConnectionBetweenAWSIMAndScenarioSimulator/#awsim-labs-scene-preparation-to-work-with-scenario_simulator_v2","title":"AWSIM Labs scene preparation to work with scenario_simulator_v2","text":"
    1. Disable or remove random traffic and any pre-spawned NPCs
    2. Disable or remove V2I traffic lights publishing
    3. Disable or remove the clock publisher
    1. Add ScenarioSimulatorConnector prefab to the scene - located in Assets/ScenarioSimulatorConnector
    1. Add Ego Follow Camera object - most likely Main Camera
    1. If necessary update the asset_id to prefab mapping - key in the map can be used in the scenario
    1. Add TimeSourceSelector prefab to the scene - located in Assets/AWSIM-Labs/Scripts/Clock/Prefabs
    1. Configure Type in the TimeSourceSelector component to SS2
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/","title":"Setup Unity project for scenario simulation","text":""},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#running-awsim-labs-from-unity-editor-with-scenario_simulator_v2","title":"Running AWSIM Labs from Unity Editor with scenario_simulator_v2","text":"

    Below you can find instructions on how to setup the scenario execution using scenario_simulator_v2 with AWSIM Labs run from Unity Editor as a simulator The instruction assumes using the Ubuntu OS.

    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#prerequisites","title":"Prerequisites","text":"

    1. Build Autoware by following \"Build Autoware with scenario_simulator_v2\" section from the scenario simulator and AWSIM Labs quick start guide

    2. Follow Setup Unity Project tutorial

    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#running-the-demo","title":"Running the demo","text":"
    1. Open AutowareSimulationScenarioSimulator.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Launch scenario_test_runner. 
      source install/setup.bash\nros2 launch scenario_test_runner scenario_test_runner.launch.py                        \\\narchitecture_type:=awf/universe/20240605  record:=false                                         \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim.yaml'          \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                          \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\" \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#other-sample-scenarios","title":"Other sample scenarios","text":""},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#conventional-traffic-lights-demo","title":"Conventional traffic lights demo","text":"

    This scenario controls traffic signals in the scene based on OpenSCENARIO. It can be used to verify whether traffic light recognition pipeline works well in Autoware.

    ros2 launch scenario_test_runner scenario_test_runner.launch.py                                           \\\narchitecture_type:=awf/universe/20240605  record:=false                                                            \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim_conventional_traffic_lights.yaml' \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                                             \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\"                    \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/ScenarioSimulation/SetupUnityProjectForScenarioSimulation/#v2i-traffic-lights-demo","title":"V2I traffic lights demo","text":"

    This scenario publishes V2I traffic signals information based on OpenSCENARIO. It can be used to verify Autoware responds to V2I traffic lights information correctly.

    ros2 launch scenario_test_runner scenario_test_runner.launch.py                                  \\\narchitecture_type:=awf/universe/20240605  record:=false                                                   \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim_v2i_traffic_lights.yaml' \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                                    \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\"           \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"Components/Sensors/CameraSensor/","title":"Camera Sensor","text":""},{"location":"Components/Sensors/CameraSensor/#camerasensor","title":"CameraSensor","text":""},{"location":"Components/Sensors/CameraSensor/#introduction","title":"Introduction","text":"

    CameraSensor is a component that simulates an RGB camera. Autonomous vehicles can be equipped with many cameras used for various purposes. In the current version of AWSIM, the camera is used primarily to provide the image to the traffic light recognition module in Autoware.

    "},{"location":"Components/Sensors/CameraSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/CameraSensor.prefab\n
    "},{"location":"Components/Sensors/CameraSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The mentioned single CameraSensor has its own frame traffic_light_left_camera/camera_link in which its data is published. The sensor prefab is added to this frame. The traffic_light_left_camera/camera_link link is added to the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/CameraSensor/#camerasensorholder-script","title":"CameraSensorHolder (script)","text":"

    CameraSensorHolder (script) allows the sequential rendering of multiple camera sensors. To utilize it, each CameraSensor object should be attached as a child object of the CameraSensorHolder.

    "},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Camere Sensors - a collection of camera sensors used for rendering
    • Publish Hz - the frequency at which camera rendering, image processing and callbacks are executed
    • Render In Queue - camera sensors rendering sequence type: in queue (one after another) or all at the same frame
    "},{"location":"Components/Sensors/CameraSensor/#camerasensor-components","title":"CameraSensor Components","text":"

    For the CameraSensor to work properly, the GameObject to which the scripts are added must also have:

    • Camera component - the basic component that ensures the functionality of the camera as a device in Unity that capture and display the world to the player.
    • HD Additional Camera Data (script) - additional component that holds HDRP specific parameters for camera. This Component should be added automatically together with Camera component.

    TrafficLights recognition

    In case of problems with the recognition of traffic lights in Autoware, it may help to increase the image resolution and focal length of the camera in AWSIM.

    Camera settings

    If you would like to adjust the image captured by the camera, we encourage you to read this manual.

    The CameraSensor functionality is split into two scripts:

    • Camera Sensor (script) - acquires the image from the Unity camera, transforms it and saves to the BGR8 format, this format along with the camera parameters is its script output - script also calls the callback for it.
    • Camera Ros2 Publisher (script) - provides the ability to publish CameraSensor output as Image and CameraInfo messages type published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Sensors/CameraSensor/*\n

    In the same location there are also *.compute files containing used ComputeShaders.

    "},{"location":"Components/Sensors/CameraSensor/#camerasensor-script","title":"CameraSensor (script)","text":"

    Camera Sensor (script) is a core camera sensor component. It is responsible for applying OpenCV distortion and encoding to BGR8 format. The distortion model is assumed to be Plumb Bob. The script renders the image from the camera to Texture2D and transforms it using the distortion parameters. This image is displayed in the GUI and further processed to obtain the list of bytes in BGR8 format on the script output.

    The script uses two ComputeShaders, they are located in the same location as the scripts:

    • CameraDistortion - to correct the image using the camera distortion parameters,

    • RosImageShader - to encode two pixels color (bgr8 - 3 bytes) into one (uint32 - 4 bytes) in order to produce ROS Image BGR8 buffer.

    API type feature DoRender void Renders the Unity camera, applies OpenCV distortion to rendered image and update output data."},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 10Hz)
    • Image On GUI:
      • Show - if camera image should be show on GUI (default: true)
      • Scale - scale of reducing the image from the camera, 1 - will give an image of real size, 2 - twice smaller, etc. (default: 4)
      • X Axis - position of the upper left corner of the displayed image in the X axis, 0is the left edge (default: 0)
      • Y Axis - position of the upper left corner of the displayed image in the Y axis, 0 is the upper edge (default: 0)
    • Camera parameters
      • Width - image width (default: 1920)
      • Height - image height (default: 1080)
      • K1, K2, P1, P2, K3 - camera distortion coefficients for Plum Bob model(default: 0, 0, 0, 0, 0)
    • Camera Object - reference to the basic Camera component (default: None)
    • Distortion Shader - reference to ComputeShader asset about Distortion Shader functionality (default: None)
    • Ros Image Shader - reference to ComputeShader asset about Ros Image Shader functionality (default: None)
    "},{"location":"Components/Sensors/CameraSensor/#output-data","title":"Output Data","text":"

    The sensor computation output format is presented below:

    Category Type Description ImageDataBuffer byte[ ] Buffer with image data. CameraParameters CameraParameters Set of the camera parameters."},{"location":"Components/Sensors/CameraSensor/#cameraros2publisher-script","title":"CameraRos2Publisher (script)","text":"

    Converts the data output from CameraSensor to ROS2 Image and CameraInfo type messages and publishes them. The conversion and publication is performed using the Publish(CameraSensor.OutputData outputData) method, which is the callback triggered by Camera Sensor (script) for the current output.

    Due to the fact that the entire image is always published, the ROI field of the message is always filled with zeros. The script also ensures that binning is assumed to be zero and the rectification matrix is the identity matrix.

    Warning

    The script uses the camera parameters set in the CameraSensor script - remember to configure them depending on the camera you are using.

    "},{"location":"Components/Sensors/CameraSensor/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Image Topic - the ROS2 topic on which the Image message is published(default: \"/sensing/camera/traffic_light/image_raw\")
    • Camera Info Topic - the ROS2 topic on which the CameraInfo message is published(default: \"/sensing/camera/traffic_light/camera_info\")
    • Frame id - frame in which data is published, used in Header(default: \"traffic_light_left_camera/camera_link\")
    • Qos Settings - Quality of service profile used in the publication(default: Best effort, Volatile, Keep last, 1)
    "},{"location":"Components/Sensors/CameraSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 10Hz
    • QoS: Best effort, Volatile, Keep last/1
    Category Topic Message type frame_id Camera info /sensing/camera/traffic_light/camera_info sensor_msgs/CameraInfo traffic_light_left_camera/camera_link Camera image /sensing/camera/traffic_light/image_raw sensor_msgs/Image traffic_light_left_camera/camera_link"},{"location":"Components/Sensors/GNSSSensor/","title":"GNSS Sensor","text":""},{"location":"Components/Sensors/GNSSSensor/#gnsssensor","title":"GnssSensor","text":""},{"location":"Components/Sensors/GNSSSensor/#introduction","title":"Introduction","text":"

    GnssSensor is a component which simulates the position of vehicle computed by the Global Navigation Satellite System based on the transformation of the GameObject to which this component is attached. The GnssSensor outputs the position in the MGRS coordinate system.

    "},{"location":"Components/Sensors/GNSSSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/GnssSensor.prefab\n
    "},{"location":"Components/Sensors/GNSSSensor/#link","title":"Link","text":"

    GnssSensor has its own frame gnss_link in which its data is published. The sensor prefab is added to this frame. The gnss_link frame is added to the sensor_kit_base_link in the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/GNSSSensor/#components","title":"Components","text":"

    The GnssSensor functionality is split into two components:

    • Gnss Sensor (script) - it calculates the position as its output and calls the callback for it.
    • Gnss Ros2 Publisher (script) - provides the ability to publish GnssSensor output as PoseStamped and PoseWithCovarianceStamped published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/Gnss/*\n
    "},{"location":"Components/Sensors/GNSSSensor/#gnss-sensor-script","title":"Gnss Sensor (script)","text":"

    This is the main script in which all calculations are performed:

    1. the position of the Object in Unity is read,
    2. this position is transformed to the ROS2 coordinate system (MGRS offset is added here),
    3. the result of the transformation is saved as the output of the component,
    4. for the current output a callback is called (which can be assigned externally).
    "},{"location":"Components/Sensors/GNSSSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 100Hz)
    "},{"location":"Components/Sensors/GNSSSensor/#output-data","title":"Output Data","text":"Category Type Description Position Vector3 Position in the MGRS coordinate system."},{"location":"Components/Sensors/GNSSSensor/#gnss-ros2-publisher-script","title":"Gnss Ros2 Publisher (script)","text":"

    Converts the data output from GnssSensor to ROS2 PoseStamped and PoseWithCovarianceStamped messages. These messages are published on two separate topics for each type. The conversion and publication is performed using the Publish(GnssSensor.OutputData outputData) method, which is the callback triggered by Gnss Sensor (script) for the current output update.

    Covariance matrix

    The row-major representation of the 6x6 covariance matrix is filled with 0 and does not change during the script run.

    "},{"location":"Components/Sensors/GNSSSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Pose Topic - the ROS2 topic on which the message PoseStamped type is published(default: \"/sensing/gnss/pose\")
    • Pose With Covariance Stamped Topic - the ROS2 topic on which the message PoseWithCovarianceStamped type is published(default: \"/sensing/gnss/pose_with_covariance\")
    • Frame id - frame in which data are published, used in Header(default: \"gnss_link\")
    • Qos Settings - Quality of service profile used in the publication(default is assumed as \"system_default\": Reliable, Volatile, Keep last, 1)
    "},{"location":"Components/Sensors/GNSSSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 1Hz
    • QoS: Reliable, Volatile, Keep last/1
    Category Topic Message type frame_id Pose /sensing/gnss/pose geometry_msgs/Pose gnss_link Pose with Covariance /sensing/gnss/pose_with_covariance geometry_msgs/PoseWithCovarianceStamped gnss_link"},{"location":"Components/Sensors/IMUSensor/","title":"IMU Sensor","text":""},{"location":"Components/Sensors/IMUSensor/#imusensor","title":"IMUSensor","text":""},{"location":"Components/Sensors/IMUSensor/#introduction","title":"Introduction","text":"

    IMUSensor is a component that simulates an IMU (Inertial Measurement Unit) sensor. Measures acceleration (\\({m}/{s^2}\\)) and angular velocity (\\({rad}/{s}\\)) based on the transformation of the GameObject to which this component is attached.

    "},{"location":"Components/Sensors/IMUSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/IMUSensor.prefab\n
    "},{"location":"Components/Sensors/IMUSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    IMUSensor has its own frame tamagawa/imu_link in which its data is published. The sensor prefab is added to this frame. The tamagawa/imu_link link is added to the sensor_kit_base_link in the base_link object located in the URDF.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/IMUSensor/#components","title":"Components","text":"

    The IMUSensor functionality is split into two scripts:

    • IMU Sensor (script) - it calculates the acceleration and angular velocity as its output and calls the callback for it.
    • Imu Ros2 Publisher (script) - provides the ability to publish IMUSensor output as Imu message type published on a specific ROS2 topics.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Sensors/Imu/*\n
    "},{"location":"Components/Sensors/IMUSensor/#imu-sensor-script","title":"IMU Sensor (script)","text":"

    This is the main script in which all calculations are performed:

    • the angular velocity is calculated as the derivative of the orientation with respect to time,
    • acceleration is calculated as the second derivative of position with respect to time,
    • in the calculation of acceleration, the gravitational vector is considered - which is added.

    Warning

    If the angular velocity about any axis is NaN (infinite), then angular velocity is published as vector zero.

    "},{"location":"Components/Sensors/IMUSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Output Hz - frequency of output calculation and callback (default: 30Hz)
    "},{"location":"Components/Sensors/IMUSensor/#output-data","title":"Output Data","text":"Category Type Description LinearAcceleration Vector3 Measured acceleration (m/s^2) AngularVelocity Vector3 Measured angular velocity (rad/s)"},{"location":"Components/Sensors/IMUSensor/#imu-ros2-publisher-script","title":"Imu Ros2 Publisher (script)","text":"

    Converts the data output from IMUSensor to ROS2 Imu type message and publishes it. The conversion and publication is performed using the Publish(IMUSensor.OutputData outputData) method, which is the callback triggered by IMU Sensor (script) for the current output.

    Warning

    In each 3x3 covariance matrices the row-major representation is filled with 0 and does not change during the script run. In addition, the field orientation is assumed to be {1,0,0,0} and also does not change.

    "},{"location":"Components/Sensors/IMUSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Topic - the ROS2 topic on which the message is published(default: \"/sensing/imu/tamagawa/imu_raw\")
    • Frame id - frame in which data is published, used in Header(default: tamagawa/imu_link\")
    • Qos Settings - Quality of service profile used in the publication(default: Reliable, Volatile, Keep last, 1000)
    "},{"location":"Components/Sensors/IMUSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 30Hz
    • QoS: Reliable, Volatile, Keep last/1000
    Category Topic Message type frame_id IMU data /sensing/imu/tamagawa/imu_raw sensor_msgs/Imu tamagawa/imu_link"},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/","title":"Add New LiDAR","text":""},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#add-a-new-lidar","title":"Add a new LiDAR","text":"

    RGLUnityPlugin (RGL) comes with a number of the most popular LiDARs model definitions and ready-to-use prefabs. However, there is a way to create your custom LiDAR. This section describes how to add a new LiDAR model that works with RGL, then create a prefab for it and add it to the scene.

    Supported LiDARs

    Not all lidar types are supported by RGL. Unfortunately, in the case of MEMs LiDARs, there is a non-repetitive phenomenon - for this reason, the current implementation is not able to reproduce their work.

    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#1-add-a-new-lidar-model","title":"1. Add a new LiDAR model","text":"

    The example shows the addition of a LiDAR named NewLidarModel.

    To add a new LiDAR model, perform the following steps:

    1. Navigate to Assets/RGLUnityPlugin/Scripts/LidarModels.

    2. Add its name to the LidarModels.cs at the end of the enumeration. The order of enums must not be changed to keep existing prefabs working.

    3. Now, it is time to define the laser (also called a channel) distribution of the LiDAR.

      Info

      If your LiDAR:

      - has a uniform laser distribution\n- has the equal range for all of the lasers\n- fire all of the rays (beams) at the same time\n

      You can skip this step and use our helper method to generate a simple uniform laser array definition (more information in the next step).

      1. Laser distribution is represented by LaserArray consists of:

        • centerOfMeasurementLinearOffsetMm - 3D translation from the game object's origin to LiDAR's origin. Preview in 2D:

        • focalDistanceMm - Distance from the sensor center to the focal point where all laser beams intersect.

        • lasers - array of lasers (channels) with a number of parameters:

          • horizontalAngularOffsetDeg - horizontal angle offset of the laser (Azimuth)
          • verticalAngularOffsetDeg - vertical angle offset of the laser (Elevation)
          • verticalLinearOffsetMm - vertical offset of the laser (translation from origin)
          • ringId - Id of the ring (in most cases laser Id)
          • timeOffset - time offset of the laser firing in milliseconds (with reference to the first laser in the array)
          • minRange - minimum range of the laser (set if lasers have different ranges)
          • maxRange - maximum range of the laser (set if lasers have different ranges)

      2. To define a new laser distribution create a new class in the LaserArrayLibrary.cs

        • Add a new public static instance of LaserArray with the definition.

        In this example, NewLidarModel laser distribution consists of 5 lasers with

        - elevations: 15, 10, 0, -10, -15 degrees\n- azimuths: 1.4, -1.4, 1.4, -1.4, 1.4 degrees\n- ring Ids: 1, 2, 3, 4, 5\n- time offsets: 0, 0.01, 0.02, 0.03, 0.04 milliseconds\n- an equal range that will be defined later\n

        Coordinate system

        Keep in mind that Unity has a left-handed coordinate system, while most of the LiDAR's manuals use a right-handed coordinate system. In that case, reverse sign of the values of the angles.

    4. The last step is to create a LiDAR configuration by adding an entry to LidarConfigurationLibrary.cs

      Add a new item to the ByModel dictionary that collects LiDAR model enumerations with their BaseLidarConfiguration choosing one of the implementations:

      • UniformRangeLidarConfiguration - lidar configuration for uniformly distributed rays along the horizontal axis with a uniform range for all the rays (it contains minRange and maxRange parameters additionally)
      • LaserBasedRangeLidarConfiguration - lidar configuration for uniformly distributed rays along the horizontal axis with ranges retrieved from lasers description
      • Or create your custom implementations in LidarConfiguration.cs like:
        • HesaiAT128LidarConfiguration
        • HesaiQT128C2XLidarConfiguration
        • HesaiPandar128E4XLidarConfiguration

      Lidar configuration parameters descrition

      Please refer to this section for the detailed description of all configuration parameters.

    5. Done. New LiDAR preset should be available via Unity Inspector.

      Frame rate of the LiDAR can be set in the Automatic Capture Hz parameter.

      Note: In the real-world LiDARs, frame rate affects horizontal resolution. Current implementation separates these two parameters. Keep in mind to change it manually.

    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#2-create-new-lidar-prefab","title":"2. Create new LiDAR prefab","text":"
    1. Create an empty object and name it appropriately according to the LiDAR model.
    2. Attach script LidarSensor.cs to created object.
    3. Set the new added LiDAR model in Model Preset field, check if the configuration loads correctly. You can now customize it however you like.
    4. (Optional) Attach script PointCloudVisualization.cs for visualization purposes.
    5. For publishing point cloud via ROS2 attach script RglLidarPublisher.cs script to created object.
    6. Set the topics on which you want the data to be published and their frame.
    7. Save the prefab in the project.
    "},{"location":"Components/Sensors/LiDARSensor/AddNewLiDAR/#3-test-your-prefab","title":"3. Test your prefab","text":"
    1. Create a new scene (remember to add the SceneManager) or use one of the existing sample scenes.

    2. Add the prepared LiDAR prefab by drag the prefab file and drop it into a scene.

    3. A LiDAR GameObject should be instantiated automatically

    4. Now you can run the scene and check how your LiDAR works.

    Success

    We encourage you to develop a vehicle using the new LiDAR you have added - learn how to do this here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/","title":"LiDAR Sensor","text":""},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#lidarsensor","title":"LidarSensor","text":""},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#introduction","title":"Introduction","text":"

    LidarSensor is the component that simulates the LiDAR (Light Detection and Ranging) sensor. LiDAR works by emitting laser beams that bounce off objects in the environment, and then measuring the time it takes for the reflected beams to return, allowing the sensor to create a 3D map of the surroundings. This data is used for object detection, localization, and mapping.

    LiDAR in an autonomous vehicle can be used for many purposes. The ones mounted on the top of autonomous vehicles are primarily used

    • to scan the environment for localization in space
    • to detect and identify obstacles such as approaching vehicles, pedestrians or other objects in the driving path.

    LiDARs placed on the left and right sides of the vehicle are mainly used to monitor the traffic lane and detect vehicles moving in adjacent lanes, enabling safe maneuvers such as lane changing or turning.

    LidarSensor component is a part of RGLUnityPlugin that integrates the external RobotecGPULidar (RGL) library with Unity. RGL also allows to provide additional information about objects, more about it here.

    Use RGL in your scene

    If you want to use RGL in your scene, make sure the scene has an SceneManager component added and all objects meet the usage requirements.

    RGL default scenes

    If you would like to see how LidarSensor works using RGL or run some tests, we encourage you to familiarize yourself with the RGL test scenes section.

    Supported LiDARs

    The current scripts implementation allows you to configure the prefab for any mechanical LiDAR. You can read about how to do it here. MEMS-based LiDARs due to their different design are not yet fully supported.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#prefabs","title":"Prefabs","text":"

    Prefabs can be found under the following path:

    Assets/AWSIM/Prefabs/RobotecGPULidars/*\n

    The table of available prefabs can be found below:

    LiDAR Path Appearance HESAI Pandar40P HesaiPandar40P.prefab HESAI PandarQT64 HesaiPandarQT64.prefab HESAI PandarXT32 HesaiPandarXT32.prefab HESAI QT128C2X HesaiQT128C2X.prefab HESAI Pandar128E4X HesaiPandar128E4X.prefab HESAI AT128 E2X HesaiAT128E2X.prefab Ouster OS1-64 OusterOS1-64.prefab Velodyne VLP-16 VelodyneVLP16.prefab Velodyne VLC-32C VelodyneVLP32C.prefab Velodyne VLS-128-AP VelodyneVLS128.prefab"},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    LidarSensor is configured in default vehicle EgoVehicle prefab. It is added to URDF object as a child of sensor_kit_base_link. LidarSensor placed in this way does not have its own frame, and the data is published relative to sensor_kit_base_link. More details about the location of the sensors in the vehicle can be found here.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    Additional LiDARs

    For a LiDAR placed on the left side, right side or rear, an additional link should be defined.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#components-and-resources","title":"Components and Resources","text":"

    The LiDAR sensor simulation functionality is split into three components:

    • Lidar Sensor (script) - provides lidar configuration, creates RGL pipeline to simulate lidar, and performs native RGL raytrace calls,
    • Rgl Lidar Publisher (script) - extends RGL pipeline with nodes to publish ROS2 messages.
    • Point Cloud Visualization (script) - visualizes point cloud collected by sensor.

    Moreover, the scripts use Resources to provide configuration for prefabs of supported lidar models:

    • LaserModels - provides a list of supported models,
    • LaserArrayLibrary - provides data related to laser array construction for supported models,
    • LaserConfigurationLibrary - provides full configuration, with ranges and noise for supported models.

    These are elements of the RGLUnityPlugin, you can read more here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#lidar-sensor-script","title":"Lidar Sensor (script)","text":"

    This is the main component that creates the RGL node pipeline for the LiDAR simulation. The pipeline consists of:

    • setting ray pattern,
    • transforming rays to represent pose of the sensor on the scene,
    • applying Gaussian noise,
    • performing raytracing,
    • removing non-hits from the result point cloud,
    • transforming point cloud to sensor frame coordinate system.
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Automatic Capture Hz - the rate of sensor processing (default: 10Hz)
    • Model Preset - allows selecting one of the built-in LiDAR models (default: RangeMeter)
    • Apply Distance Gaussian Noise - enable/disable distance Gaussian noise (default: true)
    • Apply Angular Gaussian Noise - enable/disable angular Gaussian noise (default: true)
    • Apply Velocity Distortion - enable/disable velocity distortion (default: false)
    • Configuration:
      • Laser Array - geometry description of lidar's array of lasers, should be prepared on the basis of the manual for a given model of LiDAR (default: loaded from LaserArrayLibrary)
      • Horizontal Resolution - the horiontal resolution of laser array firings
      • Min H Angle - minimum horizontal angle, left (default: 0)
      • Max H Angle - maximum horizontal angle, right (default: 0)
      • Laser Array Cycle Time - time between two consecutive firings of the whole laser array in milliseconds (default: 0); used for velocity distortion feature.
      • Beam Divergence - represents the deviation of photons from a single beam emitted by a LiDAR sensor (in degrees); used for simulating snow only (private feature).
      • Noise Params:
        • Angular Noise Type - angular noise type(default: Ray Based)
        • Angular Noise St Dev - angular noise standard deviation in degree(default: 0.05729578)
        • Angular Noise Mean - angular noise mean in degrees(default: 0)
        • Distance Noise St Dev Base - distance noise standard deviation base in meters(default: 0.02)
        • Distance Noise Rise Per Meter - distance noise standard deviation rise per meter(default: 0)
        • Distance Noise Mean - distance noise mean in meters(default: 0)
      • Additional options (available for some Lidar Model Preset)
        • Min Range - minimum range of the sensor (if not avaiable, the range is different for each laser in Laser Array)
        • Max Range - maximum range of the sensor (if not avaiable, the range is different for each laser in Laser Array)
        • High Resolution Mode Enabled - whether to activate high resolution mode (available for Hesai Pandar 128E4X LiDAR model)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data","title":"Output Data","text":"

    LidarSensor provides public methods to extend this pipeline with additional RGL nodes. In this way, other components can request point cloud processing operations and receive data in the desired format.

    Example of how to get XYZ point cloud data:

    1. To obtain point cloud data from another component you have to create a new RGLNodeSequence with RGL node to yield XYZ field and connect it to LidarSensor: 
      rglOutSubgraph = new RGLNodeSequence().AddNodePointsYield(\"OUT_XYZ\", RGLField.XYZ_F32);\nlidarSensor = GetComponent<LidarSensor>();\nlidarSensor.ConnectToWorldFrame(rglOutSubgraph); // you can also connect to Lidar frame using ConnectToLidarFrame\n// You can add a callback to receive a notification when new data is ready\nlidarSensor.onNewData += HandleLidarDataMethod;\n
    2. To get data from RGLNodeSequence call GetResultData: 
      Vector3[] xyz = new Vector3[0];\nrglOutSubgraph.GetResultData<Vector3>(ref xyz);\n
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#rgl-lidar-publisher-script","title":"Rgl Lidar Publisher (script)","text":"

    RglLidarPublisher extends the main RGL pipeline created in LidarSensor with RGL nodes that produce point clouds in specific format and publish them to the ROS2 topic. Thanks to the ROS2 integration with RGL, point clouds can be published directly from the native library. RGL creates ROS2 node named /RobotecGPULidar with publishers generated by RGL nodes.

    Currently, RglLidarPublisher implements two ROS2 publishers:

    • rosPCL24 - a 24-byte point cloud format used by Autoware
    • rosPCL48 - a 48-byte extended version point cloud format used by Autoware

    Details on the construction of these formats are available in the PointCloudFormats under the following path:

    Assets/AWSIM/Scripts/Sensors/LiDAR/PointCloudFormats.cs\n

    rosPCL48 format

    For a better understanding of the rosPCL48 format, we encourage you to familiarize yourself with the point cloud pre-processing process in Autoware, which is described here.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • Pcl 24 Topic - the ROS2 topic on which the PointCloud2 message is published(default: \"lidar/pointcloud\")
    • Pcl 48 Topic - the ROS2 topic on which the PointCloud2 message is published(default: \"lidar/pointcloud_ex\")
    • Frame ID - frame in which data are published, used in Header (default: \"world\")
    • Publish PCL24 - if publish cloud PCL24 (default: true)
    • Publish PCL48 - if publish cloud PCL48 (default: true)
    • Qos Settings - Quality of service profile used in the publication(default: Best effort, Volatile, Keep last, 5)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#published-topics","title":"Published Topics","text":"
    • Frequency: 10Hz
    • QoS: Best effort, Volatile, Keep last/5
    Category Topic Message type frame_id PointCloud 24-byte format /lidar/pointcloud sensor_msgs/PointCloud2 world PointCloud 48-byte format /lidar/pointcloud_ex sensor_msgs/PointCloud2 world"},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#point-cloud-visualization-script","title":"Point Cloud Visualization (script)","text":"

    A component visualizing a point cloud obtained from RGL in the form of a Vector3 list as colored points in the Unity scene. Based on the defined color table, it colors the points depending on the height at which they are located.

    The obtained points are displayed as the vertices of mesh, and their coloring is possible thanks to the use of PointCloudMaterial material which can be found in the following path:

    Assets/RGLUnityPlugin/Resources/PointCloudMaterial.mat\n

    Point Cloud Visualization preview:

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Point Shape - the shape of the displayed points (default: Box)
    • Point Size - the size of the displayed points (default: 0.05)
    • Colors - color list used depending on height(default: 6 colors: red, orange, yellow, green, blue, violet)
    • Auto Compute Coloring Heights - automatic calculation of heights limits for a list of colors (default: false)
    • Min Coloring Height - minimum height value from which color matching is performed, below this value all points have the first color from the list (default: 0)
    • Max Coloring Height - maximum height value from which color matching is performed, above this value all points have the last color from the list (default: 20)
    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#read-material-information","title":"Read material information","text":"

    To ensure the publication of the information described in this section, GameObjects must be adjusted accordingly. This tutorial describes how to do it.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#intensity-texture","title":"Intensity Texture","text":"

    RGL Unity Plugin allows assigning an Intensity Texture to the GameObjects to produce a point cloud containing information about the lidar ray intensity of hit. It can be used to distinguish different levels of an object's reflectivity.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data_1","title":"Output data","text":"

    Point cloud containing intensity is published on the ROS2 topic via RglLidarPublisher component. The intensity value is stored in the intensity field of the sensor_msgs/PointCloud2 message.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#instance-segmentation","title":"Instance segmentation","text":"

    RGL Unity Plugin allows assigning an ID to GameObjects to produce a point cloud containing information about hit objects. It can be used for instance/semantic segmentation tasks. This tutorial describes how to do it.

    LidarInstanceSegmentationDemo

    If you would like to see how LidarInstanceSegmentationDemo works using RGL or run some tests, we encourage you to familiarize yourself with this section.

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#output-data_2","title":"Output data","text":"

    Point cloud containing hit objects IDs is published on the ROS2 topic via RglLidarPublisher component. It is disabled by default. Properties related to this feature are marked below:

    "},{"location":"Components/Sensors/LiDARSensor/LiDARSensor/#dictionary-mapping","title":"Dictionary mapping","text":"

    The resulting simulation data contains only the id of objects without their human-readable names. To facilitate the interpretation of such data, a function has been implemented to save a file with a dictionary mapping instance ID to GameObject names. It writes pairs of values in the yaml format:

    • The name of the GameObject
    • Category ID of SemanticCategory component

    To enable saving dictionary mapping set output file path to the Semantic Category Dictionary File property in the Scene Manager component:

    The dictionary mapping file will be saved at the end of the simulation.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/","title":"RGLUnityPlugin","text":""},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#rglunityplugin","title":"RGLUnityPlugin","text":"

    Robotec GPU Lidar (RGL) is an open source high performance lidar simulator running on CUDA-enabled GPUs. It is a cross-platform solution compatible with both Windows and Linux operating systems. RGL utilizes RTX cores for acceleration, whenever they are accessible.

    RGL is used in AWSIM for performance reasons. Thanks to it, it is possible to perform a large number of calculations using the GPU, which is extremely helpful due to the size of the scenes. AWSIM is integrated with RGL out-of-the-box - using RGLUnityPlugin asset.

    Warning

    If you want to use RGL in your scene, make sure the scene has an RGLSceneManager component added and all objects meet the usage requirements.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#concept","title":"Concept","text":"

    Describing the concept of using RGL in AWSIM, we distinguish:

    • Mesh - a handle to the on-GPU data of the 3D model of objects that in AWSIM are provided in the form of Mesh Filter component. RGLUnityPlugin supports two types of meshes: static (rendered by Mesh Renderer) and animated (rendered by Skinned Mesh Renderer). Static meshes could be shared between Entities.
    • Entity - represents a 3D object on the scene with its position and rotation. It consists of a lightweight reference to a Mesh and a transformation matrix of the object.
    • Scene - a location where raytracing occurs. It is a set of entites uploaded by SceneManager script to the RGL Native Library.
    • Node - performs specific operations such as setting rays for raytracing, transforming rays, performing raytracing, and manipulating output formats. In AWSIM, the main sequence of RGL nodes that simulates LiDAR is created in the LidarSensor script. Other scripts usually create nodes to get requested output or preprocess point cloud, and then connect those nodes to the LidarSensor.
    • Graph - a collection of connected Nodes that can be run to calculate results. It allows users to customize functionality and output format by adding or removing Nodes.

    Producing a point cloud is based on the use of a Scene containing Entities with Meshes, and placing an Ego Entity with LiDAR sensor that creates a Graph describing ray pattern and performing raytracing. In subsequent frames of the simulation, SceneManager synchronizes the scene between Unity and RGL, and LiDAR sensor updates rays pose on the scene and triggers Graph to perform raytracing and format desired output.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#package-structure","title":"Package structure","text":"

    RGLUnityPlugin asset contains:

    • Plugins - dynamically loaded libraries for Windows and Linux (*.dll and *.so files).
    • Resources - visualization shader and material.
    • Scripts - scripts for using RGL in the Unity - details below.
    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#scripts","title":"Scripts","text":"
    • SceneManager - responsible for syncing the scene between Unity and RGL.
    • LidarSensor - provide lidar configuration and create RGL pipeline to simulate lidar.
    • PointCloudVisualization - visualize point cloud on the Unity scene.
    • IntensityTexture - adds slot for Intensity Texture ID to the GameObject
    • SemanticCategory - adds category ID to the GameObject
    • RGLDebugger - provides configuration for Native RGL debug tools (logging and tape).
    • A set of classes providing tools to define LiDAR specification (mostly: ray poses):
      • LidarModels - enumeration of some real-world LiDARs names.
      • LidarConfiguration - top-level configuration class, horizontal ranges, distance range, laser array.
      • LidarConfigurationLibrary - provides a number of pre-defined LidarConfigurations.
      • LaserArray - definition of a (vertical) array of lasers.
      • LaserArrayLibrary - provides a number of pre-defined LaserArrays.
      • Laser - describes offsets of a single laser within a LaserArray.
      • LidarNoiseParams - describes a LiDAR noise that can be simulated
    • LowLevelWrappers scripts - provides some convenience code to call Native RGL functions.
    • Utilities scripts - miscellaneous utilities to make rest of the code clearer.
    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#scenemanager","title":"SceneManager","text":"

    Each scene needs SceneManager component to synchronize models between Unity and RGL. On every frame, it detects changes in the Unity's scene and propagates the changes to native RGL code. When necessary, it obtains 3D models from GameObjects on the scene, and when they are no longer needed, it removes them.

    Three different strategies to interact with in-simulation 3D models are implemented. SceneManager uses one of the following policies to construct the scene in RGL:

    • Only Colliders - data is computed based on the colliders only, which are geometrical primitives or simplified Meshes. This is the fastest option, but will produce less accurate results, especially for the animated entities.
    • Regular Meshes And Colliders Instead Of Skinned - data is computed based on the regular meshes for static Entities (with MeshRenderers component) and the colliders for animated Entities (with SkinnedMeshRenderer component). This improves accuracy for static Entities with a negligible additional performance cost.
    • Regular Meshes And Skinned Meshes - uses regular meshes for both static and animated Entities. This incurs additional performance, but produces the most realistic results.
    Mesh Source Strategy Static Entity Animated Entity (NPC) Only Colliders Collider Collider Regular Meshes And Colliders Instead Of Skinned Regular Mesh Collider Regular Meshes And Skinned Meshes Regular Mesh Regular Mesh

    Mesh source can be changed in the SceneManager script properties:

    Performance

    SceneManager performance depends on mesh source option selected.

    "},{"location":"Components/Sensors/LiDARSensor/RGLUnityPlugin/#usage-requirements","title":"Usage requirements","text":"

    Objects, to be detectable by RGL, must fulfill the following requirements:

    1. Contain one of the components: Collider, Mesh Renderer, or Skinned Mesh Renderer - it depends on SceneManager mesh source parameter.

    2. Be readable from CPU-accessible memory - it can be achieved using the Read/Write Enabled checkbox in mesh settings.

      Readable objects

      Primitive Objects are readable by default.

      Example

      The activated Readable option in the mesh should look like this.

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/","title":"Read Material Information","text":"

    RGL Unity Plugin allows to:

    • assigning an Intensity Texture to the GameObjects to produce a point cloud containing information about the lidar ray intensity of hit. It can be used to distinguish different levels of an object's reflectivity.
    • assigning an ID to GameObjects to produce a point cloud containing information about hit objects. It can be used for instance/semantic segmentation tasks. Below describes how to ensure the publication of this information.
    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#add-intensity-texture-assignment","title":"Add Intensity Texture assignment","text":"

    To enable reading material information, add IntensityTexture component to every GameObject that is expected to have non-default intensity values.

    After that desired texture has to be inserted into the Intensity Texture slot.

    The texture has to be in R8 format. That means 8bit in the red channel (255 possible values).

    When the texture is assigned, the intensity values will be read from the texture and added to the point cloud if and only if the mesh component in the GameObject has a set of properly created texture coordinates.

    The expected number of texture coordinates is equal to the number of vertices in the mesh. The quantity of indices is not relevant. In other cases, the texture will be no read properly.

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#add-id-assignment","title":"Add ID assignment","text":"

    To enable segmentation, add SemanticCategory component to every GameObject that is expected to have a distinct ID. All meshes that belong to a given object will inherit its ID. ID inheritance mechanism allows IDs to be overwritten for individual meshes/objects. This solution also enables the creation of coarse categories (e.g., Pedestrians, Vehicles)

    Example

    SemanticCategory component is assigned to the Taxi GameObject. All meshes in the Taxi GameObject will have the same instance ID as Taxi:*

    Example

    The driver has its own SemanticCategory component, so his instance ID will differ from the rest of the meshes:

    Example

    SemanticCategory component is assigned to the Vehicles GameObject that contains all of the cars on the scene:

    "},{"location":"Components/Sensors/LiDARSensor/ReadMaterialInformation/#dictionary-mapping","title":"Dictionary mapping","text":"

    The resulting simulation data contains only the id of objects without their human-readable names. To facilitate the interpretation of such data, a function has been implemented to save a file with a dictionary mapping instance ID to GameObject names. It writes pairs of values in the yaml format:

    • The name of the GameObject
    • Category ID of SemanticCategory component

    To enable saving dictionary mapping set output file path to the Semantic Category Dictionary File property in the Scene Manager component:

    The dictionary mapping file will be saved at the end of the simulation.

    "},{"location":"Components/Sensors/VehicleStatusSensor/","title":"Vehicle Status Sensor","text":""},{"location":"Components/Sensors/VehicleStatusSensor/#vehiclestatussensor","title":"VehicleStatusSensor","text":""},{"location":"Components/Sensors/VehicleStatusSensor/#introduction","title":"Introduction","text":"

    VehicleStatusSensor is a component that is designed to aggregate information about the current state of the vehicle. It aggregates information about:

    • Control mode - currently active control mode, e.g. AUTONOMOUS or MANUAL.
    • Gear status - currently engaged gearbox gear, e.g. DRIVE or REVERSE.
    • Steering status - current angle of the steering tire in radians left, e.g. 0.1745 (10\u00b0).
    • Turn indicators status - current status of the direction indicators, e.g. DISABLE or ENABLE_LEFT.
    • Hazard lights status - current status of the hazard lights, e.g. DISABLE or ENABLE.
    • Velocity status - current lateral, longitudinal and heading velocities values, e.g {0.2, 0.0, 0.0}.
    "},{"location":"Components/Sensors/VehicleStatusSensor/#prefab","title":"Prefab","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/VehicleStatusSensor.prefab\n
    "},{"location":"Components/Sensors/VehicleStatusSensor/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    This sensor is added directly to the URDF link in the EgoVehicle prefab.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#components","title":"Components","text":"

    All features are implemented within the Vehicle Report Ros2 Publisher (script) which can be found under the following path:

    Assets/AWSIM/Prefabs/Sensors/*\n
    "},{"location":"Components/Sensors/VehicleStatusSensor/#vehicle-report-ros2-publisher-script","title":"Vehicle Report Ros2 Publisher (script)","text":"

    The script is responsible for updating and publishing each of the aggregated data on a separate topic. Therefore, it has 6 publishers publishing the appropriate type of message with a constant frequency - one common for all data.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • * Report Topic - topic on which suitable type of information is published(default: listed in the table below)
    • Publish Hz - frequency of publications on each topic(default: 30Hz)
    • Frame ID - frame in which data is published, used in Header(default: base_link)
    • QoS- Quality of service profile used in the publication(default assumed as \"system_default\": Reliable, Volatile, Keep last/1)
    • Vehicle - the object from which all published data are read(default: None)

    Vehicle configuration

    An important element of the script configuration that must be set is the scene Object (Vehicle). It will be used for reading all the data needed. The appropriate EgoVehicle object should be selected.

    If you can't select the right object, make sure it's set up correctly - it has got added all the scripts needed for EgoVehicle.

    "},{"location":"Components/Sensors/VehicleStatusSensor/#published-topics","title":"Published topics","text":"
    • Frequency: 30Hz
    • QoS: Reliable, Volatile, Keep last/1
    Category Topic Message type frame_id Control mode /vehicle/status/control_mode autoware_vehicle_msgs/ControlModeReport - Gear status /vehicle/status/gear_status autoware_vehicle_msgs/GearReport - Steering status /vehicle/status/steering_status autoware_vehicle_msgs/SteeringReport - Turn indicators status /vehicle/status/turn_indicators_status autoware_vehicle_msgs/TurnIndicatorsReport - Hazard lights status /vehicle/status/hazard_lights_status autoware_vehicle_msgs/HazardLightsReport - Velocity status /vehicle/status/velocity_status autoware_vehicle_msgs/VelocityReport base_line"},{"location":"Components/Traffic/NPCs/Pedestrian/","title":"Pedestrian","text":""},{"location":"Components/Traffic/NPCs/Pedestrian/#introduction","title":"Introduction","text":"

    NPCPedestrian is an object that simulates a human standing or moving on the scene. It can move cyclically in any chosen place thanks to the available scripts. Traffic light tracking will be implemented in the future.

    Sample scene

    If you would like to see how NPCPedestrian works or run some tests, we encourage you to familiarize yourself with the NPCPedestrianSample default scene described in this section.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#prefab-and-fbx","title":"Prefab and Fbx","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Pedestrians/humanElegant.prefab\n
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#visual-elements","title":"Visual elements","text":"

    Prefab is developed using models available in the form of *.fbx file. From this file, the visual elements of the model, Animator and LOD were loaded. The Animator and LOD are added as components of the main-parent GameObject in prefab, while the visual elements of the model are added as its children.

    *.fbx file can be found under the following path:

    Assets/AWSIM/Models/NPCs/Pedestrians/Human/humanElegant.fbx\n

    NPCPedestrian prefab has the following content:

    The ReferencePoint is used by the NPC Pedestrian (script) described here.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    Pedestrians implemented in the scene are usually added in one aggregating object - in this case it is NPCPedestrians. This object is added to the Environment prefab.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#components","title":"Components","text":"

    There are several components responsible for the full functionality of NPCPedestrian:

    • Animator - provides motion animations in the scene, which are composed of clips controlled by the controller.
    • LOD Group - provides level of detail configuration for shaders - affects GPU usage.
    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • NPC Pedestrian (script) - ensures that the movement of the object is combined with animation.
    • Simple Pedestrian Walker Controller (script) - provides pedestrian movement in a specific direction and distance in a cyclical manner.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/NPCs/Pedestrians/*\n
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. In order to connect the animation to the object, the Is Kinematic option must be enabled. By setting Is Kinematic, each NPCPedestrian object will have no physical interaction with other objects - it will not react to a vehicle that hits it. The Use Gravity should be turned off - the correct position of the pedestrian in relation to the ground is ensured by the NPC Pedestrian (script). In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#lod-level-of-detail","title":"LOD (Level of Detail)","text":"

    LOD provides dependence of the level of detail of the object depending on the ratio of the GameObject\u2019s screen space height to the total screen height. The pedestrian model has two object groups: suffixed LOD0 and LOD1. LOD0 objects are much more detailed than LOD1 - they have many more vertices in the Meshes. Displaying complex meshes requires more performance, so if the GameObject is a small part of the screen, less complex LOD1 objects are used.

    In the case of the NPCPedestrian prefab, if its object is less than 25% of the height of the screen then objects with the LOD1 suffix are used. For values less than 1% the object is culled.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#animator","title":"Animator","text":"

    Animator component provides animation assignments to a GameObject in the scene. It uses a developed Controller which defines which animation clips to use and controls when and how to blend and transition between them.

    The AnimationController for humans should have the two float parameters for proper transitions. Transitions between animation clips are made depending on the values of these parameters:

    • moveSpeed - pedestrian movement speed in \\({m}/{s}\\),
    • rotateSpeed - pedestrian rotation speed in \\({rad}/{s}\\).

    Developed controller can be found in the following path: Assets/AWSIM/Models/NPCs/Pedestrians/Human/Human.controller

    Walking to running transition

    The example shows the state of walking and then transitions to running as a result of exceeding the condition \\(\\mathrm{moveSpeed} > 1.6\\)

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#npc-pedestrian-script","title":"NPC Pedestrian (script)","text":"

    The script takes the Rigidbody and Animator components and combines them in such a way that the actual animation depends on the movement of Rigidbody. It provides an inputs that allows the pedestrian to move - change his position and orientation. In addition, the ReferencePoint point is used to ensure that the pedestrian follows the ground plane correctly.

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"
    • Ray Cast Max Distance - ray-cast max distance for locating the ground.
    • Ray Cast Origin Offset - upward offset of the ray-cast origin from the GameObject local origin for locating the ground.
    "},{"location":"Components/Traffic/NPCs/Pedestrian/#input-data","title":"Input Data","text":"Category Type Description SetPosition Vector3 Move the NPCPedestrian so that the reference point is at the specified coordinates. SetRotation Vector3 Rotate the NPCPedestrian so that the orientation of the reference point becomes the specified one."},{"location":"Components/Traffic/NPCs/Pedestrian/#simple-pedestrian-walker-controller-script","title":"Simple Pedestrian Walker Controller (script)","text":"

    Simple Pedestrian Walker Controller is a script that allows the pedestrian to cyclically move back and forth along a straight line. One-way motion is performed with a fixed time as parameter Duration and a constant linear velocity as parameter Speed. The script obviously uses the NPCPedestrian controls provided by the NPC Pedestrian (script) inputs.

    Pedestrian walking on the sidewalk

    "},{"location":"Components/Traffic/NPCs/Pedestrian/#collider","title":"Collider","text":"

    Collider is an optional pedestrian component. By default, NPCPedestrian doesn't have this component added, It can be added if you want to detect a collision, e.g. with an EgoVehicle. There are several types of colliders, choose the right one and configure it for your own requirements.

    Capsule Collider

    An example of a CapsuleCollider that covers almost the entire pedestrian.

    "},{"location":"Components/Traffic/NPCs/RvizNPCSpawner/","title":"Spawn NPCs from RVIZ","text":""},{"location":"Components/Traffic/NPCs/RvizNPCSpawner/#introduction","title":"Introduction","text":"

    This feature allows you to spawn NPCs (pedestrians, cars, buses) in the Unity scene (AWSIM) from Autoware (RVIZ). It includes bulk deletion, vehicle velocity specification, and ensures NPC vehicles move straight, only colliding with the ground.

    "},{"location":"Components/Traffic/NPCs/RvizNPCSpawner/#setup","title":"Setup","text":"

    You can change the configuration of the NPCs in the RVIZNPCSpawner component in AWSIM. It is attached to the Environment game object in the AutowareSimulation scene. You can also attach the RVIZNPCSpawner to any other game object and set all the required values in your custom scene.

    1. Attach the RVIZNPCSpawner component to one of the game objects in the scene. By default, it's attached to Environment.

    2. In AWSIM, you can add more cars (smaller vehicles) or buses (large vehicles) in the Npc Car prefabs / Npc Bus prefabs lists respectively.

    3. Then, select the parent objects under which the Pedestrians or Vehicles will be spawned.

    4. Finally, adjust the Despawn time to destroy the NPCs after a delay.

    "},{"location":"Components/Traffic/NPCs/RvizNPCSpawner/#spawning-npcs-from-autoware","title":"Spawning NPCs from Autoware","text":"

    1. Open up Autoware.

    2. Click the 2D Dummy Car,2D Dummy Bus or 2D Dummy Pedestrian button in the toolbar.

    1. Set the pose of the dummy object by clicking and dragging on the map.

    1. Set the velocity of the object in Tool Properties -> 2D Dummy Car/Pedestrian panel.

    1. NPCs will not be spawned if the you try to place them outside the map.
    "},{"location":"Components/Traffic/NPCs/Vehicle/","title":"Vehicle","text":""},{"location":"Components/Traffic/NPCs/Vehicle/#npcvehicle","title":"NPCVehicle","text":""},{"location":"Components/Traffic/NPCs/Vehicle/#introduction","title":"Introduction","text":"

    NPCVehicle is a non-playable object that simulates a vehicle that is stationary or moving around the scene. It can move on roads, more specifically TrafficLanes, thanks to the use of TrafficSimulator - which you can read more about here. Vehicles moving on the scene take into account each other - avoiding collisions, follow traffic lights and have an implemented mechanism of yielding the right of way.

    Sample scene

    If you would like to see how NPCVehicle works or run some tests, we encourage you to familiarize yourself with the NPCVehicleSample default scene described in this section.

    Ego Vehicle

    If you are interested in the most important vehicle on the scene - Ego Vehicle, we encourage you to read this section.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#prefabs-and-fbxs","title":"Prefabs and Fbxs","text":"

    Prefabs can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Vehicles/*\n

    The table shows the available prefabs of the vehicles:

    Hatchback SmallCar Taxi Truck Van Appearance Prefab Hatchback.prefab SmallCar.prefab Taxi-64.prefab Truck_2t.prefab Van.prefab

    NPCVehicle prefab has the following content:

    As you can see, it consists of 2 parents for GameObjects: Visuals - aggregating visual elements, Colliders - aggregating colliders and single object CoM. All objects are described in the sections below.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#visual-elements","title":"Visual elements","text":"

    Prefabs are developed using models available in the form of *.fbx files. For each vehicle, the visuals elements and LOD were loaded from the appropriate *.fbx file. The LOD is always added as components of the main-parent GameObject in prefab, while the visual elements of the model are aggregated and added in object Visuals.

    *.fbx file for each vehicle is located in the appropriate Models directory for the vehicle under the following path:

    Assets/AWSIM/Models/NPCs/Vehicles/<vehicle_name>/Models/<vehicle_name>.fbx\n

    As you can see, the additional visual element is Driver.

    It was also loaded from the *.fbx file which can be found under the following path:

    Assets/AWSIM/Models/NPCs/Vehicles/Driver/Model/Driver.fbx\n

    Vehicle fbx

    The content of a sample *.fbx file is presented below, all elements except Collider have been added to the prefab as visual elements of the vehicle. Collider is used as the Mesh source for the Mesh Collider in the BodyCollider object.

    .

    "},{"location":"Components/Traffic/NPCs/Vehicle/#link","title":"Link","text":"

    The default scene does not have vehicles implemented in fixed places, but they are spawned by RandomTrafficSimulator which is located in the Environment prefab. Therefore, before starting the simulation, no NPCVehicle object is on the scene.

    When you run the simulation, you can see objects appearing as children of RandomTrafficSimulator:

    In each NPCVehicle prefab, the local coordinate system of the vehicle (main prefab link) should be defined in the axis of the rear wheels projected onto the ground - in the middle of the distance between them. This aspect holds significance when characterizing the dynamics of the object, as it provides convenience in terms of describing its motion and control.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#components","title":"Components","text":"

    There are several components responsible for the full functionality of NPCVehicle:

    • LOD Group - provides level of detail configuration for shaders - affects GPU usage.
    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • NPC Vehicle (script) - provides the ability to change the position and orientation of the vehicle, as well as to control the turn signals and brake light.

    Script can be found under the following path:

    Assets/AWSIM/Scripts/NPCs/Vehicles\n
    "},{"location":"Components/Traffic/NPCs/Vehicle/#com","title":"CoM","text":"

    CoM (Center of Mass) is an additional link that is defined to set the center of mass in the Rigidbody. The NPC Vehicle (script) is responsible for its assignment. This measure should be defined in accordance with reality. Most often, the center of mass of the vehicle is located in its center, at the height of its wheel axis - as shown below.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#colliders","title":"Colliders","text":"

    Colliders are used to ensure collision between objects. In NPCVehicle, the main BodyCollider collider and Wheels Colliders colliders for each wheel were added.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#body-collider","title":"Body Collider","text":"

    BodyCollider is a vehicle Object responsible for ensuring collision with other objects. Additionally it can be used to detect these collisions. The MeshCollider uses a Mesh of an Object to build its Collider. The Mesh for the BodyCollider was also loaded from the *.fbx file similarly to the visual elements.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#wheels-colliders","title":"Wheels Colliders","text":"

    WheelsColliders are an essential element from the point of view of driving vehicles on the road. They are the only ones that have contact with the roads and it is important that they are properly configured. Each vehicle, apart from the visual elements related to the wheels, should also have 4 colliders - one for each wheel.

    To prevent inspector entry for WheelCollider the WheelColliderConfig has been developed. It ensures that friction is set to 0 and only wheel suspension and collisions are enabled.

    Wheel Collider Config

    For a better understanding of the meaning of WheelCollider we encourage you to read this manual.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#lod","title":"LOD","text":"

    LOD provides dependence of the level of detail of the object depending on the ratio of the GameObject\u2019s screen space height to the total screen height. Vehicle models have only one LOD0 group, therefore there is no reduction in model complexity when it does not occupy a large part of the screen. It is only culled when it occupies less than 2% of the height.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. The Mass of the vehicle should approximate its actual weight. In order for the vehicle to physically interact with other objects - react to collisions, Is Kinematic must be turned off. The Use Gravity should be turned on - to ensure the correct behavior of the body during movement. In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#npc-vehicle-script","title":"NPC Vehicle (script)","text":"

    The script takes the Rigidbody and provides an inputs that allows the NPCVehicle to move. Script inputs give the ability to set the position and orientation of the vehicle, taking into account the effects of suspension and gravity. In addition, the script uses the CoM link reference to assign the center of mass of the vehicle to the Rigidbody.

    Script inputs are used by RandomTrafficSimulator, which controls the vehicles on the scene - it is described here.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#input-data","title":"Input Data","text":"Category Type Description SetPosition Vector3 Move the NPCVehicle so that its x, z coordinates are same as the specified coordinates. Pitch and roll are determined by physical operations that take effects of suspension and gravity into account. SetRotation Vector3 Rotate the NPCVehicle so that its yaw becomes equal to the specified one. Vertical movement is determined by physical operations that take effects of suspension and gravity into account.

    Visual Object Root is a reference to the parent aggregating visuals, it can be used to disable the appearance of visual elements of the NPCVehicle in the scene.

    Whereas Bounds Represents an axis aligned bounding box of the NPCVehicle. It is used primarily to detect collisions between vehicles in the event of spawning, yielding and others. Moreover, vehicle bounds are displayed by Gizmos.

    The settings of the remaining elements, i.e. the Axle and the Lights, are described here and here.

    No Gizmo visualization

    If you don't see Gizmo's visual elements, remember to turn them on.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#axle-settings","title":"Axle Settings","text":"

    This part of the settings is responsible for the proper connection of visual elements with the collider for each wheel - described earlier. The objects configured in this section are used to control the vehicle - its wheel speed and steering angle, which are calculated based on the input values. Correct configuration is very important from the point of view of the NPCVehicle movement on the road.

    "},{"location":"Components/Traffic/NPCs/Vehicle/#lights-settings","title":"Lights Settings","text":"

    This part of the settings is related to the configuration of materials emission - used when a specific lighting is activated. There are 3 types of lights: Brake, Left Turn Signal and Right Turn Signal. Each of the lights has its visual equivalent in the form of a Mesh. In the case of NPCVehicle all of the lights are included in the Body object Mesh, which has many materials - including those related to lights.

    For each type of light, the appropriate Material Index (equivalent of element index in mesh) and Lighting Color are assigned - yellow for Turn Signals, red for Break.

    Lighting Intensity values are also configured - the greater the value, the more light will be emitted. This value is related to Lighting Exposure Weight parameter that is an exposure weight - the lower the value, the more light is emitted.

    The brake light is switched on depending on the speed of the NPCVehicle, while RandomTrafficSimulator is responsible for switching the turn signals on and off.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/","title":"Add Random Traffic Environment","text":""},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#add-environment-for-random-traffic","title":"Add Environment for Random Traffic","text":"

    This document describes the steps to properly configuer RandomTrafficSimulator in your environment.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#map-preparation","title":"Map preparation","text":"

    The 3D map model should be added to the scene. Please make sure that the Environment component with appropriate mgrsOffsetPosition is attached to the root GameObject.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-traffic-lights","title":"Annotate Traffic Lights","text":"

    Please attach TrafficLight component to all traffic light GameObjects placed on scene.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#load-lanelet","title":"Load Lanelet","text":"

    The lanelet load process can be performed by opening AWSIM -> Random Traffic -> Load Lanelet at the top toolbar of Unity Editor.

    You should be prompted with a similar window to the one presented below. Please adjust the parameters for the loading process if needed.

    Waypoint settings affect the density and accuracy of the generated waypoints. The parameters are described below:

    • Resolution: resolution of resampling. Lower values provide better accuracy at the cost of processing time.
    • Min Delta Length: minimum length(m) between adjacent points.
    • Min Delta Angle: minimum angle(deg) between adjacent edges. Lowering this value produces a smoother curve.

    To generate the Lanelet2 map representation in your simulation, please click the Load button. Environment components should be generated and placed as child objects of the Environment GameObject. You can check their visual representation by clicking consecutive elements in the scene hierarchy.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-traffic-intersections","title":"Annotate Traffic Intersections","text":"

    To annotate intersection please, add an empty GameObject named TrafficIntersections at the same level as the TrafficLanes GameObject.

    For each intersection repeat the following steps:

    1. Add an GameObject named TrafficIntersection as a child object of the TrafficIntersections object.
    2. Attach a TrafficIntersection component to it.
    3. Add a BoxCollider as a component of GameObject. It's size and position should cover the whole intersection. This is used for detecting vehicles in the intersection.
    4. Set TrafficLightGroups. Each group is controlled to have different signals, so facing traffic lights should be added to the same group. These groupings are used in traffic signal control.
    5. Specify the signal control pattern.
    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-right-of-ways-on-uncontrolled-intersections","title":"Annotate right of ways on uncontrolled intersections","text":"

    For the vehicles to operate properly it is needed to annotate the right of way of TrafficLane manually on intersections without traffic lights.

    To set the right of way, please:

    • Select a straight lane that is not right of way in the intersection. The selected lane should be highlighted as presented below.
    • Click the Set RightOfWays button to give the lane priority over other lanes.
    • Please check if all lanes that intersect with the selected lane are highlighted yellow. This means that the right of way was applied correctly.
    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#annotate-stop-lines","title":"Annotate stop lines","text":"

    For each right turn lane that yields to the opposite straight or left turn lane, a stop line needs to be defined near the center of the intersection. If there is no visible stop line, a StopLine component should be added to the scene, near the center of the intersection and associated with TrafficLane.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#assign-intersection-trafficlanes","title":"Assign Intersection TrafficLanes","text":"

    To make the yielding rules work properly, it is necessary to catagorize the TrafficLanes. The ones that belong to an intersection have the IntersectionLane variable set to true.

    To automate the assignment of the corresponding IntersectionLane to each TrafficLane, the script AssignIntersectionTrafficLanes can be used.

    1. At the time of assignment, add it as a component to some object in the scene (e.g. to the Environment object).
    2. Disable the component (uncheck the checkbox next to the script name).
    3. Assign to TrafficLanesObjectsParent GameObject, which contains all TrafficLanes objects.
    4. Check all 4 options.
    5. Enable the component (check the checkbox next to the script name).

    Check the log to see if all operations were completed:

    As a result, the names of TrafficLane objects should have prefixes with sequential numbers and TrafficLane at intersections should be marked. TrafficLanes with IntersectionLane set to True are displayed by Gizmos in green color, if IntersectionLane is False their color is white.

    "},{"location":"Components/Traffic/RandomTraffic/AddRandomTrafficEnvironment/#check-final-configuration","title":"Check final configuration","text":"

    Once all the components are ready, the simulation can be run. Check carefully if the vehicles are moving around the map correctly. For each intersection, review the settings of the relevant components if vehicles are unable to proceed.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/","title":"Random Traffic Simulator","text":""},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#random-traffic-simulator","title":"Random Traffic Simulator","text":"

    The RandomTrafficSimulator simulates city traffic with respect to all traffic rules. The system allows for random selection of car models and the paths they follow. It also allows adding static vehicles in the simulation.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#getting-started","title":"Getting Started","text":""},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#overview","title":"Overview","text":"

    The random traffic system consists of the following components:

    • RandomTrafficSimulator: manages lifecycle of NPCs and simulates NPC behaviours.
    • TrafficLane, TrafficIntersection and StopLine: represent traffic entities
    • NPCVehicle: vehicle models (NPCs) controlled by RandomTrafficSimulator

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#components-settings","title":"Components Settings","text":"

    The following section describes Unity Editor components settings.

    "},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#random-traffic-simulator_1","title":"Random Traffic Simulator","text":"Parameter Description General Settings Seed Seed value for random generator Ego Vehicle Transform of ego vehicle Vehicle Layer Mask LayerMask that masks only vehicle(NPC and ego) colliders Ground Layer Mask LayerMask that masks only ground colliders of the map NPC Vehicle Settings Max Vehicle Count Maximum number of NPC vehicles to be spawned in simulation NPC Prefabs Prefabs representing controlled vehicles. They must have NPCVehicle component attached. Spawnable Lanes TrafficLane components where NPC vehicles can be spawned during traffic simulation Vehicle Config Parameters for NPC vehicle controlSudden Deceleration is a deceleration related to emergency braking Debug Show Gizmos Enable the checkbox to show editor gizmos that visualize behaviours of NPCs"},{"location":"Components/Traffic/RandomTraffic/RandomTrafficSimulator/#gizmos","title":"Gizmos","text":"

    Gizmos are useful for checking current behavior of NPCs and its causes. Gizmos have a high computational load so please disable them if the simulation is laggy.

    "},{"location":"Components/Traffic/RandomTraffic/YieldingRules/","title":"Yielding Rules","text":""},{"location":"Components/Traffic/RandomTraffic/YieldingRules/#yielding-rules","title":"Yielding rules","text":"

    The RandomTrafficSimulator assumes that there are 10 phases of yielding priority:

    RandomTrafficYielding scene

    If you would like to see how RandomTrafficSimulator with yielding rules works or run some tests, we encourage you to familiarize yourself with the RandomTrafficYielding scene described in this section.

    1. NONE - state in which it is only checked if a vehicle is approaching the intersection. If yes, a transition to state ENTERING_INTERSECTION is made.

    2. ENTERING_INTERSECTION - state in which it is checked if any of the situations LANES_RULES_ENTERING_INTERSECTION, LEFT_HAND_RULE_ENTERING_INTERSECTION, INTERSECTION_BLOCKED occur, if yes the state of the vehicle is changed to one matching the situation - to determine if the vehicle must yield priority. If none of these situations occur only the entry into the intersection will result in a transition to AT_INTERSECTION.

    3. AT_INTERSECTION - state in which it is checked if any of the situations LANES_RULES_AT_INTERSECTION, LEFT_HAND_RULE_AT_INTERSECTION, FORCING_PRIORITY occur, if yes the state of the vehicle is changed to one matching the situation - to determine if the vehicle must yield priority. If none of these situations occur only leaving the intersection will result in a transition to NONE.

    4. INTERSECTION_BLOCKED - when vehicle A is approaching the intersection, it yields priority to vehicle B, which should yield priority, but is forcing it - this refers to a situation in which vehicle B has entered the intersection and has already passed its stop point vehicle B isn\u2019t going to stop but has to leave the intersection. Until now, vehicle A has continued to pass through the intersection without taking vehicle B into account, now it is checking if any vehicle is forcing priority (vehicle A has INTERSECTION_BLOCKED state). (vehicle A is red car with blue sphere, B is the white car to which it points)

    5. LEFT_HAND_RULE_ENTERING_INTERSECTION - vehicle A, before entering the intersection where the traffic lights are off, yields priority to vehicles (ex. B) that are approaching to the intersection and are on the left side of vehicle A. Until now, situations in which the lights are off were not handled. If a vehicle didn't have a red light and was going straight - it just entered the intersection. Now vehicle A checks if the vehicles on the left (ex. B) have a red light, if not it yields them priority. (vehicle A is truck car with gray sphere, B is the white car to which it points)

    6. LEFT_HAND_RULE_AT_INTERSECTION - when vehicle A is already at the intersection, yields priority to vehicles (ex. B) that are also at the intersection and are on its left side - in cases where no other yielding rules are resolved between them (i.e. there are no RightOfWayLanes between them). (vehicle A is red, B is white)

    7. LANES_RULES_ENTERING_INTERSECTION - when vehicle B intends to turn left and is approaching at the intersection where it needs to yield to vehicle A which is going straight ahead, then it goes to state LANES_RULES_ENTERING_INTERSECTION. The introduced changes take into account that a vehicle approaching the intersection considers not only the vehicles at the intersection but also those which are approaching it (at a distance of less than minimumDistanceToIntersection to the intersection). (vehicle B is truck with yellow sphere, A the white car to which it points)

    8. LANES_RULES_AT_INTERSECTION - when vehicle B intends to turn right and is already at the intersection where it needs to yield to vehicle A which is approaching the intersection, then it goes to state LANES_RULES_AT_INTERSECTION. The introduced changes take into account that a vehicle approaching the intersection considers not only the vehicles at the intersection but also those which are approaching it (at a distance of less than minimumDistanceToIntersection to the intersection). (vehicle B is car with red sphere, A the white car to which it points)

    9. FORCING_PRIORITY - state in which some vehicle B should yield priority to a vehicle A but doesn't - for some reason, most likely it could be some unusual situation in which all other rules have failed. Then vehicle A which is at intersection yields priority to a vehicle that is forcing priority. In such a situation, vehicle A transitions to state FORCING_PRIORITY. It is very rare to achieve this state, but it does happen.

    "},{"location":"Components/Traffic/RandomTraffic/YieldingRules/#gizmos-markings","title":"Gizmos Markings","text":"
    • No sphere means the vehicle is in one of the following states - NONE, ENTERING_INTERSECTION or AT_INTERSECTION.
    • The gray sphere means that the vehicle is approaching the intersection and yields priority to the vehicle on the left side - LEFT_HAND_RULE_ENTERING_INTERSECTION.
    • The black sphere means that the vehicle is at the intersection and yields priority to a vehicle on the left side - LEFT_HAND_RULE_AT_INTERSECTION.
    • The yellow sphere means that the vehicle yields due to lanes rules before entering the intersection - LANES_RULES_ENTERING_INTERSECTION.
    • The red sphere means that it yields due to lanes rules but is already at the intersection - LANES_RULES_AT_INTERSECTION.
    • The blue sphere means that a vehicle is approaching the intersection and yields priority to a vehicle that is forcing priority - INTERSECTION_BLOCKED - when the turning vehicle begins to yield, then the blue sphere disappears. However, if the turning vehicle continues to turn (does not yield because it has passed the stopping point), then the vehicle going straight stops before the intersection and allows the turning vehicle to leave the intersection.
    • The pink sphere means that a vehicle is at intersection and yields priority to a vehicle that is forcing priority - FORCING_PRIORITY.
    "},{"location":"Components/Traffic/TrafficComponents/","title":"Traffic Components","text":"

    This section

    This section is still under development!

    This is a section that describes in detail all components related to simulated traffic in the Environment prefab.

    "},{"location":"Components/Traffic/TrafficComponents/#architecture","title":"Architecture","text":"

    The random traffic system consists of the following components:

    • TrafficManager

      It is a top level interface meant to be used on the Unity scene. TrafficManager runs all elements needed for a successful traffic simulation. This component manages all TrafficSimulators so they don't work against each other. It gives you the possibility to configure the TrafficSimulators.

    • TrafficSimulator

      Technically it is not a component, it is crucial to understand what it is and what it does in order to correctly configure the TrafficManager. TrafficSimulator manages NPCVehicles spawning. There can be many TrafficSimulators on the scene. They are added and configured in the TrafficManager component. Every TrafficSimulator manages some part of the traffic it is responsible for - meaning it has spawned the NPCVehicles and set their configuration.

      • RandomTrafficSimulator - spawns and controls NPCVehicles driving randomly
      • RouteTrafficSimulator - spawns and controls NPCVehicles driving on a defined route

      TrafficSimulator inaccessibility

      It is not possible to get direct access to the TrafficSimulator. It should be added and configured through the TrafficManager component.

    • TrafficLane, TrafficIntersection and StopLine

      These components represent traffic entities. They are used to control and manage the traffic with respect to traffic rules and current road situation.

    • NPCVehicle

      The vehicle models (NPCs) spawned by one of the TrafficSimulators. They are spawned according to the TrafficSimulator configuration and either drive around the map randomly (when spawned by a RandomTrafficSimulator) or follow the predefined path (when spawned by a RouteTrafficSimulator). NPCVehicles are managed by one central knowledge base.

    The process of spawning a NPCVehicle and its later behavior control is presented on the following sequence diagram.

    Sequence Diagram Composition

    Please note that the diagram composition has been simplified to the level of GameObjects and chosen elements of the GameObjects for the purpose of improving readability.

    "},{"location":"Components/Traffic/TrafficComponents/#lanelet2","title":"Lanelet2","text":"

    Lanelet2 is a library created for handling a map focused on automated driving. It also supports ROS and ROS2 natively. In AWSIM Lanelet2 is used for reading and handling a map of all roads. Specifically it does contain all TrafficLanes and StopLines. You may also see us referring to the actual map data file (*.osm) as a Lanelet2.

    Lanelet2 official page

    If you want to learn more we encourage to visit the official project page.

    "},{"location":"Components/Traffic/TrafficComponents/#randomtrafficsimulator","title":"RandomTrafficSimulator","text":"

    Nomenclature

    Please note that

    • a GameObject
    • an element spawning NPCVehicles randomly and
    • the whole system of traffic control

    are named RandomTrafficSimulator. Keep this in mind when reading the following page - so you don't get confused.

    RandomTrafficSimulator simulates traffic with respect to all traffic rules. The system allows for random selection of car models and the paths they follow. It also allows adding static vehicles in the simulation.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The RandomTrafficSimulator consists of several GameObjects.

    • RandomTrafficSimulator - this is an Object consisting of a Traffic Manager (script). You can learn more about it here.
    • TrafficIntersections - this is a parent Object for all TrafficIntersections. You can learn more about it here.
    • TrafficLanes - this is a parent Object for all TrafficLanes. You can learn more about it here.
    • StopLines - this is a parent Object for all StopLines. You can learn more about it here.
    "},{"location":"Components/Traffic/TrafficComponents/#components","title":"Components","text":"

    RandomTrafficSimulator only has one component: Traffic Manager (script) which is described below.

    "},{"location":"Components/Traffic/TrafficComponents/#trafficmanager-script","title":"TrafficManager (script)","text":"

    Traffic Manager (script) is responsible for all of top level management of the NPCVehicles. It managed spawning of NPCVehicles on TrafficLanes.

    TrafficManager uses the concept of TrafficSimulators. One TrafficSimulator is responsible for managing its set of NPCVehicles. Every TrafficSimulator spawns its own NPCVehicles independently. The vehicles spawned by one TrafficSimulator do respect its configuration. TrafficSimulators can be interpreted as NPCVehicle spawners with different configurations each. Many different TrafficSimulators can be added to the TrafficManager.

    If a random mode is selected (RandomTrafficSimulator) then NPCVehicles will spawn in random places (from the selected list) and drive in random directions. To be able to reproduce the behavior of the RandomTrafficSimulator a Seed can be specified - which is used for the pseudo-random numbers generation.

    TrafficManager script also configures all of the spawned NPCVehicles, so that they all have common parameters

    • Acceleration - the acceleration used by the vehicles at all times when accelerating.
    • Deceleration - the value of deceleration used in ordinary situations.
    • Sudden Deceleration - deceleration used when standard Deceleration is not sufficient to avoid accident.
    • Absolute Deceleration - value of deceleration used when no other deceleration allows to avoid the accident.

    The Vehicle Layer Mask and Ground Layer Mask are used to make sure all vehicles can correctly interact with the ground to guarantee simulation accuracy.

    Max Vehicle Count specifies how many NPCVehicles can be present on the scene at once. When the number of NPCVehicles on the scene is equal to this value the RandomTrafficSimulator stops spawning new vehicles until some existing vehicles drive away and disappear.

    The EgoVehicle field provides the information about Ego vehicle used for correct behavior ofNPCVehicleswhen interacting with Ego.

    Show Gizmos checkbox specifies whether the Gizmos visualization should be displayed when running the simulation.

    Show Yielding Phase checkbox specifies whether yielding phases should be displayed by Gizmos - in the form of spheres above vehicles, details in the Markings section.

    Show Obstacle Checking checkbox specifies whether obstacle checking should be displayed by Gizmos - in the form of boxes in front of vehicles

    Show Spawn Points checkbox specifies whether spawn points should be displayed by Gizmos - in the form of flat cuboids on roads.

    Gizmos performance

    Gizmos have a high computational load. Enabling them may cause the simulation to lag.

    As mentioned earlier - TrafficManager may contain multiple TrafficSimulators. The two available variants of TrafficSimulator are described below

    • RandomTrafficSimulator
    • RouteTrafficSimulator

    TrafficSimulators should be interpreted as spawning configurations for some group of NPCVehicles on the scene.

    "},{"location":"Components/Traffic/TrafficComponents/#random-traffic","title":"Random Traffic","text":"

    When using RandomTrafficSimulator the NPCVehicle prefabs (NPC Prefabs) can be chosen as well as Spawnable Lanes. The later are the only TrafficLanes on which the NPCVehicles can spawn. Upon spawning one of the Spawnabe Lanes is chosen and - given the vehicle limits are not reached - one random NPCVehicle from the Npc prefabs list is spawned on that lane. After spawning, the NPCVehicle takes a random route until it drives out of the map - then it is destroyed.

    The Maximum Spawns field specifies how many Vehicles should be spawned before this TrafficSimulator stops working. Set to 0 to disable this restriction.

    "},{"location":"Components/Traffic/TrafficComponents/#route-traffic","title":"Route Traffic","text":"

    When using Route traffic Simulator the NPCVehicle prefabs (NPC Prefabs) as well as Route can be chosen. The later is an ordered list of TrafficLanes that all spawned vehicles will drive on. Given the vehicle limit is not reached - the RouteTrafficSimulator will spawn one of the Npc Prefabs chosen randomly on the first Route element (Element 0). After the first vehicle drives off the next one will spawn according to the configuration. It is important for all Route elements to be connected and to be arranged in order of appearance on the map. The NPCVehicle disappears after completing the Route.

    The Maximum Spawns field specifies how many Vehicles should be spawned before this TrafficSimulator stops working. Set to 0 to disable this restriction.

    "},{"location":"Components/Traffic/TrafficComponents/#parameter-explanation","title":"Parameter explanation","text":"Parameter Description General Settings Seed Seed value for random generator Ego Vehicle Transform of ego vehicle Vehicle Layer Mask LayerMask that masks only vehicle(NPC and ego) colliders Ground Layer Mask LayerMask that masks only ground colliders of the map Culling Distance Distance at which NPCs are culled relative to EgoVehicle Culling Hz Culling operation cycle NPCVehicle Settings Max Vehicle Count Maximum number of NPC vehicles to be spawned in simulation NPC Prefabs Prefabs representing controlled vehicles. They must have NPCVehicle component attached. Spawnable Lanes TrafficLane components where NPC vehicles can be spawned during traffic simulation Vehicle Config Parameters for NPC vehicle controlSudden Deceleration is a deceleration related to emergency braking Debug Show Gizmos Enable the checkbox to show editor gizmos that visualize behaviours of NPCs"},{"location":"Components/Traffic/TrafficComponents/#traffic-light-script","title":"Traffic Light (script)","text":"

    Traffic Light (script) is a component added to every TrafficLight on the scene. It is responsible for configuring the TrafficLight behavior - the bulbs and their colors.

    The Renderer filed points to the renderer that should be configured - in this case it is always a TrafficLight renderer.

    Bulbs Emission Config is a list describing available colors for this Traffic Light. Every element of this list configures the following

    • Bulb Color - the name of the configured color that will be used to reference this color
    • Color - the actual color with which a bulb should light up
    • Intensity - the intensity of the color
    • Exposure Weight - how bright should the color be when lighting up

    The Bulb Material Config is a list of available bulbs in a given Traffic Light. Every element describes a different bulb. Every bulb has the following aspects configured

    • Bulb Type - the name that will be usd to reference the configured bulb
    • Material Index - The index of a material of the configured bulb. This is an index of a sub-mesh of the configured bulb in the Traffic Light mesh. The material indices are described in detail here and here.
    "},{"location":"Components/Traffic/TrafficComponents/#trafficintersections","title":"TrafficIntersections","text":"

    TrafficIntersection is a representation of a road intersection. It consists of several components. TrafficIntersection is used in the Scene for managing TrafficLights. All Traffic Lights present on one Traffic Intersection must be synchronized - this is why the logic of TrafficLight operation is included in the TrafficIntersection.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_1","title":"Link in the default Scene","text":"

    Every TrafficIntersection has its own GameObject and is added as a child of the aggregate TrafficIntersections Object. TrafficIntersections are elements of an Environment, so they should be placed as children of an appropriate Environment Object.

    "},{"location":"Components/Traffic/TrafficComponents/#components_1","title":"Components","text":"

    TrafficIntersection has the following components:

    • Box Collider - marks the area of the Traffic Intersection, it should cover the whole intersection area
    • Traffic Intersection (script) - controls all Traffic Lights on the given intersection according to the configuration
    "},{"location":"Components/Traffic/TrafficComponents/#collider","title":"Collider","text":"

    Every TrafficIntersection contains a Box Collider element. It needs to accurately cover the whole area of the TrafficIntersection. Box Collider - together with the Traffic Intersection (script) - is used for detecting vehicles entering the TrafficIntersection.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-intersection-script","title":"Traffic Intersection (script)","text":"

    Traffic Intersection (script) is used for controlling all TrafficLights on a given intersection. The Collider Mask field is a mask on which all Vehicle Colliders are present. It - together with Box Collider - is used for keeping track of how many Vehicles are currently present on the Traffic Intersection. The Traffic Light Groups and Lighting Sequences are described below.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-light-groups","title":"Traffic Light Groups","text":"

    Traffic Light Group is a collection of all Traffic Lights that are in the same state at all times. This includes all redundant Traffic Lights shining in one direction as well as the ones in the opposite direction. In other words - as long as two Traffic Lights indicate exactly the same thing they should be added to the same Traffic Light Group. This grouping simplifies the creation of Lighting Sequences.

    "},{"location":"Components/Traffic/TrafficComponents/#lighting-sequences","title":"Lighting Sequences","text":"

    Lighting Sequences is the field in which the whole intersection Traffic Lights logic is defined. It consists of many different Elements. Each Element is a collection of Orders that should take an effect for the period of time specified in the Interval Sec field. Lighting Sequences Elements are executed sequentially, in order of definition and looped - after the last element sequence goes back to the first element.

    The Group Lighting Orders field defines which Traffic Light Groups should change their state and how. For every Group Lighting Orders Element the Traffic Lights Group is specified with the exact description of the goal state for all Traffic Lights in that group - which bulb should light up and with what color.

    One Lighting Sequences Element has many Group Lighting Orders, which means that for one period of time many different orders can be given. E.g. when Traffic Lights in one direction change color to green - Traffic Lights in the parallel direction change color to red.

    Traffic Light state persistance

    If in the given Lighting Sequences Element no order is given to some Traffic Light Group - this Group will keep its current state. When the next Lighting Sequences Element activates - the given Traffic Light Group will remain in an unchanged state.

    Lighting Sequence Sample - details

    Description Editor Traffic Lights in Pedestrian Group 1change color to flashing green. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Pedestrian Group 1change color to solid red. Other Groups keep theircurrent state. This state lasts for 1 second. Traffic Lights in Vehicle Group 1change color to solid yellow. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Vehicle Group 1change color to solid red. Other Groups keep theircurrent state. This state lasts for 3 seconds. Traffic Lights in Vehicle Group 2change color to solid green. Traffic Lights in Pedestrian Group 2change color to solid green. Other Groups keep theircurrent state. This state lasts for 15 seconds. Traffic Lights in Pedestrian Group 2change color to flashing green. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Pedestrian Group 2change color to solid red. Other Groups keep theircurrent state. This state lasts for 1 second. Traffic Lights in Vehicle Group 2change color to solid yellow. Other Groups keep theircurrent state. This state lasts for 5 seconds. Traffic Lights in Vehicle Group 2change color to solid red. Other Groups keep theircurrent state. This state lasts for 3 second. Sequence loops back to thefirst element of the list."},{"location":"Components/Traffic/TrafficComponents/#trafficlanes","title":"TrafficLanes","text":"

    TrafficLane is a representation of a short road segment. It consists of several waypoints that are connected by straight lines. TrafficLanes are used as a base for a RandomTrafficSimulator. They allow NPCVehicles to drive on the specific lanes on the road and perform different maneuvers with respect to the traffic rules. TrafficLanes create a network of drivable roads when connected.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_2","title":"Link in the default Scene","text":"

    Every TrafficLane has its own GameObject and is added as a child of the aggregate TrafficLanes Object. TrafficLanes are an element of an Environment, so they should be placed as children of an appropriate Environment Object.

    TrafficLanes can be imported from the lanelet2 *.osm file.

    "},{"location":"Components/Traffic/TrafficComponents/#components_2","title":"Components","text":"

    TrafficLane consists of an Object containing Traffic Lane (script).

    TrafficLane has a transformation property - as every Object in Unity - however it is not used in any way. All details are configured in the Traffic Lane (script), the information in Object transformation is ignored.

    "},{"location":"Components/Traffic/TrafficComponents/#traffic-lane-script","title":"Traffic Lane (script)","text":"

    Traffic Lane (script) defines the TrafficLane structure. The Waypoints field is an ordered list of points that - when connected with straight lines - create a TrafficLane.

    Traffic Lane (script) coordinate system

    Waypoints are defined in the Environment coordinate system, the transformation of GameObject is ignored.

    Turn Direction field contains information on what is the direction of this TrafficLane - whether it is a right or left turn or straight road.

    Traffic lanes are connected using Next Lanes and Prev Lanes fields. This way individual TrafficLanes can create a connected road network. One Traffic Lane can have many Next Lanes and Prev Lanes. This represents the situation of multiple lanes connecting to one or one lane splitting into many - e.g. the possibility to turn and to drive straight.

    Right Of Way Lanes are described below.

    Every TrafficLane has to have a Stop Line field configured when the Stop Line is present on the end of the TrafficLane. Additionally the Speed Limit field contains the highest allowed speed on given TrafficLane.

    "},{"location":"Components/Traffic/TrafficComponents/#right-of-way-lanes","title":"Right Of Way Lanes","text":"

    Right Of Way Lanes is a collection of TrafficLanes. Vehicle moving on the given TrafficLane has to give way to all vehicles moving on every Right Of Way Lane. It is determined based on basic traffic rules. Setting Right Of Way Lanes allows RandomTrafficSimulator to manage all NPCVehicles so they follow traffic rules and drive safely.

    In the Unity editor - when a TrafficLane is selected - aside from the selected TrafficLane highlighted in blue, all Right Of Way Lanes are highlighted in yellow.

    Right Of Way Lanes Sample - details

    The selected TrafficLane (blue) is a right turn on an intersection. This means, that before turning right the vehicle must give way to all vehicles driving from ahead - the ones driving straight as well as the ones turning left. This can be observed as TrafficLanes highlighted in yellow.

    "},{"location":"Components/Traffic/TrafficComponents/#stoplines","title":"StopLines","text":"

    StopLine is a representation of a place on the road where vehicles giving way to other vehicles should stop and wait. They allow RandomTrafficSimulator to manage NPCVehicles in safe and correct way - according to the traffic rules. All possible locations where a vehicle can stop in order to give way to other vehicles - that are enforced by an infrastructure, this does not include regular lane changing - need to be marked with StopLines.

    "},{"location":"Components/Traffic/TrafficComponents/#link-in-the-default-scene_3","title":"Link in the default Scene","text":"

    Every StopLine has its own GameObject and is added as a child of the aggregate StopLines Object. Stop Lines are an element of an Environment, so they should be placed as children of an appropriate Environment Object.

    StopLines can be imported from the lanelet2 *.osm file.

    "},{"location":"Components/Traffic/TrafficComponents/#components_3","title":"Components","text":"

    StopLine consists of an Object containing Stop Line (script).

    Stop Line has a transformation property - as every Object in Unity - however it is not used in any way. All details are configured in the Traffic Lane (script), the information in Object transformation is ignored.

    "},{"location":"Components/Traffic/TrafficComponents/#stop-line-script","title":"Stop Line (script)","text":"

    Stop Line (script) defines StopLine configuration. The Points field is an ordered list of points that - when connected - create a StopLine. The list of points should always have two elements that create a straight StopLine.

    Stop Line (script) coordinate system

    Points are defined in the Environment coordinate system, the transformation of GameObject is ignored.

    The Has Stop Sign field contains information whether the configured StopLine has a corresponding StopSign on the scene.

    Every Stop Line needs to have a Traffic Light field configured with the corresponding Traffic Light. This information allows the RandomTrafficSimulator to manage the NPCVehicles in such a way that they respect the Traffic Lights and behave on the Traffic Intersections correctly.

    "},{"location":"Components/Traffic/TrafficComponents/#gizmos","title":"Gizmos","text":"

    Gizmos are a in-simulation visualization showing current and future moves of the NPCVehicles. They are useful for checking current behavior of NPCs and its causes. On the Scene they are visible as cuboid contours indicating which TrafficLanes will be taken by each vehicle in the near future.

    Gizmos computing

    Gizmos have a high computational load. Please disable them if the simulation is laggy.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/","title":"Add Vehicle","text":"

    Ego Vehicle Component

    In this tutorial we will create a new EgoVehicle. To learn more about what an EgoVehicle is in AWSIM please visit Ego Vehicle description page.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#cerate-an-object","title":"Cerate an Object","text":"

    Add a child Object to the Simulation called EgoVehicle.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-rigidbody","title":"Add a Rigidbody","text":"

    1. While having a newly created EgoVehicle Object selected, in the Inspector view click on the 'Add Component' button, search for Rigidbody and select it.

    2. Configure Mass and Drag with the correct values for your Vehicle.

    3. Configure Interpolation and Collision Detection.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-visual-elements","title":"Add visual elements","text":"

    For a detailed explanation hwo to add visual elements of your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-canter-of-mass","title":"Add a Canter of Mass","text":"

    To add a center of mass to your vehicle you have to add a CoM child Object to the EgoVehicle Object (the same as in steps before).

    Then just set the position of the CoM Object in the Inspector view to represent real-world center of mass of the Vehicle.

    How do I know what is the Center of Mass of my Vehicle

    The best way is to obtain a Center of Mass information from your Vehicle documentation.

    However, if this is not possible, you can try to estimate the Center of Mass of your vehicle. Best practice is to set the estimated Center of Mass as the following

    • Evenly between the axles of the Vehicle
    • Right in the middle of the Vehicles width
    • Somewhere in the neighborhood of a quarter of the Vehicle height

    Note: This will vary very much depending on your Vehicle construction. For the best possible result please follow the Vehicle specifications.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-reflection-probe","title":"Add a Reflection Probe","text":"

    1. Add a new Object called Reflection Probe as a child to the EgoVehicle Object.

    2. Click on the 'Add Component' button, in the windows that pops-up search for Reflection Probe and select it.

      Note

      Please note that with Reflection Probe there should also be automatically added a `HD Additional Reflection Data Script.

    3. Configure the Reflection Probe as you wish.

      Example Configuration

      Below you can see an example configuration of the Reflection Probe.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-colliders","title":"Add Colliders","text":"

    For a detailed explanation how to add colliders to your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-base-for-sensors-urdf","title":"Add a base for sensors (URDF)","text":"

    You will most certainly want to add some sensors to your EgoVehicle. First you need to create a parent Object for all those sensors called URDF. To do this we will add a child Object URDF to the EgoVehicle Object.

    This Object will be used as a base for all sensors we will add later.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-script","title":"Add a Vehicle Script","text":"

    To be able to control your EgoVehicle you need a Vehicle Script.

    1. Add the Vehicle Script to the EgoVehicle Object.

    2. Configure the Vehicle Script Axle Settings and Center Of Mass Transform.

    Testing

    It is not possible to test this Script alone, but you can test the following

    • Vehicle Keyboard Input Script
    • Vehicle Visual Effects Script
    • Vehicle Ros Input Script

    If components listed above work correctly this means the Vehicle Script works correctly too.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-keyboard-input-script","title":"Add a Vehicle Keyboard Input Script","text":"

    You can control your EgoVehicle in the simulation manually with just one Script called Vehicle Keyboard Input.

    If you want to add it just click the 'Add Component' button on the EgoVehicle Object and search for Vehicle Keyboard Input Script and select it.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-visual-effect-script","title":"Add a Vehicle Visual Effect Script","text":"

    For a visual indication of a Vehicle status you will need a Vehicle Visual Effect Script. To add and configure it follow the steps below.

    1. Add a Vehicle Visual Effect Script by clicking 'Add Component' button, searching for it and selecting it.

    2. Configure the lights.

      Note

      In this step we will configure only Brake Lights, but should repeat this for every Light. The process is almost the same for all Lights - just change the mesh renderer and lighting settings according to your preference.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#how-to-test","title":"How to test","text":"

    After configuring Vehicle Visual Effect Script it is advised to test whether everything works as expected.

    1. Make sure you have a Vehicle Keyboard Input Script added and that it is enabled.

    2. If your scene does not have any models yet please turn the gravity off in Rigidbody configuration so that the Vehicle does not fall down into infinity.

    3. Start the simulation.

    4. Test the Turn Signals.

      You can control the Turn Signals with a Vehicle Keyboard Input Script. Activate the Turn Signals with one of the following keys

      • 1 - Left Turn Signal
      • 2 - Right Turn Signal
      • 3 - Hazard Lights
      • 4 - Turn Off all Signals

    5. Test the Lights.

      You can control the lights by \"driving\" the Vehicle using Vehicle Keyboard Input Script. Although if you have an empty Environment like in this tutorial the Vehicle won't actually drive.

      To test Brake Lights change the gear to Drive by pressing D on the keyboard and activate braking by holding arrow down.

      To test the Reverse Light change the gear to Reverse by pressing R on the keyboard. The Reverse Light should turn on right away.

    Camera tip

    If you have not configured a camera or configured it in such a way that you can't see the Vehicle well you can still test most of the lights by changing views.

    • Turn the Light (or Signal) on by pressing the appropriate key
    • Move to the Scene View by pressing ctrl + 1 - now you can move the camera freely
    • To change the Lights you need to go back to Game View by pressing ctrl + 2

    Pleas note that this method won't work for testing Brake Lights, as for them to work you need to keep the arrow down button pressed all the time.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-ros-input-script","title":"Add a Vehicle Ros Input Script","text":"

    For controlling your Vehicle with autonomous driving software (e.g. Autoware) you need a Vehicle Ros Input Script.

    Disable Vehicle Keyboard Input Script

    If you have added a Vehicle Keyboard Input Script in your Vehicle please disable it when using the Vehicle Ros Input Script.

    Not doing so will lead to the vehicle receiving two different inputs which will cause many problems.

    Add it to the EgoVehicle Object by clicking on the 'Add Component' button, searching for it and selecting it.

    The Script is configured to work with Autoware by default, but you can change the topics and Quality of Service settings as you wish.

    Note

    The Vehicle should be configured correctly, but if you have many Vehicles or something goes wrong, please select the right Vehicle in the Vehicle field by clicking on the small arrow icon and choosing the right item from the list.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#how-to-test_1","title":"How to test","text":"

    The best way to test the Vehicle Ros Input Script is to run Autoware.

    1. Run the Scene same as on this page.
    2. Launch only the Autoware like on this page
    3. Plan a path in Autoware like here, if the Vehicle moves in AWSIM correctly then the Script is configured well.
    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-sensors","title":"Add Sensors","text":"

    For a detailed explanation how to add sensors to your Vehicle check out this dedicated tutorial.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddAVehicle/#add-a-vehicle-to-scene","title":"Add a Vehicle to Scene","text":"

    First you will have to save the Vehicle you created as a prefab, to easily add it later to different Scenes.

    1. Open the Vehicles directory in the Project view (Assets/AWSIM/Prefabs/Vehicles)
    2. Drag the Vehicle Object from the Hierarchy view to the Vehicles directory

    After that, you can add the Vehicle you created to different Scenes by dragging it from Vehicles directory to the Hierarchy of different Scenes.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/","title":"Add Colliders","text":"

    Next you need to add Colliders to your Vehicle. To do this follow the steps below.

    1. Add a child Object called Colliders to the EgoVehicle Object.

    2. Shift parent Object Colliders accordingly as in earlier steps where we shifted Models.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/#add-a-vehicle-collider","title":"Add a Vehicle Collider","text":"

    1. Add a child Object Collider to the Colliders Object.

    2. Add a Mesh Collider component to the Collider Object by clicking on the 'Add Component' button in the Inspector view and searching for it.

    3. Click on the arrow in mesh selection field and from the pop-up window select your collider mesh. Next click on the check-box called Convex, by now your collider mesh should be visible in the editor.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddColliders/#add-wheel-colliders","title":"Add Wheel Colliders","text":"

    1. Add a child Object Wheels to the Colliders Object.

    Note

    In this tutorial we will add only one wheel collider, but you should repeat the step for all 4 wheels. That is, follow the instructions that follow this message for every wheel your Vehicle has.

    • Front Left Wheel
    • Front Right Wheel
    • Rear Left Wheel
    • Rear Right Wheel

    1. Add a child Object FrontLeftWheel to the Wheels Object.

    2. Add a Wheel Collider component to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    3. Add a Wheel Script to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    4. Drag FrontLeftWheel Object from the WheelVisuals to the Wheel Visual Transform field.

    5. Add a Wheel Collider Config Script to the FrontLeftWheel Object by clicking 'Add Component' and searching for it.

    6. Configure the Wheel Collider Config Script so that the Vehicle behaves as you wish.

    7. Set the Transform of FrontLeftWheel Object to match the visuals of your Vehicle.

    Successful configuration

    If you have done everything right your Colliders Object should look similar to the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/","title":"Add Sensors","text":""},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#awsim-sensors","title":"AWSIM Sensors","text":"

    There is a number of different sensors available in AWSIM. Below we present a list of sensors with links to their individual pages.

    • Vehicle Status Sensor
    • GNSS
    • LiDAR
    • IMU
    • Camera
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-links-for-sensors","title":"Add links for sensors","text":"

    Best practice is to replicate a ROS sensors transformations tree in Unity using Objects.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#coordinate-system-conversion","title":"Coordinate system conversion","text":"

    Please note that Unity uses less common left-handed coordinate system. Please keep this in mind while defining transformations. More details about right-handed and left-handed systems can be found here.

    To simplify the conversion process always remember that any point in ROS coordinate system (x, y, z) has an equivalent in the Unity coordinate system being (-y, z, x).

    The same can be done with the rotation. ROS orientation described with roll, pitch and yaw (r, p, y) can be translated to Unity Rotation as follows (p, -y, -r).

    Unit conversion

    Please remember to convert the rotation units. ROS uses radians and Unity uses degrees. The conversion from radians (rad) to degrees (deg) is as follows.

    deg = rad * 180 / PI\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-transformations-tree","title":"Add transformations tree","text":"

    URDF

    Before following this tutorial please make sure you have an URDF Object like it is shown shown in this section.

    First we will have to add a base_link which is the root of all transformations.

    Add a base_link Object as a child to the URDF Object.

    base_link transformation

    Please remember to set an appropriate transformation of the base_link Object so that it is identical as the base_link used in ROS in reference to the Vehicle.

    This is very important, as a mistake here will result in all subsequent sensors being misplaced.

    Inside the base_link we will represent all transformations contained in the ROS transformations tree.

    You will have to check your Vehicle specific configuration. You can do this in many ways, for example:

    • Check the ROS specific .yaml parameter files containing information about each transformation.

      Example

      Here we see an example .yaml file containing transformation from the base_link to the sensor_kit_base_link:

      base_link:\n    sensor_kit_base_link:\n        x: 0.9\n        y: 0.0\n        z: 2.0\n        roll: -0.001\n        pitch: 0.015\n        yaw: -0.0364\n

    • Check the values with ROS command line tools (for more information on these please visit official ROS 2 documentation).

      You can run a command like the following to check a transformation between two frames.

      ros2 run tf2_ros tf2_echo [source_frame] [target_frame]\n

      Example

      Here we see an example command with the output containing transformation from the base_link to the sensor_kit_base_link (note that the line after $ sign is the executed command):

      $ ros2 run tf2_ros tf2_echo base_link sensor_kit_base_link\n[INFO] [1686654712.339110702] [tf2_echo]: Waiting for transform base_link ->  sensor_kit_base_link: Invalid frame ID \"base_link\" passed to canTransform argument target_frame - frame does not exist\nAt time 0.0\n- Translation: [0.900, 0.000, 2.000]\n- Rotation: in Quaternion [-0.000, 0.008, -0.018, 1.000]\n- Rotation: in RPY (radian) [-0.001, 0.015, -0.036]\n- Rotation: in RPY (degree) [-0.057, 0.859, -2.086]\n- Matrix:\n0.999  0.036  0.015  0.900\n-0.036  0.999  0.000  0.000\n-0.015 -0.001  1.000  2.000\n0.000  0.000  0.000  1.000\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-one-sensor-link","title":"Add one sensor link","text":"

    Note

    In this step we will only add one sensor link. You will have to repeat this step for every sensor you want to add to your Vehicle.

    Let's say we want to add a LiDAR that is facing right.

    We have the following configuration files.

    base_link:\n    sensor_kit_base_link:\n        x: 0.9\n        y: 0.0\n        z: 2.0\n        roll: -0.001\n        pitch: 0.015\n        yaw: -0.0364\n
    sensor_kit_base_link:\n    velodyne_right_base_link:\n        x: 0.0\n        y: -0.56362\n        z: -0.30555\n        roll: -0.01\n        pitch: 0.71\n        yaw: -1.580\n

    We can clearly see the structure of transformation tree. The transformations are as follows.

    base_link -> sensor_kit_base_link -> velodyne_right_base_link\n

    We need to start adding these transformation from the root of the tree. We will start with the sensor_kit_base_link, as the base_link already exists in our tree.

    1. The first step is to add an Object named the same as the transformation frame (sensor_kit_base_link).

    2. Next we have to convert the transformation from ROS standard to the Unity standard. This is done with the formulas show in this section.

      The result of conversion of the coordinate systems and units is shown below.

      Position:\n(0.9, 0.0, 2.0)             ->  (0.0, 2.0, 0.9)\nRotation:\n(-0.001, 0.015, -0.0364)    ->  (0.8594, 2.0856, 0.0573)\n

      The resulting sensor_kit_base_link Object transformation is shown below.

    Now the same has to be done with the velodyne_right_base_link.

    1. Add transformation Object (velodyne_right_base_link).

      Info

      Remember to correctly set the child Object, in this case we use sensor_kit_base_link as a child, because this is what the .yaml file says.

    2. Convert the transformation into Unity coordinate system.

      The correct transformation is shown below.

      Position:\n(0, -0.56362, -0.30555)     ->  (0.56362, -0.30555, 0)\nRotation:\n(-0.01, 0.71, -1.580)       ->  (40.68, 90.5273, 0.573)\n

      The final velodyne_right_base_link Object transformation is shown below.

    Success

    If you have done everything right, after adding all of the sensor links your URDF Object tree should look something like the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-sensors","title":"Add sensors","text":"

    After adding links for all sensors you need to add the actual sensors into your Vehicle.

    Sensor position

    Please keep in mind, that we have created the sensor links in order to have an accurate transformations for all of the sensors. This implies that the Sensor Object itself can not have any transformation.

    If one of your Sensors, after adding it to the scene, is mispositioned, check whether the transformation is set to identity (position and rotation are zeros).

    When adding sensors almost all of them will have some common fields.

    • Frame Id

      Frame Id is the name of frame of reference against which the received data will be interpreted by the autonomous driving software stack.

      Remember that the Frame Id must exist internally in the ROS transformations tree.

    • Topics

      Topics are names of broadcasting channels. You can set the names of topics as you like and the data from sensors will be broadcasted on these topics.

      Remember to configure your receiving end to listen on the same topics as broadcasting ones.

    • Quality Of Service settings (QOS settings)

      Quality of service settings allow you to configure the behavior of the source node while broadcasting the sensor data. You can adjust these settings to suit your needs.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-vehicle-status-sensor","title":"Add a Vehicle Status Sensor","text":"

    To add a Vehicle Status Sensor to your Vehicle simply locate the following directory in the Project view and drag a prefab of this Sensor into the URDF Object.

    Assets/AWSIM/Prefabs/Sensors\n

    Next in the Inspector View select your Vehicle.

    ROS message example

    In this example you can see what a valid message from the Vehicle Status Sensor can look like.

    $ ros2 topic echo --once /vehicle/status/velocity_status\nheader:\n  stamp:\n    sec: 17\n    nanosec: 709999604\n  frame_id: base_link\nlongitudinal_velocity: 0.004912620410323143\nlateral_velocity: -0.005416259169578552\nheading_rate: 0.006338323466479778\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-lidar","title":"Add a LiDAR","text":"

    Scene Manager

    Before continuing with this tutorial please check out a dedicated one focused on Scene Manager.

    To add a LiDAR to your Vehicle you will have to drag a model of the LiDAR to the link tree you have created in the earlier step.

    You can use the predefined RGL LiDAR models or any other LiDAR models. In this tutorial we will be using RGL VelodyneVLP16 LiDAR model.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors/RobotecGPULidars\n

    LiDAR noise configuration

    LiDAR Sensor in simulation is returning a perfect result data. This is not an accurate representation of the real-world.

    LiDAR Sensor addresses this issue by applying a simulated noise to the output data. You can configure the noise parameters in the Inspector View under Configuration -> Noise Params fields.

    You can optionally remove the noise simulation by unchecking the Apply Distance/Angular Gaussian Noise.

    You can also change the ranges of the LiDAR detection.

    There is also a possibility to configure the visualization of the Point Cloud generated by the LiDAR. E.g. change the hit-point shape and size.

    ROS message example

    In this example you can see what a valid message from the LiDAR Sensor can look like.

    $ ros2 topic echo --once /lidar/pointcloud\nheader:\n  stamp:\n    sec: 20\n    nanosec: 589999539\n  frame_id: world\nheight: 1\nwidth: 14603\nfields:\n- name: x\n  offset: 0\n  datatype: 7\n  count: 1\n- name: y\n  offset: 4\n  datatype: 7\n  count: 1\n- name: z\n  offset: 8\n  datatype: 7\n  count: 1\n- name: intensity\n  offset: 16\n  datatype: 7\n  count: 1\n- name: ring\n  offset: 20\n  datatype: 4\n  count: 1\nis_bigendian: false\npoint_step: 24\nrow_step: 350472\ndata:\n- 156\n- 218\n- 183\n- 62\n- 0\n- 189\n- 167\n- 187\n- 32\n- 58\n- 173\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 1\n- 0\n- 0\n- 0\n- 198\n- 129\n- 28\n- 63\n- 0\n- 6\n- 230\n- 58\n- 128\n- 184\n- 93\n- 61\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 9\n- 0\n- 0\n- 0\n- 92\n- 2\n- 194\n- 62\n- 0\n- 141\n- 42\n- 187\n- 128\n- 89\n- 139\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 2\n- 0\n- 0\n- 0\n- 187\n- 168\n- 42\n- 63\n- 0\n- 159\n- 175\n- 59\n- 160\n- 243\n- 185\n- 61\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 10\n- 0\n- 0\n- 0\n- 119\n- 186\n- 204\n- 62\n- 0\n- 254\n- 23\n- 59\n- 128\n- 143\n- 41\n- 189\n- 0\n- 0\n- 0\n- 0\n- 0\n- 0\n- 200\n- 66\n- 3\n- 0\n- 0\n- 0\n- 65\n- 241\n- 59\n- 63\n- 128\n- 0\n- 252\n- 187\n- '...'\nis_dense: true\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-an-imu","title":"Add an IMU","text":"

    To add an IMU to your Vehicle you will have to drag a model of the IMU to the link tree you have created in the earlier step.

    You can use the provided or your own IMU Sensor. In this tutorial we will be using IMU Sensor provided with AWSIM.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the IMU Sensor can look like.

    $ ros2 topic echo --once /sensing/imu/tamagawa/imu_raw\nheader:\n  stamp:\n    sec: 20\n    nanosec: 589999539\n  frame_id: tamagawa/imu_link\norientation:\n  x: 0.0\n  y: 0.0\n  z: 0.0\n  w: 1.0\norientation_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\nangular_velocity:\n  x: 0.014335081912577152\n  y: 0.008947336114943027\n  z: -0.008393825963139534\nangular_velocity_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\nlinear_acceleration:\n  x: 0.006333829835057259\n  y: -0.005533283110707998\n  z: -0.0018753920448943973\nlinear_acceleration_covariance:\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n- 0.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-gnss","title":"Add a GNSS","text":"

    To add a GNSS Sensor to your Vehicle you will have to drag a model of the GNSS to the link tree you have created in the earlier step.

    You can use the provided or your own GNSS Sensor. In this tutorial we will be using GNSS Sensor provided with AWSIM.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the GNSS Sensor can look like.

    $ ros2 topic echo --once /sensing/gnss/pose\nheader:\n  stamp:\n    sec: 8\n    nanosec: 989999799\n  frame_id: gnss_link\npose:\n  position:\n    x: 81656.765625\n    y: 50137.5859375\n    z: 44.60169219970703\n  orientation:\n    x: 0.0\n    y: 0.0\n    z: 0.0\n    w: 0.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-camera","title":"Add a Camera","text":"

    To add a Camera Sensor to your Vehicle you will have to drag a model of the Camera to the link tree you have created in the earlier step.

    Simply locate the following directory in the Project view and drag the prefab into the designated sensor link.

    Assets/AWSIM/Prefabs/Sensors\n

    You can configure some aspects of the Camera to your liking.

    E.g. you can set the field of view (fov) of the camera by changing the Field of View field or manipulating the physical camera parameters like Focal Length.

    The important thing is to configure the Camera Sensor Script correctly.

    Always check whether the correct Camera Object is selected and make sure that Distortion Shader and Ros Image Shader are selected.

    Example Camera Sensor Script configuration

    You can add the live Camera preview onto the Scene. To do this select the Show checkbox. Additionally you can change how the preview is displayed. Change the Scale value to control the size of the preview (how many times smaller the preview will be compared to the actual screen size).

    Move the preview on the screen by changing the X Axis and Y Axis values on the Image On Gui section.

    Camera preview example

    Testing camera with traffic light recognition

    You can test the Camera Sensor traffic light recognition by positioning the vehicle on the Unity Scene in such a way that on the Camera preview you can see the traffic lights.

    Remember to lock the Inspector view on Camera Object before dragging the whole Vehicle - this way you can see the preview while moving the vehicle.

    Run the Scene the same as on this page.

    Launch only the Autoware like on this page.

    By default you should see the preview of traffic light recognition visualization in the bottom left corner of Autoware.

    Traffic lights recognition example in Autoware

    ROS message example

    In this example you can see what a valid message from the Camera Sensor can look like.

    $ ros2 topic echo --once /sensing/camera/traffic_light/image_raw\nheader:\n  stamp:\n    sec: 14\n    nanosec: 619999673\n  frame_id: traffic_light_left_camera/camera_optical_link\nheight: 1080\nwidth: 1920\nencoding: bgr8\nis_bigendian: 0\nstep: 5760\ndata:\n- 145\n- 126\n- 106\n- 145\n- 126\n- 106\n- 145\n- 126\n- 106\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 105\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 104\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 126\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 103\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 124\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- 101\n- 145\n- 123\n- '...'\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#add-a-pose-sensor","title":"Add a Pose Sensor","text":"

    To add a Pose Sensor to your Vehicle simply locate the following directory in the Project view and drag a prefab of this Sensor into the base_link Object.

    Assets/AWSIM/Prefabs/Sensors\n

    ROS message example

    In this example you can see what a valid message from the Pose Sensor can look like.

    $ ros2 topic echo --once /awsim/ground_truth/vehicle/pose\nheader:\n  stamp:\n    sec: 5\n    nanosec: 389999879\n  frame_id: base_link\npose:\n  position:\n    x: 81655.7578125\n    y: 50137.3515625\n    z: 42.8094367980957\n  orientation:\n    x: -0.03631274029612541\n    y: 0.0392342209815979\n    z: 0.02319677732884884\n    w: 0.9983005523681641\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddSensors/#test-a-sensor","title":"Test a Sensor","text":"

    You can test whether the Sensor works correctly in several ways.

    1. Check whether the configuration is correct.

      In terminal source ROS with the following line (only if you haven't done so already).

      source /opt/ros/humble/setup.bash\n

      Check the details about the topic that your Sensor is broadcasting to with the following command.

      ros2 topic info -v <topic_name>\n

      Example

      In this example we can see that the message is broadcasted by AWSIM and nobody is listening. We can also examine the Quality of Service settings.

      $ ros2 topic info -v /awsim/ground_truth/vehicle/pose\nType: geometry_msgs/msg/PoseStamped\n\nPublisher count: 1\n\nNode name: AWSIM\nNode namespace: /\nTopic type: geometry_msgs/msg/PoseStamped\nEndpoint type: PUBLISHER\nGID: 01.10.13.11.98.7a.b1.2a.ee.a3.5a.11.00.00.07.03.00.00.00.00.00.00.00.00\nQoS profile:\n  Reliability: RELIABLE\n  History (Depth): KEEP_LAST (1)\n  Durability: VOLATILE\n  Lifespan: Infinite\n  Deadline: Infinite\n  Liveliness: AUTOMATIC\n  Liveliness lease duration: Infinite\n\nSubscription count: 0\n

    2. Check whether correct information is broadcasted.

      In terminal source ROS with the following line (only if you haven't done so already).

      source /opt/ros/humble/setup.bash\n

      View one transmitted message.

      ros2 topic echo --once <topic_name>\n

      Example

      In this example we can see the Vehicles location at the moment of executing the command.

      NOTE: The position and orientation are relative to the frame in the header/frame_id field (base_link in this example).

      $ ros2 topic echo --once /awsim/ground_truth/vehicle/pose\nheader:\n  stamp:\n    sec: 46\n    nanosec: 959998950\n  frame_id: base_link\npose:\n  position:\n    x: 81655.7265625\n    y: 50137.4296875\n    z: 42.53997802734375\n  orientation:\n    x: 0.0\n    y: -9.313260163068549e-10\n    z: -6.36646204504876e-12\n    w: 1.0\n---\n
    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/","title":"Add Visual Elements","text":"

    Your EgoVehicle needs many individual visual parts. Below we will add all needed visual elements.

    First in EgoVehicle Object add a child Object called Models.

    Inside Models Object we will add all visual models of our EgoVehicle.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-a-body","title":"Add a Body","text":"

    First you will need to add a Body of your Vehicle. It will contain many parts, so first lets create a Body parent Object.

    Next we will need to add Car Body

    1. Add a child Object BodyCar to the Body Object.

    2. To the BodyCar Object add a Mesh Filter.

      Click on the 'Add Component' button, search for Mesh Filter and select it. Next search for mesh of your vehicle and select it in the Mesh field.

    3. To the BodyCar Object add a Mesh Renderer.

      Click on the 'Add Component' button, search for Mesh Filter and select it

    4. Specify Materials.

      You need to specify what materials will be used for rendering your EgoVehicle model. Do this by adding elements to the Materials list and selecting the materials you wish to use as shown below.

      Add as many materials as your model has sub-meshes.

      Tip

      When you add too many materials, meaning there will be no sub-meshes to apply these materials to, you will see this warning. In such a case please remove materials until this warning disappears.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-interactive-body-parts","title":"Add interactive Body parts","text":"

    In this step we will add the following parts

    • Break light
    • Reverse Light
    • Right Turn Signal
    • Left Turn Signal
    • (optional) other visual elements required specifically by your Vehicle.

    Info

    It may seem like all of the elements above can be parts of the Body mesh, but it is important for these parts to be separate, because we need to be able to make them interactive (e.g. flashing turn signals).

    Other good reason for having different meshes for Vehicle parts is that you have a Vehicle model, but for the simulation you need to add e.g. a roof rack with sensors - which can be achieved by adding more meshes.

    Note

    We will illustrate this step only for Break Light, but you should repeat this step of the tutorial for each element of the list above.

    1. Add a child Object to the Body Object.

    2. Add a Mesh Filter and select the mesh (the same as in section before).

    3. Add a Mesh Renderer and select the materials (the same as in section before).

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#add-wheels","title":"Add Wheels","text":"

    In this step we will add individual visuals for every wheel. This process is very similar to the one before.

    1. Add a child Object to the Models Object called WheelVisuals.

    Note

    In this tutorial we will add only one wheel, but you should repeat the step for all 4 wheels. That is, follow the instructions that follow this message for every wheel your Vehicle has.

    • Front Left Wheel
    • Front Right Wheel
    • Rear Left Wheel
    • Rear Right Wheel

    1. Add a child Object to the WheelVisuals Object called FrontLeftWheel.

    2. Add a child Object to the FrontLeftWheel Object called WheelFrontL. This Object will contain the actual wheel part.

    3. Add a Mesh Filter and select the wheel mesh.

    4. Add a Mesh Renderer and select the wheel materials.

    5. Repeat the steps before to add Breaks.

      The same way you have added the WheelFrontL Object now add the WheelFrontLBreaks. Naturally you will have to adjust the mesh and materials used as they will be different for breaks than for the wheel.

      Your final break configuration should look similar to the one following.

    6. Set the FrontLeftWheel parent Object transformation to position the wheel in correct place.

    Successful configuration

    If you have done everything right your WheelVisuals Object should look similar to the one following.

    "},{"location":"Components/Vehicle/AddNewVehicle/AddVisualElements/#move-the-models","title":"Move the models","text":"

    The last step to correctly configure Vehicle models is to shift them so that the EgoVehicle origin is in the center of fixed axis.

    This means you need to shift the whole Models Object accordingly (change the position fields in transformation).

    Tip

    Add a dummy Object as a child to the EgoVehicle Object (the same as in steps before) so it is located in the origin of the EgoVehicle.

    Now move Models around relative to the dummy - change position in the Inspector view. The dummy will help you see when the fixed axis (in case of the Lexus from example it is the rear axis) is aligned with origin of EgoVehicle.

    In the end delete the dummy Object as it is no longer needed.

    "},{"location":"Components/Vehicle/CustomizeSlip/","title":"Customize Slip","text":""},{"location":"Components/Vehicle/CustomizeSlip/#customize-slip","title":"Customize slip","text":"

    By attaching a GroundSlipMutiplier.cs script to a collider (trigger), you can change the slip of the vehicle within the range of that collider.

    "},{"location":"Components/Vehicle/CustomizeSlip/#sample-scene","title":"Sample scene","text":"

    Assets\\AWSIM\\Scenes\\Samples\\VehicleSlipSample.unity

    "},{"location":"Components/Vehicle/CustomizeSlip/#how-to-setup","title":"How to setup","text":"
    1. Create collider
    2. Check IsTrigger
    3. Change properties of FowardSlip and SidewaySlip.
    "},{"location":"Components/Vehicle/DynamicSensorPlacement/","title":"Dynamic Sensor Placement","text":""},{"location":"Components/Vehicle/DynamicSensorPlacement/#dynamic-sensor-placement","title":"Dynamic Sensor Placement","text":"

    This tool allows you to dynamically place sensors on a car using positions and rotations specified in a URDF file.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#follow-the-steps-to-generate-the-urdf-file","title":"Follow the steps to generate the urdf file:","text":"

    1. Build Autoware by following the instruction in https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/.

    2. Modify L3-4 in $HOME/autoware/src/universe/autoware.universe/launch/tier4_vehicle_launch/urdf/vehicle.xacro as the following,

          <xacro:arg name=\"vehicle_model\" default=\"sample_vehicle\"/>\n    <xacro:arg name=\"sensor_model\" default=\"awsim_sensor_kit\"/>\n

    3. Run the following commands:

      source $HOME/autoware/install/setup.bash\n\nros2 run xacro xacro -o awsim_vehicle.urdf $HOME/autoware/src/universe/autoware.universe/launch/tier4_vehicle_launch/urdf/vehicle.xacro\n

    4. You should now have a URDF file named awsim_vehicle.urdf.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#using-the-dynamic-sensor-placement-tool","title":"Using the Dynamic Sensor Placement tool:","text":"

    1. Open up AWSIM and place the generated awsim_vehicle.urdf in the Externals folder so the path will be ./Assets/AWSIM/Externals/awsim_vehicle.urdf.

    2. Now, under open up the Dynamic sensor placement tool under AWSIM menu.

    3. Enter the path to the URDF file

    4. Click \"Place sensors\". All the sensors should be automatically placed on the car.

    "},{"location":"Components/Vehicle/DynamicSensorPlacement/#note","title":"Note","text":"

    1. Only the game object named sensor_kit_base_link and its direct children will be assigned transforms if they are mentioned in the URDF file as children of sensor_kit_base_link. You will need to manually place the base_link game object.

    2. Ensure the names of the game objects are exactly the same as those mentioned in the URDF file. Look for the name of the child of sensor_kit_base_link in the URDF file under the <joint> tag.

      For example:

      <joint name=\"velodyne_top_base_mount_joint\" type=\"fixed\">\n    <origin rpy=\"0.0 0.0 1.575\" xyz=\"0.0 0.0 0.0\"/>\n    <parent link=\"sensor_kit_base_link\"/>\n    <child link=\"velodyne_top_base_link\"/>\n</joint>\n

    3. Finally, ensure that all the direct children of the sensor game objects have their rotations and positions set to zero.

    "},{"location":"Components/Vehicle/EgoVehicle/","title":"Ego Vehicle","text":""},{"location":"Components/Vehicle/EgoVehicle/#introduction","title":"Introduction","text":"

    EgoVehicle is a playable object that simulates a vehicle that can autonomously move around the scene. It has components (scripts) that make it possible to control it by keyboard or by Autoware (using ROS2 communication). Moreover, it provides sensory data needed for self-localization in space and detection of objects in the surrounding environment.

    The default prefab EgoVehicle was developed using a Lexus RX450h 2015 vehicle model with a configured sample sensor kit.

    Own EgoVehicle prefab

    If you would like to develop your own EgoVehicle prefab, we encourage you to read this tutorial.

    "},{"location":"Components/Vehicle/EgoVehicle/#supported-features","title":"Supported features","text":"

    This vehicle model was created for Autoware simulation, and assuming that Autoware has already created a gas pedal map, this vehicle model uses acceleration as an input value. It has the following features:

    • Longitudinal control by acceleration (\\(\\frac{m}{s^2}\\)).
    • Lateral control by two-wheel model.
    • Yaw, roll and pitch controlled by Physics engine.
    • Mass-spring-damper suspension model (WheelColliders).
    • Logical, not mechanical, automatic gears change.
    • 3D Mesh (*.fbx) as road surface for vehicle driving, gradient resistance.

    AutowareSimulation

    If you would like to see how EgoVehicle works or run some tests, we encourage you to familiarize yourself with the AutowareSimulation scene described in this section.

    "},{"location":"Components/Vehicle/EgoVehicle/#lexus-rx450h-2015-parameters","title":"Lexus RX450h 2015 parameters","text":"Parameter Value Unit Mass \\(1500\\) \\(kg\\) Wheel base \\(2.5\\) \\(m\\) Tread width \\(Ft = 1.8; Rr = 1.8\\) \\(m\\) Center of Mass position \\(x = 0; y = 0.5; z = 0\\) \\(m\\) Moment of inertia \\(\\mathrm{yaw} = 2000; \\mathrm{roll} = 2000; \\mathrm{pitch} = 700\\) \\(kg \\cdot m^2\\) Spring rate \\(Ft = 55000; Rr = 48000\\) \\(N\\) Damper rate \\(Ft = 3000; Rr = 2500\\) \\(\\frac{N}{s}\\) Suspension stroke \\(Ft = 0.2; Rr = 0.2\\) \\(m\\) Wheel radius \\(0.365\\) \\(m\\)

    Vehicle inertia

    In general, measuring the moment of inertia is not easy, and past papers published by NHTSA are helpful. Measured Vehicle Inertial Parameters - NHTSA 1998

    "},{"location":"Components/Vehicle/EgoVehicle/#prefab-and-fbx","title":"Prefab and Fbx","text":"

    Prefab can be found under the following path:

    Assets/AWSIM/Prefabs/NPCs/Vehicles/Lexus RX450h 2015 Sample Sensor.prefab\n

    EgoVehicle name

    In order to standardize the documentation, the name EgoVehicle will be used in this section as the equivalent of the prefab named Lexus RX450h 2015 2015 Sample Sensor.

    EgoVehicle prefab has the following content:

    As you can see, it consists of 3 parents for GameObjects:

    • Models - aggregating visual elements,
    • Colliders - aggregating colliders,
    • URDF - aggregating sensors,
    • and 2 single GameObjects: CoM and Reflection Probe.

    All objects are described in the sections below.

    "},{"location":"Components/Vehicle/EgoVehicle/#visual-elements","title":"Visual elements","text":"

    Prefab is developed using models available in the form of *.fbx files. The visuals elements have been loaded from the appropriate *.fbx file and are aggregated and added in object Models.

    *.fbx file for Lexus RX450h 2015 is located under the following path:

    Assets/AWSIM/Models/Vehicles/Lexus RX450h 2015.fbx\n

    Models object has the following content:

    As you can see, the additional visual element is XX1 Sensor Kit.

    It was also loaded from the *.fbx file which can be found under the following path:

    Assets/AWSIM/Models/Sensors/XX1 Sensor Kit.fbx\n

    Lexus RX450h 2015.fbx

    The content of a sample *.fbx file is presented below, all elements except Collider have been added to the prefab as visual elements of the vehicle. Collider is used as the Mesh source for the Mesh Collider in the BodyCollider object.

    "},{"location":"Components/Vehicle/EgoVehicle/#link-in-the-default-scene","title":"Link in the default Scene","text":"

    The default scene contains a single Lexus RX450h 2015 Sample Sensor prefab that is added as a child of the EgoVehicle GameObject.

    In EgoVehicle prefab, the local coordinate system of the vehicle (main prefab link) should be defined in the axis of the rear wheels projected onto the ground - in the middle of the distance between them. This aspect holds significance when characterizing the dynamics of the object, as it provides convenience in terms of describing its motion and control.

    "},{"location":"Components/Vehicle/EgoVehicle/#components","title":"Components","text":"

    There are several components responsible for the full functionality of Vehicle:

    • Rigidbody - ensures that the object is controlled by the physics engine in Unity - e.g. pulled downward by gravity.
    • Vehicle (script) - provides the ability to set the acceleration of the vehicle and the steering angle of its wheels.
    • Vehicle Keyboard Input (script) - provides the ability to set inputs in the Vehicle (script) via the keyboard.
    • Vehicle Ros Input (script) - provides the ability to set inputs in the Vehicle (script) via subscribed ROS2 topics (outputs from Autoware).
    • Vehicle Visual Effect - provides the ability to simulate vehicle lights, such as turn signals, brake lights, and hazard light.

    Scripts can be found under the following path:

    Assets/AWSIM/Scripts/Vehicles/*\n
    "},{"location":"Components/Vehicle/EgoVehicle/#architecture","title":"Architecture","text":"

    The EgoVehicle architecture - with dependencies - is presented on the following diagram.

    The communication between EgoVehicle components is presented on two different diagrams - a flow diagram and a sequence diagram.

    The flow diagram presents a flow of information between the EgoVehicle components.

    The sequence diagram provides a deeper insight in how the communication is structured and what are the steps taken by each component. Some tasks performed by the elements are presented for clarification.

    Sequence diagram

    Please keep in mind, that Autoware message callbacks and the update loop present on the sequence diagram are executed independently and concurrently. One thing they have in common are resources - the Vehicle (script).

    "},{"location":"Components/Vehicle/EgoVehicle/#com","title":"CoM","text":"

    CoM (Center of Mass) is an additional link that is defined to set the center of mass in the Rigidbody. The Vehicle (script) is responsible for its assignment. This measure should be defined in accordance with reality. Most often, the center of mass of the vehicle is located in its center, at the height of its wheel axis - as shown below.

    "},{"location":"Components/Vehicle/EgoVehicle/#colliders","title":"Colliders","text":"

    Colliders are used to ensure collision between objects. In EgoVehicle, the main Collider collider and colliders in Wheels GameObject for each wheel were added.

    Colliders object has the following content:

    "},{"location":"Components/Vehicle/EgoVehicle/#bodycollider","title":"BodyCollider","text":"

    Collider is a vehicle object responsible for ensuring collision with other objects. Additionally, it can be used to detect these collisions. The MeshCollider takes a Mesh of object and builds its Collider based on it. The Mesh for the Collider was also loaded from the *.fbx file similarly to the visual elements.

    "},{"location":"Components/Vehicle/EgoVehicle/#wheels-colliders","title":"Wheels Colliders","text":"

    WheelsColliders are an essential elements from the point of view of driving vehicles on the road. They are the only ones that have contact with the roads and it is important that they are properly configured. Each vehicle, apart from the visual elements related to the wheels, should also have 4 colliders - one for each wheel.

    Wheel (script) provides a reference to the collider and visual object for the particular wheel. Thanks to this, the Vehicle (script) has the ability to perform certain actions on each of the wheels, such as:

    • update the steering angle in WheelCollider,
    • update the visual part of the wheel depending on the speed and angle of the turn,
    • update the wheel contact information stored in the WheelHit object,
    • update the force exerted by the tire forward and sideways depending on the acceleration (including cancellation of skidding),
    • ensure setting the tire sleep (it is impossible to put Rigidbody to sleep, but putting all wheels to sleep allows to get closer to this effect).

    Wheel Collider Config (script) has been developed to prevent inspector entry for WheelCollider which ensures that friction is set to 0 and only wheel suspension and collisions are enabled.

    Wheel Collider Config

    For a better understanding of the meaning of WheelCollider we encourage you to read this manual.

    "},{"location":"Components/Vehicle/EgoVehicle/#rigidbody","title":"Rigidbody","text":"

    Rigidbody ensures that the object is controlled by the physics engine. The Mass of the vehicle should approximate its actual weight. In order for the vehicle to physically interact with other objects - react to collisions, Is Kinematic must be turned off. The Use Gravity should be turned on - to ensure the correct behavior of the body during movement. In addition, Interpolate should be turned on to ensure the physics engine's effects are smoothed out.

    "},{"location":"Components/Vehicle/EgoVehicle/#reflection-probe","title":"Reflection Probe","text":"

    Reflection Probe is added to EgoVehicle prefab to simulate realistic reflections in a scene. It is a component that captures and stores information about the surrounding environment and uses that information to generate accurate reflections on objects in real-time. The values in the component are set as default.

    HD Additional Reflection Data (script) is additional component used to store settings for HDRP's reflection probes and is added automatically.

    "},{"location":"Components/Vehicle/EgoVehicle/#urdf-and-sensors","title":"URDF and Sensors","text":"

    URDF (Unified Robot Description Format) is equivalent to the simplified URDF format used in ROS2. This format allows to define the positions of all sensors of the vehicle in relation to its local coordinate system. URDF is built using multiple GameObjects as children appropriately transformed with relation to its parent.

    A detailed description of the URDF structure and sensors added to prefab Lexus RX450h 2015 is available in this section.

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-script","title":"Vehicle (script)","text":"

    Vehicle (script) provides an inputs that allows the EgoVehicle to move. Script inputs provides the ability to set the acceleration of the vehicle and the steering angle of its wheels, taking into account the effects of suspension and gravity. It also provides an input to set the gear in the gearbox and to control the turn signals. Script inputs can be set by one of the following scripts: Vehicle Ros Input (script) or Vehicle Keyboard Input (script).

    The script performs several steps periodically:

    • checks whether the current inputs meet the set limits and adjusts them within them,
    • calculates the current linear velocity, angular velocity vector and local acceleration vector,
    • set the current steering angle in the script for each wheel and perform their updates,
    • if the current gear is PARKING and the vehicle is stopped (its speed and acceleration are below the set thresholds), it puts the vehicle (Rigidbody) and its wheels (Wheel (script)) to sleep,
    • if the vehicle has not been put to sleep, it sets the current acceleration to each with the appropriate sign depending on the DRIVE and REVERSE gear.
    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":"

    The script uses the CoM link reference to assign the center of mass of the vehicle to the Rigidbody. In addiction, Use inertia allows to define the inertia tensor for component Rigidbody - by default it is disabled.

    Physics Settings - allows to set values used to control vehicle physics:

    • Sleep Velocity Threshold - velocity threshold used to put vehicle to sleep,
    • Sleep Time Threshold - time threshold for which the vehicle must not exceed the Sleep Velocity Threshold, have contact with the ground and a set acceleration input equal to zero,
    • Skidding Cancel Rate - coefficient that determines the rate at which skidding is canceled, affects the anti-skid force of the wheels - the higher the value, the faster the cancellation of the skid.

    Axles Settings contains references to (Wheel (script)) scripts to control each wheel. Thanks to them, the Vehicle (script) is able to set their steering angle and accelerations.

    Input Settings - allows to set limits for values on script input:

    • Max Steer Angle Input - maximum value of acceleration set by the script (also negative),
    • Max Acceleration Input - maximum steering angle of the wheels set by the script (also negative).

    Inputs - are only used as a preview of the currently set values in the script input:

    "},{"location":"Components/Vehicle/EgoVehicle/#input-data","title":"Input Data","text":"Category Type Description AccelerationInput float Acceleration input (m/s^2). On the plane, output the force that will result in this acceleration. On a slope, it is affected by the slope resistance, so it does not match the input. SteerAngleInput float Vehicle steering input (degree). Negative steers left, positive right AutomaticShiftInput enumeration Vehicle gear shift input (AT).Values: PARKING, REVERSE, NEUTRAL, DRIVE. SignalInput enumeration Vehicle turn signal input.Values: NONE, LEFT, RIGHT, HAZARD."},{"location":"Components/Vehicle/EgoVehicle/#output-data","title":"Output data","text":"Category Type Description LocalAcceleration Vector3 Acceleration(m/s^2) in the local coordinate system of the vehicle Speed float Vehicle speed (m/s). SteerAngle float Vehicle steering angle (degree). Signal enumeration Vehicle turn signal. Velocity Vector3 Vehicle velocity (m/s) LocalVelocity Vector3 Vehicle local velocity (m/s) AngularVelocity Vector3 Vehicle angular velocity (rad/s)

    The acceleration or deceleration of the vehicle is determined by AutomaticShiftInput and AccelerationInput. The vehicle will not move in the opposite direction of the (DRIVE or REVERSE) input.

    Example

    Sample vehicle behaves:

    • Sample 1 - vehicle will accelerate with input values (gradient resistance is received).

      AutomaticShiftInput = DRIVE\nSpeed = Any value\nAccelerationInput > 0\n

    • Sample 2 - vehicle will decelerate (like a brake).

      AutomaticShiftInput = DRIVE\nSpeed > 0\nAccelerationInput < 0\n

    • Sample 3 - vehicle will continuously stop.

      AutomaticShiftInput = DRIVE\nSpeed <= 0\nAccelerationInput < 0\n
    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-ros-script","title":"Vehicle Ros (script)","text":"

    Vehicle Ros (script) is responsible for subscribing to messages that are vehicle control commands. The values read from the message are set on the inputs of the Vehicle (script) script.

    The concept for vehicle dynamics is suitable for Autoware's autoware_control_msgs/Control and autoware_vehicle_msgs/GearCommand messages interface usage. The script sets gear, steering angle of wheels and acceleration of the vehicle (read from the aforementioned messages) to the Vehicle (script) input. In the case of VehicleEmergencyStamped message it sets the absolute acceleration equal to 0. In addition, also through Vehicle (script), the appropriate lights are turned on and off depending on TurnIndicatorsCommand and HazardLightsCommand messages.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_1","title":"Elements configurable from the editor level","text":"
    • * Command Topic - topic on which suitable type of information is subscribed (default: listed in the table below)
    • QoS- Quality of service profile used in the publication (default assumed as \"system_default\": Reliable, TransientLocal, Keep last/1)
    • Vehicle - reference to a script in the vehicle object where the subscribed values are to be set (default: None)
    "},{"location":"Components/Vehicle/EgoVehicle/#subscribed-topics","title":"Subscribed Topics","text":"
    • QoS: Reliable, TransientLocal, KeepLast/1
    Category Topic Message type Frequency (Autoware dependent) TurnIndicatorsCommand /control/command/turn_indicators_cmd autoware_vehicle_msgs/TurnIndicatorsCommand 10 HazardLightsCommand /control/command/hazard_lights_cmd autoware_vehicle_msgs/HazardLightsCommand 10 AckermannControlCommand /control/command/control_cmd autoware_control_msgs/Control 60 GearCommand /control/command/gear_cmd autoware_vehicle_msgs/GearCommand 10 VehicleEmergencyStamped /control/command/emergency_cmd tier4_vehicle_msgs/msg/VehicleEmergencyStamped 60

    ROS2 Topics

    If you would like to know all the topics used in communication Autoware with AWSIM, we encourage you to familiarize yourself with this section

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-keyboard-script","title":"Vehicle Keyboard (script)","text":"

    Vehicle Keyboard (script) allows EgoVehicle to be controlled by the keyboard. Thanks to this, it is possible to switch on the appropriate gear of the gearbox, turn the lights on/off, set the acceleration and steering of the wheels. It's all set in the Vehicle (script) of the object assigned in the Vehicle field. The table below shows the available control options.

    Button Option d Switch to move forward (drive gear) r Switch to move backwards (reverse gear) n Switch to neutral p Switch to parking gear UP ARROW Forward acceleration DOWN ARROW Reverse acceleration (decelerate) LEFT/RIGHT ARROW Turning 1 Turn left blinker on (right off) 2 Turn right blinker on (left off) 3 Turn on hazard lights 4 Turn off blinker or hazard lights

    WASD

    Controlling the movement of the vehicle with WASD as the equivalent of arrow keys is acceptable, but remember that the d button engages the drive gear.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_2","title":"Elements configurable from the editor level","text":"
    • Max Acceleration- maximum value of acceleration set by the script (also negative)
    • Max Steer Angle - maximum steering angle of the wheels set by the script (also negative)

    Value limits

    Max Acceleration and Max Steer Angle values greater than those set in the Vehicle (script) are limited by the script itself - they will not be exceeded.

    "},{"location":"Components/Vehicle/EgoVehicle/#vehicle-visual-effect-script","title":"Vehicle Visual Effect (script)","text":"

    This part of the settings is related to the configuration of the emission of materials when a specific lighting is activated. There are 4 types of lights: Brake, Left Turn Signal, Right Turn Signal and Reverse. Each of the lights has its visual equivalent in the form of a Mesh. In the case of EgoVehicle, each light type has its own GameObject which contains the Mesh assigned.

    For each type of light, the appropriate Material Index (equivalent of element index in mesh) and Lighting Color are assigned - yellow for Turn Signals, red for Break and white for Reverse.

    Lighting Intensity values are also configured - the greater the value, the more light will be emitted. This value is related to Lighting Exposure Weight parameter that is a exposure weight - the lower the value, the more light is emitted.

    All types of lighting are switched on and off depending on the values obtained from the Vehicle (script) of the vehicle, which is assigned in the Vehicle field.

    "},{"location":"Components/Vehicle/EgoVehicle/#elements-configurable-from-the-editor-level_3","title":"Elements configurable from the editor level","text":"
    • Turn Signal Timer Interval Sec - time interval for flashing lights - value \\(0.5\\) means that the light will be on for \\(0.5s\\), then it will be turned off for \\(0.5s\\) and turned on again. (default: 0.5)
    "},{"location":"Components/Vehicle/FollowCamera/","title":"FollowCamera","text":""},{"location":"Components/Vehicle/FollowCamera/#introduction","title":"Introduction","text":"

    The FollowCamera component is designed to track a specified target object within the scene. It is attached to the main camera and maintains a defined distance and height from the target. Additionally, it offers the flexibility of custom rotation around the target as an optional feature.

    "},{"location":"Components/Vehicle/FollowCamera/#elements-configurable-from-the-editor-level","title":"Elements configurable from the editor level","text":""},{"location":"Components/Vehicle/FollowCamera/#required-member","title":"Required member","text":"
    • Target - the transform component of the tracked object
    "},{"location":"Components/Vehicle/FollowCamera/#base-setttings","title":"Base Setttings","text":"
    • Distance - base distance between the camera and the target object
    • Offset - lateral offset of the camera position
    • Height - base height of the camera above the target object
    • HeightMultiplier - camera height multiplier
    "},{"location":"Components/Vehicle/FollowCamera/#optional-movement-setttings","title":"Optional Movement Setttings","text":"
    • RotateAroundModeToggle - toggle key between rotate around mode and default follow mode
    • RotateAroundSensitivity - mouse movement sensitivity for camera rotation around the target
    • HeightAdjustmentSensitivity - mouse movement sensitivity for camera height adjustment
    • ZoomSensitivity - mouse scroll wheel sensitivity for camera zoom
    • InvertHorzAxis - invert horizontal mouse movement
    • InvertVertAxis - invert vertical mouse movement
    • InvertScrollWheel - invert mouse scroll wheel
    • MaxHeight - maximum value of camera height
    • MinDistance - minimum value of camera distance to target object
    • MaxDistance - maximum value of camera distance to target object
    "},{"location":"Components/Vehicle/FollowCamera/#rotate-around-mode","title":"Rotate Around Mode","text":"

    Camera rotation around the target can be activated by pressing the RotateAroundModeToggle key (default 'C' key). In this mode, the user can manually adjust the camera view at run-time using the mouse. To deactivate the Rotate Around mode, press the RotateAroundModeToggle key once more.

    In the Rotate Around Mode camera view can be controlled as follows:

    • hold left shift + mouse movement: to adjust the camera position,
    • hold left shift + mouse scroll wheel: to zoom in or out of the camera view,
    • left shift + left arrow: to set left camera view,
    • left shift + right arrow: to set right camera view,
    • left shift + up arrow: to set front camera view,
    • left shift + down arrow: to set back camera view.
    "},{"location":"Components/Vehicle/FollowCamera/#optional","title":"Optional","text":"

    An optional prefab featuring a UI panel, located at Assets/Prefabs/UI/MainCameraView.prefab, can be used to showcase a user guide. To integrate this prefab into the scene, drag and drop it beneath the Canvas object. This prefab displays instructions on how to adjust the camera view whenever the Rotate Around Mode is activated.

    "},{"location":"Components/Vehicle/URDFAndSensors/","title":"URDF And Sensors","text":""},{"location":"Components/Vehicle/URDFAndSensors/#urdf-and-sensors","title":"URDF and Sensors","text":"

    This section describes the placement of sensors in EgoVehicle on the example of a Lexus RX450h 2015 Sample Sensor prefab.

    URDF (Unified Robot Description Format) is equivalent to the simplified URDF format used in ROS2. This format allows to define the positions of all sensors of the vehicle in relation to its main parent prefab coordinate system.

    URDF is added directly to the main parent of the prefab and there are no transforms between these objects. It is built using multiple GameObjects as children appropriately transformed with relation to its parent.

    The transforms in the URDF object are defined using the data from the sensor kit documentation used in the vehicle. Such data can be obtained from sensor kit packages for Autoware, for example: awsim_sensor_kit_launch - it is used in the AWSIM compatible version of Autoware. This package contains a description of transforms between coordinate systems (frames) in the form of *.yaml files: sensors_calibration and sensor_kit_calibration.

    In the first file, the transform of the sensor kit frame (sensor_kit_base_link) relative to the local vehicle frame (base_link) is defined. In Unity, this transform is defined in the object Sensor Kit. While the second file contains a definition of the transformations of all sensors with respect to the sensor kit - they are described in the Sensor Kit subsections.

    Transformations

    Please note that the transformation Objects are intended to be a direct reflection of frames existing in ROS2. All frame Objects are defined as children of base_link and consist of nothing but a transformation - analogical to the one present in ROS2 (keep in mind the coordinate system conversion). The sensor Objects are added to the transformation Object with no transformation of their own.

    Coordinate system conventions

    Unity uses a left-handed convention for its coordinate system, while the ROS2 uses a right-handed convention. For this reason, you should remember to perform conversions to get the correct transforms.

    "},{"location":"Components/Vehicle/URDFAndSensors/#base-link","title":"Base Link","text":"

    Base Link (frame named base_link) is the formalized local coordinate system in URDF. All sensors that publish data specified in some frame present in Autoware are defined in relation to base_link. It is a standard practice in ROS, that base_link is a parent transformation of the whole robot and all robot parts are defined in some relation to the base_link.

    If any device publishes data in the base_link frame - it is added as a direct child, with no additional transformation intermediate Object (PoseSensor is an example). However, if this device has its own frame, it is added as a child to its frame Object - which provides an additional transformation. The final transformation can consist of many intermediate transformation Objects. The frame Objects are added to the base_link (GnssSensor and its parent gnss_link are an example).

    "},{"location":"Components/Vehicle/URDFAndSensors/#sensor-kit","title":"Sensor Kit","text":"

    Sensor Kit (frame named sensor_kit_base_link) is a set of objects that consists of all simulated sensors that are physically present in an autonomous vehicle and have their own coordinate system (frame). This set of sensors has its own frame sensor_kit_base_link that is relative to the base_link.

    In the Lexus RX450h 2015 Sample Sensor prefab, it is added to the base_link GameObject with an appropriately defined transformation. It acts as an intermediate frame GameObject. Sensor Kit is located on the top of the vehicle, so it is significantly shifted about the Oy and Oz axes. Sensors can be defined directly in this Object (VelodyneVLP16 is an example), or have their own transformation Object added on top of the sensor_kit_base_link (like GnssSensor mentioned in the base_link section).

    The sensors described in this subsection are defined in relation to the sensor_kit_base_link frame.

    "},{"location":"Components/Vehicle/URDFAndSensors/#lidars","title":"LiDARs","text":"

    LidarSensor is the component that simulates the LiDAR (Light Detection and Ranging) sensor. The LiDARs mounted on the top of autonomous vehicles are primarily used to scan the environment for localization in space and for detection and identification of obstacles. LiDARs placed on the left and right sides of the vehicle are mainly used to monitor the traffic lane and detect vehicles moving in adjacent lanes. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one VelodyneVLP16 prefab sensor configured on the top of the vehicle, mainly used for location in space, but also for object recognition. Since the top LiDAR publishes data directly in the sensor_kit_base_link frame, the prefab is added directly to it - there is no transform. The other two remaining LiDARs are defined, but disabled - they do not provide data from space (but you can enable them!).

    "},{"location":"Components/Vehicle/URDFAndSensors/#top","title":"Top","text":""},{"location":"Components/Vehicle/URDFAndSensors/#left-disabled","title":"Left - disabled","text":""},{"location":"Components/Vehicle/URDFAndSensors/#right-disabled","title":"Right - disabled","text":""},{"location":"Components/Vehicle/URDFAndSensors/#imu","title":"IMU","text":"

    IMUSensor is a component that simulates an IMU (Inertial Measurement Unit) sensor. It measures acceleration and angular velocity of the EgoVehicle. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor has one such sensor located on the top of the vehicle. It is added to an Object tamagawa/imu_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link. This transformation has no transition, but only rotation around the Oy and Oz axes. The transform is defined in such a way that its axis Oy points downwards - in accordance with the gravity vector.

    "},{"location":"Components/Vehicle/URDFAndSensors/#gnss","title":"GNSS","text":"

    GnssSensor is a component which simulates the position of vehicle computed by the Global Navigation Satellite. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one such sensor located on top of the vehicle. It is added to an Object gnss_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link. The frame is slightly moved back along the Oy and Oz axes.

    "},{"location":"Components/Vehicle/URDFAndSensors/#camera","title":"Camera","text":"

    CameraSensor is a component that simulates an RGB camera. Autonomous vehicles can be equipped with many cameras used for various purposes. A detailed description of this sensor is available in this section.

    Lexus RX450h 2015 Sample Sensor prefab has one camera, positioned on top of the vehicle in such a way that the cameras field of view provides an image including traffic lights - the status of which must be recognized by Autoware. It is added to an Object traffic_light_left_camera/camera_link that matches its frame_id and contains its transform with respect to sensor_kit_base_link.

    "},{"location":"Components/Vehicle/URDFAndSensors/#pose","title":"Pose","text":"

    PoseSensor is a component which provides access to the current position and rotation of the EgoVehicle - is added as a ground truth.

    The position and orientation of EgoVehicle is defined as the position of the frame base_link in the global frame, so this Object is added directly as its child without a transform.

    "},{"location":"Components/Vehicle/URDFAndSensors/#vehiclesensor","title":"VehicleSensor","text":"

    VehicleStatusSensor is a component that is designed to aggregate information about the current state of the EgoVehicle, such as the active control mode, vehicle speed, steering of its wheels, or turn signal status. A detailed description of this sensor is available in this section.

    This Object is not strictly related to any frame, however, it is assumed as a sensor, therefore it is added to the URDF.

    "},{"location":"DeveloperGuide/Contact/","title":"Contact","text":""},{"location":"DeveloperGuide/Contact/#contact","title":"Contact","text":"

    English/\u65e5\u672c\u8a9e OK

    e-mail : takatoki.makino@tier4.jp

    twitter : https://twitter.com/mackierx111

    "},{"location":"DeveloperGuide/Documentation/","title":"Documentation","text":""},{"location":"DeveloperGuide/Documentation/#documentation","title":"Documentation","text":"

    This document uses Material for MkDocs.

    "},{"location":"DeveloperGuide/Documentation/#local-hosting","title":"Local hosting","text":"

    1 Install Material for MkDocs. 

    $ pip install mkdocs-material\n
    2 Hosting on localhost. 
    $ cd AWSIM\n$ mkdocs serve\nINFO     -  Building documentation...\nINFO     -  Cleaning site directory\nINFO     -  Documentation built in 0.16 seconds\nINFO     -  [03:13:22] Watching paths for changes: 'docs', 'mkdocs.yml'\nINFO     -  [03:13:22] Serving on http://127.0.0.1:8000/\n

    3 Access http://127.0.0.1:8000/ with a web browser.

    For further reference see Material for MkDocs - Getting started.

    "},{"location":"DeveloperGuide/Documentation/#mkdocs-files","title":"MkDocs files","text":"

    Use the following /docs directory and mkdocs.yml for new documentation files. 

    AWSIM\n\u251c\u2500 docs/                // markdown and image file for each document.\n\u2514\u2500 mkdocs.yml           // mkdocs config.\n
    Create one directory per document. For example, the directory structure of this \"Documentation\" page might look like this. 
    AWSIM\n\u2514\u2500 docs/                            // Root of all documents\n    \u2514\u2500 DeveloperGuide               // Category\n        \u2514\u2500 Documentation            // Root of each document\n            \u251c\u2500 index.md             // Markdown file\n            \u2514\u2500 image_0.png          // Images used in markdown file\n
    "},{"location":"DeveloperGuide/Documentation/#deploy-hosting","title":"Deploy & Hosting","text":"

    When docs are pushed to the main branch, they are deployed to GitHub Pages using GitHub Actions. See also Material for MkDocs - Publishing your site

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/","title":"Graphy Asset Setup","text":""},{"location":"DeveloperGuide/EditorSetup/Graphy/#graphy-asset-setup","title":"Graphy Asset Setup","text":""},{"location":"DeveloperGuide/EditorSetup/Graphy/#add-graphy-from-asset-store","title":"Add Graphy from Asset Store","text":"

    1) Go to Unity Asset Store and add Graphy to personal assets.

    Graphy Asset Store link:

    • https://assetstore.unity.com/packages/tools/gui/graphy-ultimate-fps-counter-stats-monitor-debugger-105778
    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#add-graphy-to-the-unity-editor","title":"Add Graphy to the Unity Editor","text":"

    1) Open up the Unity Editor. - Open up a temporary new scene by File -> New Scene -> Empty(Built-in) -> Create - This is due to a bug with Unity crashing on certain Linux configurations. - Once the package is imported, you can open up the desired scene. 2) Go to the Window menu and select Package Manager. 3) Make sure the My Assets tab is selected from the top left of the Package Manager window. 4) Find & select the Graphy from the list and click Download or Import from the bottom left of the Package Manager window. 5) There will be a popup window showing contents of the package. Click Import to add Graphy to the project.

    After the import is complete, you should be able to see Graphy prefab in the Hierarchy window of the AutowareSimulation scene. If it's missing you can add it to scene by following steps below.

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#integrating-graphy-into-custom-scenes","title":"Integrating Graphy into custom scenes","text":"

    Graphy is pre-integrated within the AutowareSimulation scene. To incorporate Graphy into your own custom scenes, please adhere to the following steps:

    1) Go to the Assets folder in the Project window. 2) Open Graphy > Prefab folder. 3) Drag the Graphy prefab into the scene. 4) You can customize your Graphy by selecting the Graphy prefab in the scene and changing the settings in the inspector window.

    "},{"location":"DeveloperGuide/EditorSetup/Graphy/#useful-links","title":"Useful links:","text":"

    Unity Package manager:

    • https://docs.unity3d.com/Manual/upm-ui.html

    Graphy Github page:

    • https://github.com/Tayx94/graphy

    Graphy Documentation:

    • https://github.com/Tayx94/graphy/blob/master/Readme!%20-%20Graphy%20-%20Documentation.pdf
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/","title":"Rider Configuration","text":""},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#jetbrains-rider-setup-with-unity","title":"JetBrains Rider setup with Unity","text":""},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#install-jetbrains-rider","title":"Install JetBrains Rider:","text":"

    Follow the steps in:

    • https://www.jetbrains.com/help/rider/Installation_guide.html#snap
    sudo snap install rider --classic\n
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#install-net-sdk","title":"Install .NET SDK:","text":"

    Follow the steps in:

    • https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#register-the-microsoft-package-repository
    # Get Ubuntu version\ndeclare repo_version=$(if command -v lsb_release &> /dev/null; then lsb_release -r -s; else grep -oP '(?<=^VERSION_ID=).+' /etc/os-release | tr -d '\"'; fi)\n\n# Download Microsoft signing key and repository\nwget https://packages.microsoft.com/config/ubuntu/$repo_version/packages-microsoft-prod.deb -O packages-microsoft-prod.deb\n\n# Install Microsoft signing key and repository\nsudo dpkg -i packages-microsoft-prod.deb\n\n# Clean up\nrm packages-microsoft-prod.deb\n\n# Update packages\nsudo apt update\nsudo apt install dotnet-sdk-8.0\n
    "},{"location":"DeveloperGuide/EditorSetup/JetBrainsRider/#connect-rider-to-unity-editor","title":"Connect Rider to Unity Editor:","text":"

    Follow the steps in:

    • https://www.jetbrains.com/help/rider/Unity.html#8f092cb7_9
    1) Open an existing Unity project in the Unity Editor.\n\n2) Select Edit > Preferences (Unity > Settings on macOS) and open the External Tools page.\n\n3) In the External Script Editor, select a \"Rider\" installation.\n\n4) In the Preferences window, click \"Regenerate project files\" under the External Tools section.\n\n5) While still in the Unity Editor, right-click anywhere in the Project view and select Open C# Project.\n\n6) Rider will start automatically and open the solution related to this Unity project. Once the solution is loaded, Rider and the Unity Editor become connected. The Unity icon on the toolbar shows the current connection status:\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/","title":"VSCode Configuration","text":""},{"location":"DeveloperGuide/EditorSetup/VSCode/#visual-studio-code-setup-with-unity","title":"Visual Studio Code setup with Unity","text":""},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-visual-studio-code","title":"Install Visual Studio Code","text":"

    Follow the steps in: - https://code.visualstudio.com/docs/setup/linux

    # Install the keys and repository\nsudo apt-get install wget gpg\nwget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg\nsudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg\nsudo sh -c 'echo \"deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main\" > /etc/apt/sources.list.d/vscode.list'\nrm -f packages.microsoft.gpg\n\n# Then update the package cache and install the package using:\nsudo apt install apt-transport-https\nsudo apt update\nsudo apt install code\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-the-dotnet-sdk","title":"Install the Dotnet SDK","text":"

    Follow the steps in: - https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#register-the-microsoft-package-repository

    # Get Ubuntu version\ndeclare repo_version=$(if command -v lsb_release &> /dev/null; then lsb_release -r -s; else grep -oP '(?<=^VERSION_ID=).+' /etc/os-release | tr -d '\"'; fi)\n\n# Download Microsoft signing key and repository\nwget https://packages.microsoft.com/config/ubuntu/$repo_version/packages-microsoft-prod.deb -O packages-microsoft-prod.deb\n\n# Install Microsoft signing key and repository\nsudo dpkg -i packages-microsoft-prod.deb\n\n# Clean up\nrm packages-microsoft-prod.deb\n\n# Update packages\nsudo apt update\n\nsudo apt install dotnet-sdk-8.0\n
    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#install-the-extensions","title":"Install the extensions","text":"

    Follow the steps in: - https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit - https://marketplace.visualstudio.com/items?itemName=VisualStudioToolsForUnity.vstuc - https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp

    Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter. - ext install ms-dotnettools.csdevkit Repeat for: - ext install VisualStudioToolsForUnity.vstuc - ext install ms-dotnettools.csharp

    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#configure-the-unity","title":"Configure the Unity","text":"
    • Open up the Unity Editor
    • Edit -> Preferences -> External Tools -> External Script Editor
    • Select Visual Studio Code
    • If it's not there, click Browse and navigate and select /usr/bin/code

    It should all be configured now. You can either open up a script by double clicking in the Project window in Unity or by opening up the project in VS Code: - Assets -> Open C# Project

    Syntax highlighting and CTRL-click navigation should work out of the box.

    For more advanced features such as debugging, check the Unity Development with VS Code Documentation.

    "},{"location":"DeveloperGuide/EditorSetup/VSCode/#additional-notes","title":"Additional notes","text":"

    In the AWSIM project, the package Visual Studio Editor is already installed to satisfy the requirement from the Unity for Visual Studio Code extension.

    "},{"location":"DeveloperGuide/HowToContribute/","title":"How to Contribute","text":""},{"location":"DeveloperGuide/HowToContribute/#how-to-contribute","title":"How to Contribute","text":"

    Everyone is welcome!

    "},{"location":"DeveloperGuide/HowToContribute/#how-can-i-get-help","title":"How can I get help?","text":"

    Do not open issues for general support questions as we want to keep GitHub issues for confirmed bug reports. Instead, open a discussion in the Q&A category. The trouble shooting page at AWSIM and at Autoware will be also helpful.

    "},{"location":"DeveloperGuide/HowToContribute/#issue","title":"Issue","text":"

    Before you post an issue, please search Issues and Discussions Q&A catecory to check if it is not a known issue.

    This page is helpful how to create an issue from a repository.

    "},{"location":"DeveloperGuide/HowToContribute/#bug-report","title":"Bug report","text":"

    If you find a new bug, please create an issue here

    "},{"location":"DeveloperGuide/HowToContribute/#feature-request","title":"Feature request","text":"

    If you propose a new feature or have an idea, please create an issue here

    "},{"location":"DeveloperGuide/HowToContribute/#task","title":"Task","text":"

    If you have plan to contribute AWSIM Labs, please create an issue here.

    "},{"location":"DeveloperGuide/HowToContribute/#question","title":"Question","text":"
    • If you need a general support, please open a discussion in the Q&A category.
    • You can contribute by Answering questions and supporting other contributors
    "},{"location":"DeveloperGuide/HowToContribute/#pull-requests","title":"Pull requests","text":"

    If you have an idea to improve the simulation, you can submit a pull request. The following process should be followed:

    1. Create a derived branch (feature/***) from the main branch.
    2. Create a pull request to the main branch.

    Please keep the following in mind, while developing new features:

    • Git branching guidelines
    • C# coding convention.
    "},{"location":"DeveloperGuide/License/","title":"License","text":""},{"location":"DeveloperGuide/License/#awsim-licenses","title":"AWSIM Licenses","text":"

    AWSIM License applies to tier4/AWSIM repositories and all content contained in the Releases.

    • AWSIM specific code is distributed under Apache2.0 License. The following extensions are included (*.cs *.compute *.xml)
    • AWSIM specific assets are distributed under CC BY-NC License. The following extensions are included (*.fbx *.pcd *.osm *.png *.anim *.unitypackage *.x86_64)
    "},{"location":"DeveloperGuide/License/#apache20-license","title":"Apache2.0 License","text":"
    **********************************************************************************\n\n                                 Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright 2022 TIER IV, Inc.\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n
    "},{"location":"DeveloperGuide/License/#cc-by-nc-license","title":"CC BY-NC License","text":"
    **********************************************************************************\n\nAttribution-NonCommercial 4.0 International\n\n=======================================================================\n\nCreative Commons Corporation (\"Creative Commons\") is not a law firm and\ndoes not provide legal services or legal advice. Distribution of\nCreative Commons public licenses does not create a lawyer-client or\nother relationship. Creative Commons makes its licenses and related\ninformation available on an \"as-is\" basis. Creative Commons gives no\nwarranties regarding its licenses, any material licensed under their\nterms and conditions, or any related information. Creative Commons\ndisclaims all liability for damages resulting from their use to the\nfullest extent possible.\n\nUsing Creative Commons Public Licenses\n\nCreative Commons public licenses provide a standard set of terms and\nconditions that creators and other rights holders may use to share\noriginal works of authorship and other material subject to copyright\nand certain other rights specified in the public license below. The\nfollowing considerations are for informational purposes only, are not\nexhaustive, and do not form part of our licenses.\n\n     Considerations for licensors: Our public licenses are\n     intended for use by those authorized to give the public\n     permission to use material in ways otherwise restricted by\n     copyright and certain other rights. Our licenses are\n     irrevocable. Licensors should read and understand the terms\n     and conditions of the license they choose before applying it.\n     Licensors should also secure all rights necessary before\n     applying our licenses so that the public can reuse the\n     material as expected. Licensors should clearly mark any\n     material not subject to the license. This includes other CC-\n     licensed material, or material used under an exception or\n     limitation to copyright. More considerations for licensors:\n    wiki.creativecommons.org/Considerations_for_licensors\n\n     Considerations for the public: By using one of our public\n     licenses, a licensor grants the public permission to use the\n     licensed material under specified terms and conditions. If\n     the licensor's permission is not necessary for any reason--for\n     example, because of any applicable exception or limitation to\n     copyright--then that use is not regulated by the license. Our\n     licenses grant only permissions under copyright and certain\n     other rights that a licensor has authority to grant. Use of\n     the licensed material may still be restricted for other\n     reasons, including because others have copyright or other\n     rights in the material. A licensor may make special requests,\n     such as asking that all changes be marked or described.\n     Although not required by our licenses, you are encouraged to\n     respect those requests where reasonable. More considerations\n     for the public:\n    wiki.creativecommons.org/Considerations_for_licensees\n\n=======================================================================\n\nCreative Commons Attribution-NonCommercial 4.0 International Public\nLicense\n\nBy exercising the Licensed Rights (defined below), You accept and agree\nto be bound by the terms and conditions of this Creative Commons\nAttribution-NonCommercial 4.0 International Public License (\"Public\nLicense\"). To the extent this Public License may be interpreted as a\ncontract, You are granted the Licensed Rights in consideration of Your\nacceptance of these terms and conditions, and the Licensor grants You\nsuch rights in consideration of benefits the Licensor receives from\nmaking the Licensed Material available under these terms and\nconditions.\n\n\nSection 1 -- Definitions.\n\n  a. Adapted Material means material subject to Copyright and Similar\n     Rights that is derived from or based upon the Licensed Material\n     and in which the Licensed Material is translated, altered,\n     arranged, transformed, or otherwise modified in a manner requiring\n     permission under the Copyright and Similar Rights held by the\n     Licensor. For purposes of this Public License, where the Licensed\n     Material is a musical work, performance, or sound recording,\n     Adapted Material is always produced where the Licensed Material is\n     synched in timed relation with a moving image.\n\n  b. Adapter's License means the license You apply to Your Copyright\n     and Similar Rights in Your contributions to Adapted Material in\n     accordance with the terms and conditions of this Public License.\n\n  c. Copyright and Similar Rights means copyright and/or similar rights\n     closely related to copyright including, without limitation,\n     performance, broadcast, sound recording, and Sui Generis Database\n     Rights, without regard to how the rights are labeled or\n     categorized. For purposes of this Public License, the rights\n     specified in Section 2(b)(1)-(2) are not Copyright and Similar\n     Rights.\n  d. Effective Technological Measures means those measures that, in the\n     absence of proper authority, may not be circumvented under laws\n     fulfilling obligations under Article 11 of the WIPO Copyright\n     Treaty adopted on December 20, 1996, and/or similar international\n     agreements.\n\n  e. Exceptions and Limitations means fair use, fair dealing, and/or\n     any other exception or limitation to Copyright and Similar Rights\n     that applies to Your use of the Licensed Material.\n\n  f. Licensed Material means the artistic or literary work, database,\n     or other material to which the Licensor applied this Public\n     License.\n\n  g. Licensed Rights means the rights granted to You subject to the\n     terms and conditions of this Public License, which are limited to\n     all Copyright and Similar Rights that apply to Your use of the\n     Licensed Material and that the Licensor has authority to license.\n\n  h. Licensor means the individual(s) or entity(ies) granting rights\n     under this Public License.\n\n  i. NonCommercial means not primarily intended for or directed towards\n     commercial advantage or monetary compensation. For purposes of\n     this Public License, the exchange of the Licensed Material for\n     other material subject to Copyright and Similar Rights by digital\n     file-sharing or similar means is NonCommercial provided there is\n     no payment of monetary compensation in connection with the\n     exchange.\n\n  j. Share means to provide material to the public by any means or\n     process that requires permission under the Licensed Rights, such\n     as reproduction, public display, public performance, distribution,\n     dissemination, communication, or importation, and to make material\n     available to the public including in ways that members of the\n     public may access the material from a place and at a time\n     individually chosen by them.\n\n  k. Sui Generis Database Rights means rights other than copyright\n     resulting from Directive 96/9/EC of the European Parliament and of\n     the Council of 11 March 1996 on the legal protection of databases,\n     as amended and/or succeeded, as well as other essentially\n     equivalent rights anywhere in the world.\n\n  l. You means the individual or entity exercising the Licensed Rights\n     under this Public License. Your has a corresponding meaning.\n\n\nSection 2 -- Scope.\n\n  a. License grant.\n\n       1. Subject to the terms and conditions of this Public License,\n          the Licensor hereby grants You a worldwide, royalty-free,\n          non-sublicensable, non-exclusive, irrevocable license to\n          exercise the Licensed Rights in the Licensed Material to:\n\n            a. reproduce and Share the Licensed Material, in whole or\n               in part, for NonCommercial purposes only; and\n\n            b. produce, reproduce, and Share Adapted Material for\n               NonCommercial purposes only.\n\n       2. Exceptions and Limitations. For the avoidance of doubt, where\n          Exceptions and Limitations apply to Your use, this Public\n          License does not apply, and You do not need to comply with\n          its terms and conditions.\n\n       3. Term. The term of this Public License is specified in Section\n          6(a).\n\n       4. Media and formats; technical modifications allowed. The\n          Licensor authorizes You to exercise the Licensed Rights in\n          all media and formats whether now known or hereafter created,\n          and to make technical modifications necessary to do so. The\n          Licensor waives and/or agrees not to assert any right or\n          authority to forbid You from making technical modifications\n          necessary to exercise the Licensed Rights, including\n          technical modifications necessary to circumvent Effective\n          Technological Measures. For purposes of this Public License,\n          simply making modifications authorized by this Section 2(a)\n          (4) never produces Adapted Material.\n\n       5. Downstream recipients.\n\n            a. Offer from the Licensor -- Licensed Material. Every\n               recipient of the Licensed Material automatically\n               receives an offer from the Licensor to exercise the\n               Licensed Rights under the terms and conditions of this\n               Public License.\n\n            b. No downstream restrictions. You may not offer or impose\n               any additional or different terms or conditions on, or\n               apply any Effective Technological Measures to, the\n               Licensed Material if doing so restricts exercise of the\n               Licensed Rights by any recipient of the Licensed\n               Material.\n\n       6. No endorsement. Nothing in this Public License constitutes or\n          may be construed as permission to assert or imply that You\n          are, or that Your use of the Licensed Material is, connected\n          with, or sponsored, endorsed, or granted official status by,\n          the Licensor or others designated to receive attribution as\n          provided in Section 3(a)(1)(A)(i).\n\n  b. Other rights.\n\n       1. Moral rights, such as the right of integrity, are not\n          licensed under this Public License, nor are publicity,\n          privacy, and/or other similar personality rights; however, to\n          the extent possible, the Licensor waives and/or agrees not to\n          assert any such rights held by the Licensor to the limited\n          extent necessary to allow You to exercise the Licensed\n          Rights, but not otherwise.\n\n       2. Patent and trademark rights are not licensed under this\n          Public License.\n\n       3. To the extent possible, the Licensor waives any right to\n          collect royalties from You for the exercise of the Licensed\n          Rights, whether directly or through a collecting society\n          under any voluntary or waivable statutory or compulsory\n          licensing scheme. In all other cases the Licensor expressly\n          reserves any right to collect such royalties, including when\n          the Licensed Material is used other than for NonCommercial\n          purposes.\n\n\nSection 3 -- License Conditions.\n\nYour exercise of the Licensed Rights is expressly made subject to the\nfollowing conditions.\n\n  a. Attribution.\n\n       1. If You Share the Licensed Material (including in modified\n          form), You must:\n\n            a. retain the following if it is supplied by the Licensor\n               with the Licensed Material:\n\n                 i. identification of the creator(s) of the Licensed\n                    Material and any others designated to receive\n                    attribution, in any reasonable manner requested by\n                    the Licensor (including by pseudonym if\n                    designated);\n\n                ii. a copyright notice;\n\n               iii. a notice that refers to this Public License;\n\n                iv. a notice that refers to the disclaimer of\n                    warranties;\n\n                 v. a URI or hyperlink to the Licensed Material to the\n                    extent reasonably practicable;\n\n            b. indicate if You modified the Licensed Material and\n               retain an indication of any previous modifications; and\n\n            c. indicate the Licensed Material is licensed under this\n               Public License, and include the text of, or the URI or\n               hyperlink to, this Public License.\n\n       2. You may satisfy the conditions in Section 3(a)(1) in any\n          reasonable manner based on the medium, means, and context in\n          which You Share the Licensed Material. For example, it may be\n          reasonable to satisfy the conditions by providing a URI or\n          hyperlink to a resource that includes the required\n          information.\n\n       3. If requested by the Licensor, You must remove any of the\n          information required by Section 3(a)(1)(A) to the extent\n          reasonably practicable.\n\n       4. If You Share Adapted Material You produce, the Adapter's\n          License You apply must not prevent recipients of the Adapted\n          Material from complying with this Public License.\n\n\nSection 4 -- Sui Generis Database Rights.\n\nWhere the Licensed Rights include Sui Generis Database Rights that\napply to Your use of the Licensed Material:\n\n  a. for the avoidance of doubt, Section 2(a)(1) grants You the right\n     to extract, reuse, reproduce, and Share all or a substantial\n     portion of the contents of the database for NonCommercial purposes\n     only;\n\n  b. if You include all or a substantial portion of the database\n     contents in a database in which You have Sui Generis Database\n     Rights, then the database in which You have Sui Generis Database\n     Rights (but not its individual contents) is Adapted Material; and\n\n  c. You must comply with the conditions in Section 3(a) if You Share\n     all or a substantial portion of the contents of the database.\n\nFor the avoidance of doubt, this Section 4 supplements and does not\nreplace Your obligations under this Public License where the Licensed\nRights include other Copyright and Similar Rights.\n\n\nSection 5 -- Disclaimer of Warranties and Limitation of Liability.\n\n  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE\n     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS\n     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF\n     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,\n     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,\n     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR\n     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,\n     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT\n     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT\n     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.\n\n  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE\n     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,\n     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,\n     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,\n     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR\n     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN\n     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR\n     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR\n     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.\n\n  c. The disclaimer of warranties and limitation of liability provided\n     above shall be interpreted in a manner that, to the extent\n     possible, most closely approximates an absolute disclaimer and\n     waiver of all liability.\n\n\nSection 6 -- Term and Termination.\n\n  a. This Public License applies for the term of the Copyright and\n     Similar Rights licensed here. However, if You fail to comply with\n     this Public License, then Your rights under this Public License\n     terminate automatically.\n\n  b. Where Your right to use the Licensed Material has terminated under\n     Section 6(a), it reinstates:\n\n       1. automatically as of the date the violation is cured, provided\n          it is cured within 30 days of Your discovery of the\n          violation; or\n\n       2. upon express reinstatement by the Licensor.\n\n     For the avoidance of doubt, this Section 6(b) does not affect any\n     right the Licensor may have to seek remedies for Your violations\n     of this Public License.\n\n  c. For the avoidance of doubt, the Licensor may also offer the\n     Licensed Material under separate terms or conditions or stop\n     distributing the Licensed Material at any time; however, doing so\n     will not terminate this Public License.\n\n  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public\n     License.\n\n\nSection 7 -- Other Terms and Conditions.\n\n  a. The Licensor shall not be bound by any additional or different\n     terms or conditions communicated by You unless expressly agreed.\n\n  b. Any arrangements, understandings, or agreements regarding the\n     Licensed Material not stated herein are separate from and\n     independent of the terms and conditions of this Public License.\n\n\nSection 8 -- Interpretation.\n\n  a. For the avoidance of doubt, this Public License does not, and\n     shall not be interpreted to, reduce, limit, restrict, or impose\n     conditions on any use of the Licensed Material that could lawfully\n     be made without permission under this Public License.\n\n  b. To the extent possible, if any provision of this Public License is\n     deemed unenforceable, it shall be automatically reformed to the\n     minimum extent necessary to make it enforceable. If the provision\n     cannot be reformed, it shall be severed from this Public License\n     without affecting the enforceability of the remaining terms and\n     conditions.\n\n  c. No term or condition of this Public License will be waived and no\n     failure to comply consented to unless expressly agreed to by the\n     Licensor.\n\n  d. Nothing in this Public License constitutes or may be interpreted\n     as a limitation upon, or waiver of, any privileges and immunities\n     that apply to the Licensor or You, including from the legal\n     processes of any jurisdiction or authority.\n\n=======================================================================\n\nCreative Commons is not a party to its public\nlicenses. Notwithstanding, Creative Commons may elect to apply one of\nits public licenses to material it publishes and in those instances\nwill be considered the \u201cLicensor.\u201d The text of the Creative Commons\npublic licenses is dedicated to the public domain under the CC0 Public\nDomain Dedication. Except for the limited purpose of indicating that\nmaterial is shared under a Creative Commons public license or as\notherwise permitted by the Creative Commons policies published at\ncreativecommons.org/policies, Creative Commons does not authorize the\nuse of the trademark \"Creative Commons\" or any other trademark or logo\nof Creative Commons without its prior written consent including,\nwithout limitation, in connection with any unauthorized modifications\nto any of its public licenses or any other arrangements,\nunderstandings, or agreements concerning use of licensed material. For\nthe avoidance of doubt, this paragraph does not form part of the\npublic licenses.\n\nCreative Commons may be contacted at creativecommons.org\n
    "},{"location":"DeveloperGuide/TroubleShooting/","title":"Trouble shooting","text":""},{"location":"DeveloperGuide/TroubleShooting/#trouble-shooting","title":"Trouble shooting","text":"

    This document describes the most common errors encountered when working with AWSIm or autoware.

    Trouble Solution Massive output of Plugins errors git clone the AWSIM repository again error : RuntimeError: error not set, at C:\\ci\\ws\\src\\ros2\\rcl\\rcl\\src\\rcl\\node.c:262 Set up environment variables and config around ROS2 correctly. For example: - Environment variables - cyclonedds_config.xml $ ros2 topic list is not displayed - your machine ROS_DOMAIN_ID is different- ROS2 is not sourced Using AWSIM on Windows and Autoware on Ubuntu. $ ros2 topic list is not displayed. Allow the communication in Windows Firewall self-driving stops in the middle of the road. Check if your map data is correct (PointCloud, VectorMap, 3D fbx models) Connecting AWSIM and Autoware results in bad network Make ros local host-only. Include the following in the .bashrc (The password will be requested at terminal startup after OS startup.) export ROS_LOCALHOST_ONLY=1export RMW_IMPLEMENTATION=rmw_cyclonedds_cppif [ ! -e /tmp/cycloneDDS_configured ]; thensudo sysctl -w net.core.rmem_max=2147483647sudo ip link set lo multicast ontouch /tmp/cycloneDDS_configuredfi Lidar (colored pointcloud on RViz ) does not show. Reduce processing load by following command. This can only be applied to Autoware's awsim-stable branch. cd <path_to_your_autoware_folder>wget \"https://drive.google.com/uc?export=download&id=11mkwfg-OaXIp3Z5c3R58Pob3butKwE1Z\" -O patch.shbash patch.sh && rm patch.sh Error when starting AWSIM binary. segmentation fault (core dumped) - Check if yourNvidia drivers or Vulkan API are installed correctly - When building binary please pay attantion whether the Graphic Jobs option in Player Settings is disabled. It should be disabled since it may produce segmentation fault errors. Please check forum for more details. Initial pose does not match automatically. Set initial pose manually. Unity crashes and check the log for the cause of the error. Editor log file locationWindows : C:\\Users\\username\\AppData\\Local\\Unity\\Editor\\Editor.logLinux : ~/.config/unity3d/.Editor.log Player log file location Windows : C:\\Users\\username\\AppData\\LocalLow\\CompanyName\\ProductName\\output_log.txtLinux :~/.config/unity3d/CompanyName/ProductName/Player.logSee also : Unity Documentation - Log Files Safe mode dialog appears when starting UnityEditor. or error : No usable version of libssl was found 1. download libssl $ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5.11_amd64.deb 2. install sudo dpkg -i libssl1.0.0_1.0.2n-1ubuntu5.11_amd64.deb (Windows) Unity Editor's error:Plugins: Failed to load 'Assets/RGLUnityPlugin/Plugins/Windows/x86_64/RobotecGPULidar.dll' because one or more of its dependencies could not be loaded. Install Microsoft Visual C++ Redistributable packages for Visual Studio 2015, 2017, 2019, and 2022 (X64 Architecture) (Windows) Built-binary or Unity Editor freeze when simulation started Update/Install latest NIC(NetworkInterfaceCard) drivers for your PC.Especially, if you can find latest drivers provided by chip vendors for the interfaces (not by Microsoft), we recommend vendors' drivers."},{"location":"GettingStarted/QuickStartDemo/","title":"Quick Start Demo","text":""},{"location":"GettingStarted/QuickStartDemo/#quick-start-demo","title":"Quick Start Demo","text":"

    Below you can find instructions on how to setup the self-driving demo of AWSIM simulation controlled by Autoware. The instruction assumes using the Ubuntu OS.

    "},{"location":"GettingStarted/QuickStartDemo/#demo-configuration","title":"Demo configuration","text":"

    The simulation provided in the AWSIM demo is configured as follows:

    AWSIM Demo Settings Vehicle Lexus RX 450h Environment Japan Tokyo Nishishinjuku Sensors GNSSIMU3 x VLP16Traffic Light Camera Traffic Randomized traffic ROS2 humble"},{"location":"GettingStarted/QuickStartDemo/#pc-specs","title":"PC specs","text":"

    Please make sure that your machine meets the following requirements in order to run the simulation correctly:

    Required PC Specs OS Ubuntu 22.04 CPU 6c12t or higher GPU RTX 2080 or higher Nvidia Driver (Ubuntu 22) >=545"},{"location":"GettingStarted/QuickStartDemo/#dds-configuration","title":"DDS configuration","text":"

    In order to run AWSIM Labs with the best performance and without hogging the network, please follow the steps below.

    Add the following lines to ~/.bashrc file:

    if [ ! -e /tmp/cycloneDDS_configured ]; then\n    sudo sysctl -w net.core.rmem_max=2147483647\n    sudo sysctl -w net.ipv4.ipfrag_time=3\n    sudo sysctl -w net.ipv4.ipfrag_high_thresh=134217728     # (128 MB)\n    sudo ip link set lo multicast on\n    touch /tmp/cycloneDDS_configured\nfi\n

    Every time you restart this machine, and open a new terminal, the above commands will be executed.

    Until you restart the machine, they will not be executed again.

    "},{"location":"GettingStarted/QuickStartDemo/#cyclonedds-configuration","title":"CycloneDDS configuration","text":"

    Save the following as cyclonedds.xml in your home directory ~: 

    <?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n<CycloneDDS xmlns=\"https://cdds.io/config\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd\">\n    <Domain Id=\"any\">\n        <General>\n            <Interfaces>\n                <NetworkInterface name=\"lo\" priority=\"default\" multicast=\"default\" />\n            </Interfaces>\n            <AllowMulticast>default</AllowMulticast>\n            <MaxMessageSize>65500B</MaxMessageSize>\n        </General>\n        <Internal>\n            <SocketReceiveBufferSize min=\"10MB\"/>\n            <Watermarks>\n                <WhcHigh>500kB</WhcHigh>\n            </Watermarks>\n        </Internal>\n    </Domain>\n</CycloneDDS>\n

    Make sure the following lines are added to the ~/.bashrc file:

    export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp\nexport CYCLONEDDS_URI=/home/your_username/cyclonedds.xml\n

    Replace your_username with your actual username.

    Note

    You should use the absolute path to the cyclonedds.xml file.

    Warning

    A system restart is required for these changes to work.

    Warning

    DO NOT set export ROS_LOCALHOST_ONLY=1. CycloneDDS configuration will be enough.

    "},{"location":"GettingStarted/QuickStartDemo/#start-the-demo","title":"Start the demo","text":""},{"location":"GettingStarted/QuickStartDemo/#running-the-awsim-demo","title":"Running the AWSIM demo","text":"

    To run the simulator, please follow the steps below.

    1. Install Nvidia GPU driver (Skip if already installed).

      1. Add Nvidia driver to apt repository 
        sudo add-apt-repository ppa:graphics-drivers/ppa\nsudo apt update\n
      2. Install the recommended version of the driver. 
        sudo ubuntu-drivers autoinstall\n\n# or install a specific version (following was tested)\nsudo apt install nvidia-driver-550\n
      3. Reboot your machine to make the installed driver detected by the system. 
        sudo reboot\n
      4. Open terminal and check if nvidia-smi command is available and outputs summary similar to the one presented below. 
        $ nvidia-smi\n+-----------------------------------------------------------------------------------------+\n| NVIDIA-SMI 550.54.15              Driver Version: 550.54.15      CUDA Version: 12.4     |\n|-----------------------------------------+------------------------+----------------------+\n| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |\n| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |\n|                                         |                        |               MIG M. |\n|=========================================+========================+======================|\n|   0  NVIDIA GeForce RTX 3080        Off |   00000000:2D:00.0  On |                  N/A |\n| 30%   40C    P8             35W /  320W |    5299MiB /  10240MiB |      7%      Default |\n|                                         |                        |                  N/A |\n+-----------------------------------------+------------------------+----------------------+\n...\n

    2. Install Vulkan Graphics Library (Skip if already installed).

      1. Update the environment. 
        sudo apt update\n
      2. Install the library. 
        sudo apt install libvulkan1\n

    3. Download and Run AWSIM Demo binary.

      1. Download the latest release from:

        AWSIM Labs GitHub Releases Page

      2. Unzip the downloaded file.

      3. Make the file executable.

        Right click the awsim_labs.x86_64 file and check the Execute checkbox

        or execute the command below.

        chmod +x <path to AWSIM folder>/awsim_labs.x86_64\n

      4. Launch awsim_labs.x86_64. 

        ./<path to AWSIM folder>/awsim_labs.x86_64\n

        It may take some time for the application to start the so please wait until image similar to the one presented below is visible in your application window.

    "},{"location":"GettingStarted/QuickStartDemo/#launching-autoware","title":"Launching Autoware","text":"

    In order to configure and run the Autoware software with the AWSIM demo, please:

    1. Download map files (pcd, osm) and unzip them. Download Map files (pcd, osm)

    2. Clone Autoware and move to the directory. 

      git clone https://github.com/autowarefoundation/autoware.git\ncd autoware\n
    3. Switch branch to main. 
      git checkout main\n
    4. Configure the environment. (Skip if Autoware environment has been configured before) 
      ./setup-dev-env.sh\n
    5. Create the src directory and clone external dependent repositories into it. 
      mkdir src\nvcs import src < autoware.repos\n
    6. Install dependent ROS packages. 
      source /opt/ros/humble/setup.bash\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n
    7. Build the workspace. 
      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=1\n
    8. Launch Autoware. 
      source install/setup.bash\nros2 launch autoware_launch e2e_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=awsim_labs_sensor_kit map_path:=<absolute path of map folder>\n\n# Use the absolute path for the map folder, don't use the ~ operator.\n\n# Example:\nros2 launch autoware_launch e2e_simulator.launch.xml vehicle_model:=sample_vehicle sensor_model:=awsim_labs_sensor_kit map_path:=/home/your_username/autoware_map/nishishinjuku_autoware_map\n
    "},{"location":"GettingStarted/QuickStartDemo/#lets-run-the-self-driving-simulation","title":"Let's run the self driving simulation","text":"

    1. Launch AWSIM and Autoware according to the steps described earlier in this document.

    2. The Autoware will automatically set its pose estimation as presented below.

    3. Set the navigation goal for the vehicle.

    4. Optionally, you can define an intermediate point through which the vehicle will travel on its way to the destination. The generated path can be seen on the image below.

    5. Enable self-driving.

    To make the vehicle start navigating please engage its operation using the command below.

    cd autoware\nsource install/setup.bash\nros2 topic pub /autoware/engage autoware_vehicle_msgs/msg/Engage '{engage: True}' -1\n

    The self-driving simulation demo has been successfully launched!

    "},{"location":"GettingStarted/QuickStartDemo/#troubleshooting","title":"Troubleshooting","text":"

    In case of any problems with running the sample AWSIM binary with Autoware, start with checking our Troubleshooting page with the most common problems.

    "},{"location":"GettingStarted/QuickStartDemo/#appendix","title":"Appendix","text":"
    • AWSIM ROS2 topic list
    "},{"location":"GettingStarted/SetupUnityProject/","title":"Setup Unity Project","text":""},{"location":"GettingStarted/SetupUnityProject/#setup-unity-project","title":"Setup Unity Project","text":"

    Info

    It is advised to checkout the Quick Start Demo tutorial before reading this section.

    This page is a tutorial for setting up a AWSIM Unity project.

    "},{"location":"GettingStarted/SetupUnityProject/#environment-preparation","title":"Environment preparation","text":""},{"location":"GettingStarted/SetupUnityProject/#system-setup","title":"System setup","text":"Ubuntu 22Windows
    1. Make sure your machine meets the required hardware specifications.
      • NOTE: PC requirements may vary depending on simulation contents which may change as the simulator develops
    2. Prepare a desktop PC with Ubuntu 22.04 installed.
    3. Install Nvidia drivers and Vulkan Graphics API.
    4. Install git.
    5. Follow the DDS configuration guide.
    1. Make sure your machine meets the required hardware specifications.
      • NOTE: PC requirements may vary depending on simulation contents which may change as the simulator develops
    2. Prepare a desktop PC with Windows 10 or 11 (64 bit) installed.
    3. Install git.
    4. Install Microsoft Visual C++ Redistributable packages for Visual Studio 2015, 2017, 2019, and 2022 (X64 Architecture)
    "},{"location":"GettingStarted/SetupUnityProject/#ros-2","title":"ROS 2","text":"

    AWSIM comes with a standalone flavor of Ros2ForUnity. This means that, to avoid internal conflicts between different ROS 2 versions, you shouldn't run the Editor or AWSIM binary with ROS 2 sourced.

    Warning

    Do not run the AWSIM, Unity Hub, or the Editor with ROS 2 sourced.

    Ubuntu 22Windows
    • Make sure that the terminal which you are using to run Unity Hub, Editor, or AWSIM doesn't have ROS 2 sourced.
    • It is common to have ROS 2 sourced automatically with ~/.bashrc or ~/.profile. Make sure it is not obscuring your working environment:
      • Running Unity Hub from the Ubuntu GUI menu takes the environment configuration from ~/.profile.
      • Running Unity Hub from the terminal uses the current terminal configuration from ~/.profile and ~/.bashrc.
      • Running Unity Editor from the UnityHub inherits the environment setup from the Unity Hub.
    • Make sure your Windows environment variables are ROS 2 free.
    "},{"location":"GettingStarted/SetupUnityProject/#unity-installation","title":"Unity installation","text":"

    Info

    AWSIM's Unity version is currently 2022.3.36f1

    Follow the steps below to install Unity on your machine:

    "},{"location":"GettingStarted/SetupUnityProject/#install-unityhub","title":"Install UnityHub:","text":"
    1. Install UnityHub to manage Unity projects. Please go to Unity download page and download latest UnityHub.AppImage.
    2. Install Unity 2022.3.36f1 via UnityHub:
      • Open new terminal, navigate to directory where UnityHub.AppImage is download and execute the following command: 
        ./UnityHub.AppImage\n
    "},{"location":"GettingStarted/SetupUnityProject/#install-unity-editor","title":"Install Unity Editor:","text":"
    1. Click Installs from the left menu and then click the Install Editor button from the top right.
    2. From the new window click the Official releases tab and check for the current version of Unity. - If you can't find the version, click to Archive and search for the version in the Unity archives page. It will direct you to Unity Archive.

    3. After finding the version, click the download/install button to start the installation process. - At this point, your Unity installation process should have started.

      === \"Ubuntu 22\" - *NOTE: If the installation process has not started after clicking the download/install button, please copy the hyperlink (by right clicking the button and selecting Copy link address) and add it as an argument for Unity Hub app. An example command: 

      ./UnityHub.AppImage unityhub://2022.3.21f1/d91830b65d9b\n

    4. After successful installation the version will be available in the Installs tab in Unity Hub.

    "},{"location":"GettingStarted/SetupUnityProject/#open-awsim-project","title":"Open AWSIM project","text":"

    To open the Unity AWSIM project in Unity Editor:

    Using Unity HubUsing Terminal

    1. Make sure you have the AWSIM repository cloned and ROS 2 is not sourced. 

      git clone git@github.com:autowarefoundation/AWSIM.git\n

    2. Launch UnityHub. 

      ./UnityHub.AppImage\n

      Info

      If you are launching the Unity Hub from the Ubuntu applications menu (without the terminal), make sure that system optimizations are set. To be sure, run the terminal at least once before running the Unity Hub. This will apply the OS settings.

    3. Open the project in UnityHub

      • Click the Open button from the Projects tab,
      • Navigate the directory where the AWSIM repository was cloned to and select the directory,
      • The project should be added to Projects tab in Unity Hub. To launch the project in Unity Editor simply click the AWSIM project.
      • The project is now ready to use.
      • The project can be opened by double clicking on the project name or selecting it from the list then clicking the Open button on the top right.

    1. Enter the AWSIM directory (make sure ROS 2 is not sourced). 

      cd AWSIM\n

    2. If your Unity Editor is in default location, run the project using the editor command. 

      ~/Unity/Hub/Editor/[your_editor_version]/Editor/Unity -projectPath .\n

      Info

      Please specify your Unity Editor version in the path. If your Unity Editor is installed in different location, please adjust the path accordingly.

    Warning

    If you get the safe mode dialog when starting UnityEditor, you may need to install openssl.

    1. download libssl $ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl1.0/libssl1.0.0_1.0.2n-1ubuntu5.13_amd64.deb
    2. install sudo dpkg -i libssl1.0.0_1.0.2n-1ubuntu5.13_amd64.deb
    "},{"location":"GettingStarted/SetupUnityProject/#import-external-packages","title":"Import external packages","text":"

    To properly run and use AWSIM project in Unity it is required to download map package which is not included in the repository.

    1. Download and import Nishishinjuku_URP_v0.1.0.unitypackage

      Download Map Package

    2. In Unity Editor, from the menu bar at the top, select Assets -> Import Package -> Custom Package... and navigate the Nishishinjuku_URP.unitypackage file you've downloaded and open.

    3. Click Import button in the popup window to import the package.
    4. Nishishinjuku package should be successfully imported under Assets/AWSIM/Externals/directory. You can access the directory from the Project window in Unity Editor.

    Info

    The Externals directory is added to the .gitignore because the map has a large file size and should not be directly uploaded to the repository.

    "},{"location":"GettingStarted/SetupUnityProject/#import-graphy-asset","title":"Import Graphy Asset","text":"

    Import Graphy by following these instructions: Graphy Asset Setup

    "},{"location":"GettingStarted/SetupUnityProject/#run-the-demo-in-editor","title":"Run the demo in Editor","text":"

    The following steps describe how to run the demo in Unity Editor:

    1. Open the AutowareSimulation.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Now you should see the simulation running in the Editor.

    If you encounter any issues while running the simulation, please refer to the Troubleshooting section or open an issue in the AWSIM Labs GitHub.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/","title":"Using OpenSCENARIO","text":""},{"location":"GettingStarted/UsingOpenSCENARIO/#using-openscenario","title":"Using OpenSCENARIO","text":"

    Warning

    Running AWSIM with scenario_simulator_v2 is still a prototype, so stable running is not guaranteed.

    Below you can find instructions on how to setup the OpenSCENARIO execution using scenario_simulator_v2 with AWSIM as a simulator The instruction assumes using the Ubuntu OS.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/#prerequisites","title":"Prerequisites","text":"
    • Follow Setup Unity Project tutorial
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#build-autoware-with-scenario_simulator_v2","title":"Build Autoware with scenario_simulator_v2","text":"

    In order to configure the Autoware software with the AWSIM Labs demo, please:

    1. Clone the Autoware and move to the directory. 
      git clone git@github.com:autowarefoundation/autoware.git\ncd autoware\n
    2. Check out to the awsim-labs-stable branch (This is a temporary branch, and it will be used in the main branch later on.) 
      git checkout awsim-labs-stable\n
    3. Configure the environment. (Skip if Autoware environment has been configured before) 
      ./setup-dev-env.sh\n
    4. Create the src directory and clone external dependent repositories into it. 
      mkdir src\nvcs import src < autoware.repos\nvcs import src < simulator.repos\n

    5. Download shinjuku_map.zip archive

    6. Unzip it to src/simulator directory 

      unzip <Download directory>/shinjuku_map.zip -d src/simulator\n
    7. Install dependent ROS packages. 
      source /opt/ros/humble/setup.bash\nrosdep update\nrosdep install -y --from-paths src --ignore-src --rosdistro $ROS_DISTRO\n
    8. Build the workspace. 
      colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"-w\"\n
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#running-the-demo","title":"Running the demo","text":"
    1. Open AutowareSimulationScenarioSimulator.unity scene placed under Assets/AWSIM/Scenes/Main directory
    2. Run the simulation by clicking Play button placed at the top section of Editor.
    3. Launch scenario_test_runner. 
      source install/setup.bash\nros2 launch scenario_test_runner scenario_test_runner.launch.py                        \\\narchitecture_type:=awf/universe/20240605  record:=false                                         \\\nscenario:='$(find-pkg-share scenario_test_runner)/scenario/sample_awsim.yaml'          \\\nsensor_model:=awsim_labs_sensor_kit  vehicle_model:=sample_vehicle                          \\\nlaunch_simple_sensor_simulator:=false autoware_launch_file:=\"e2e_simulator.launch.xml\" \\\ninitialize_duration:=260 port:=8080\n
    "},{"location":"GettingStarted/UsingOpenSCENARIO/#troubleshooting","title":"Troubleshooting","text":"

    In case of problems, make sure that the regular demo work well with the Autoware built above. Follow the troubleshooting page there if necessary.

    "},{"location":"GettingStarted/UsingOpenSCENARIO/#appendix","title":"Appendix","text":"
    • AWSIM ROS2 topic list
    "},{"location":"Introduction/AWSIM/","title":"AWSIM Labs","text":""},{"location":"Introduction/AWSIM/#awsim-labs","title":"AWSIM Labs","text":"

    AWSIM Labs is a fork of TIER IV/AWSIM, an open-source simulator made with Unity for autonomous driving research and development. It is developed for self-driving software like Autoware. This simulator aims to bridge the gap between the virtual and real worlds, enabling users to train and evaluate their autonomous systems in a safe and controlled environment before deploying them on real vehicles. It provides a realistic virtual environment for training, testing, and evaluating various aspects of autonomous driving systems.

    AWSIM simulates a variety of real-world scenarios, with accurate physics and sensor models. It offers a wide range of sensors, such as: Cameras, GNSS, IMU and LiDARs, allowing developers to simulate their autonomous vehicle's interactions with the environment accurately. The simulator also models dynamic objects, such as pedestrians, other vehicles, and traffic lights, making it possible to study interactions and decision-making in complex traffic scenarios. This enables the testing and evaluation of perception, planning, and control algorithms under different sensor configurations and scenarios.

    AWSIM supports a flexible and modular architecture, making it easy to customize and extend its capabilities. Users can modify the current or add a new environment with their own assets and traffic rules to create custom scenarios to suit their specific research needs. This allows for the development and testing of advanced algorithms in diverse driving conditions.

    Because AWSIM was developed mainly to work with Autoware, it supports:

    • Ubuntu 22.04 and Windows 10/11
    • ROS2 Humble distribution

    Prerequisites

    You can read more about the prerequisites and running AWSIM here.

    Connection with Autoware

    Introduction about how the connection between AWSIM and Autoware works can be read here.

    "},{"location":"Introduction/AWSIM/#why-was-awsim-developed","title":"Why was AWSIM developed?","text":"

    The main objectives of AWSIM are to facilitate research and development in autonomous driving, enable benchmarking of algorithms and systems, and foster collaboration and knowledge exchange within the autonomous driving community. By providing a realistic and accessible platform, AWSIM aims to accelerate the progress and innovation in the field of autonomous driving.

    "},{"location":"Introduction/AWSIM/#architecture","title":"Architecture","text":"

    To describe the architecture of AWSIM, first of all, it is necessary to mention the Scene. It contains all the objects occurring in the simulation of a specific scenario and their configurations. The default AWSIM scene that is developed to work with Autoware is called AutowareSimulation.

    In the scene we can distinguish basics components such like MainCamera, ClockPublisher, EventSystem and Canvas. A detailed description of the scene and its components can be found here.

    Besides the elements mentioned above, the scene contains two more, very important and complex components: Environment and EgoVehicle - described below.

    "},{"location":"Introduction/AWSIM/#environment","title":"Environment","text":"

    Environment is a component that contains all Visual Elements that simulate the environment in the scene and those that provide control over them. It also contains two components Directional Light and Volume, which ensure suitable lighting for Visual Elements and simulate weather conditions. A detailed description of these components can be found here.

    In addition to Visual Elements such as buildings or greenery, it contains the entire architecture responsible for traffic. The traffic involves NPCVehicles that are spawned in the simulation by TrafficSimulator - using traffic components. A quick overview of the traffic components is provided below, however, you can read their detailed description here.

    NPCPedestrians are also Environment components, but they are not controlled by TrafficSimulator. They have added scripts that control their movement - you can read more details here.

    "},{"location":"Introduction/AWSIM/#traffic-components","title":"Traffic Components","text":"

    TrafficLanes and StopLines are elements loaded into Environment from Lanelet2. TrafficLanes have defined cross-references in such a way as to create routes along the traffic lanes. In addition, each TrafficLane present at the intersection has specific conditions for yielding priority. TrafficSimulator uses TrafficLanes to spawn NPCVehicles and ensure their movement along these lanes. If some TrafficLanes ends just before the intersection, then it has a reference to StopLine. Each StopLine at the intersection with TrafficLights has reference to the nearest TrafficLight. TrafficLights belong to one of the visual element groups and provide an interface to control visual elements that simulate traffic light sources (bulbs). A single TrafficIntersection is responsible for controlling all TrafficLights at one intersection. Detailed description of mentioned components is in this section.

    "},{"location":"Introduction/AWSIM/#egovehicle","title":"EgoVehicle","text":"

    EgoVehicle is a component responsible for simulating an autonomous vehicle moving around the scene. It includes:

    • Models and Reflection Probe components related to its visual appearance.
    • Colliders providing collisions and the ability to move on roads.
    • Sensors providing data related to the state of the vehicle, including its position and speed in Environment and the state of its surroundings.
    • Vehicle component that simulates dynamics, controls **Wheel and is responsible for ensuring their movement.
    • Vehicle Ros Input and Vehicle Keyboard Inputcomponents that have a reference to the Vehicle object and set control commands in it.
    • Vehicle Visual Effect provides an interface for Vehicle to control the lighting.

    A detailed description of EgoVehicle and its components mentioned above can be found here. The sensor placement on EgoVehicle used in the default scene is described here. Details about each of the individual sensors are available in the following sections: Pose, GNSS, LiDAR, IMU, Camera, Vehicle Status.

    "},{"location":"Introduction/AWSIM/#fixedupdate-limitation","title":"FixedUpdate Limitation","text":"

    In AWSIM, the sensors' publishing methods are triggered from the FixedUpdate function and the output frequency is controlled by:

    time += Time.deltaTime;\nvar interval = 1.0f / OutputHz;\ninterval -= 0.00001f; // Allow for accuracy errors.\nif (time < interval)\n    return;\ntimer = 0;\n

    Since this code runs within the FixedUpdate method, it's essential to note that Time.deltaTime is equal to Fixed Timestep, as stated in the Unity Time.deltaTime documentation. Consequently, with each invocation of FixedUpdate, the time variable in the sensor script will increment by a constant value of Fixed Timestep, independent of the actual passage of real-time. Additionally, as outlined in the Unity documentation, the FixedUpdate method might execute multiple times before the Update method is called, resulting in extremely small time intervals between successive FixedUpdate calls. The diagram below illustrates the mechanism of invoking the FixedUpdate event function.\"

    During each frame (game tick) following actions are performed:

    • first, the Delta Time is calculated as the difference between the current frame and the previous frame,
    • next, the Delta Time is added to the Time (regular time),
    • afterward, a check is made to determine how much Fixed Time (physics time) is behind the Time,
    • if the difference between Time and Fixed Time is equal to or greater then Fixed Timestep, the Fixed Update event function is invoked,
    • if FixedUpdate function were called, the Fixed Timestep is added to the Fixed Time,
    • once again, a check is performed to assess how much Fixed Time is behind the Time,
    • if necessary, the FixedUpdate function is called again,
    • if the difference between the Time and the Fixed Time is smaller than the Fixed Timestep, the Update method is called, followed be scene rendering and other Unity event functions.

    As a consequence, this engine feature may result in unexpected behavior when FPS (Frames Per Second) are unstable or under certain combinations of FPS, Fixed Timestep, and sensor OutputHz

    In case of low frame rates, it is advisable to reduce the Time Scale of the simulation. The Time Scale value impacts simulation time, which refers to the time that is simulated within the model and might or might not progress at the same rate as real-time. Therefore, by reducing the time scale, the progression of simulation time slows down, allowing the simulation more time to perform its tasks.

    "},{"location":"Introduction/Autoware/","title":"Autoware","text":""},{"location":"Introduction/Autoware/#autoware","title":"Autoware","text":"

    Autoware is an open-source software platform specifically designed for autonomous driving applications. It was created to provide a comprehensive framework for developing and testing autonomous vehicle systems. Autoware offers a collection of modules and libraries that assist in various tasks related to perception, planning, and control, making it easier for researchers and developers to build autonomous driving systems.

    The primary purpose of Autoware is to enable the development of self-driving technologies by providing a robust and flexible platform. It aims to accelerate the research and deployment of autonomous vehicles by offering a ready-to-use software stack. Autoware focuses on urban driving scenarios and supports various sensors such as LiDAR, Radars, and Cameras, allowing for perception of the vehicle's surroundings.

    "},{"location":"Introduction/Autoware/#why-use-awsim-with-autoware","title":"Why use AWSIM with Autoware?","text":"

    Autoware can be used with a AWSIM for several reasons. Firstly, simulators like AWSIM provide a cost-effective and safe environment for testing and validating autonomous driving algorithms before deploying them on real vehicles. Autoware's integration with a simulator allows developers to evaluate and fine-tune their algorithms without the risk of real-world accidents or damage.

    Additionally, simulators enable developers to recreate complex driving scenarios, including difficult conditions or rare events, which may be difficult to replicate in real-world testing with such high fidelity. Autoware's compatibility with a AWSIM allows seamless integration between the software and the simulated vehicle, enabling comprehensive testing and validation of autonomous driving capabilities. By utilizing a simulator, Autoware can be extensively tested under various scenarios to ensure its robustness and reliability.

    Connection with Autoware

    Introduction about how the connection between AWSIM and Autoware works can be read here.

    "},{"location":"Introduction/Autoware/#architecture","title":"Architecture","text":"

    In terms of architecture, Autoware follows a modular approach. It consists of multiple independent modules that communicate with each other through a ROS2. This modular structure allowing users to select and combine different modules based on their specific needs and requirements. The software stack comprises multiple components, including perception, localization, planning, and control modules. Here's a brief overview of each module:

    • Sensing - acquires data from sensors different sensors mounted on the autonomous vehicle such as LiDARs, GNSS, IMU and cameras. It pre-processing received data in order to later extract relevant information about the surrounding environment through the Perception module or about vehicle location by the Localization module. More details here.
    • Perception - performs advanced processing of sensor data (LiDARs, cameras) to extract meaningful information about the surrounding environment. It performs tasks like object detection (other vehicles, pedestrians), lane detection, and traffic lights recognition. More details here.
    • Localization - performs a fusion of data from Sensing module like LiDAR, GNSS, IMU, and odometry sensors to estimate the vehicle's position and orientation accurately. More details here.
    • Planning - generates a safe and feasible trajectory for the autonomous vehicle based on the information gathered from Perception and Localization. It also takes into account various factors from Map like traffic rules and road conditions. More details here.
    • Control - executes the planned trajectory by sending commands to the vehicle's actuators, such as steering, throttle, and braking. It ensures that the vehicle follows the desired trajectory while maintaining safety and stability. More details here.
    • Vehicle Interface - is a crucial component that enables communication and interaction between Autoware software system and a vehicle. It facilitates the exchange of control signals and vehicle information necessary for autonomous driving operations. The vehicle interface ensures that Autoware can send commands to the vehicle, such as acceleration, braking, and steering, while also receiving real-time data from the vehicle, such as speed, position, and sensors data. It acts as a bridge, allowing Autoware to seamlessly interface with the specific characteristics and requirements of the vehicle it is operating with. More details here.
    • Map - the map module creates and maintains a representation of the environment in which the autonomous vehicle operates. It combines data from Lanelet2 (*.osm) and PointCloud (*.pcd) to generate a detailed map. The map contains information about road geometries, lane markings, traffic lights, rules, and other relevant features. Map serves as a crucial reference for planning and decision-making processes. More details here.
    "},{"location":"Introduction/CombinationWithAutoware/","title":"CombinationWithAutoware","text":"

    Autoware is a powerful open-source software platform for autonomous driving. Its modular architecture, including perception, localization, planning, and control modules, provides a comprehensive framework for developing self-driving vehicles. Autoware combined with AWSIM simulator provides safe testing, validation, and optimization of autonomous driving algorithms in diverse scenarios.

    Run with Autoware

    If you would like to know how to run AWSIM with Autoware, we encourage you to read this section.

    "},{"location":"Introduction/CombinationWithAutoware/#features","title":"Features","text":"

    The combination of Autoware and AWSIM provides the opportunity to check the correctness of the vehicle's behavior in various traffic situations. Below are presented some typical features provided by this combination. Moreover, examples of detecting several bad behaviors are included.

    "},{"location":"Introduction/CombinationWithAutoware/#engagement","title":"Engagement","text":"

    • Driving straight through an intersection with priority

    • Turning at the intersection

    "},{"location":"Introduction/CombinationWithAutoware/#traffic-light-recognition","title":"Traffic light recognition","text":"

    • Stopping at a red light

    • Driving on a green light

    • Stopping at yellow light

    • Still driving at yellow light (only when it is too late to stop)

    "},{"location":"Introduction/CombinationWithAutoware/#interaction-with-vehicles","title":"Interaction with vehicles","text":"

    • Yield right-of-way when turning right

    • Following the vehicles ahead

    • Stopping behind the vehicles ahead

    • Cutting-in to a different traffic lane

    "},{"location":"Introduction/CombinationWithAutoware/#interaction-with-pedestrians","title":"Interaction with pedestrians","text":"

    • Giving right of way to a pedestrian crossing at a red light

    • Giving way to a pedestrian crossing beyond a crosswalk

    "},{"location":"Introduction/CombinationWithAutoware/#detecting-bad-behaviors","title":"Detecting bad behaviors","text":"

    • Incorrect and dangerous execution of a lane change

    • Too late detection of a pedestrian entering the roadway

    "},{"location":"Introduction/CombinationWithAutoware/#combination-architecture","title":"Combination Architecture","text":"

    The combination of AWSIM with Autoware is possible thanks to Vehicle Interface and Sensing modules of Autoware architecture. The component responsible for ensuring connection with these modules from the AWSIM side is EgoVehicle. It has been adapted to the Autoware architecture and provides ROS2 topic-based communication. However, the other essential component is ClockPublisher, which provides simulation time for Autoware - also published on the topic - more details here.

    EgoVehicle component provides the publication of the current vehicle status through a script working within Vehicle Status. It provides real-time information such as: current speed, current steering of the wheels or current states of lights - these are outputs from AWSIM.

    On the other hand, Vehicle Ros Input is responsible for providing the values of the outputs from Autoware. It subscribes to the current commands related to the given acceleration, gearbox gear or control of the specified lights.

    Execution of the received commands is possible thanks to Vehicle, which ensures the setting of appropriate accelerations on the **Wheel and controlling the visual elements of the vehicle.

    The remaining data delivered from AWSIM to Autoware are sensors data, which provides information about the current state of the surrounding environment and those necessary to accurately estimate EgoVehicle position.

    More about EgoVehicle and its scripts is described in this section.

    "},{"location":"Introduction/CombinationWithAutoware/#sequence-diagram","title":"Sequence diagram","text":"

    Below is a simplified sequential diagram of information exchange in connection between AWSIM and Autoware. As you can see, the first essential information published from AWSIM is Clock - the simulation time. Next, EgoVehicle is spawned and first sensors data are published, which are used in the process of automatic position initialization on Autoware side. At the same time, the simulation on AWSIM side is updated.

    Next in the diagram is the main information update loop in which:

    • During each cycle there is a synchronization with the time from the simulation.
    • AWSIM publishes data from sensors available in EgoVehicle, which are taken into account in the processes carried out in Autoware.
    • The control commands from Autoware are subscribed by AWSIM, which are executed on AWSIM side and EgoVehicle update is performed.
    • The current state of the EgoVehicle is published.

    The order of information exchange presented in the diagram is a simplification. The exchange of information takes place through the publish-subscribe model and each data is sent with a predefined frequency.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/","title":"Combination with Autoware and Scenario simulator v2","text":""},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#combination-with-autoware-and-scenario-simulator-v2","title":"Combination with Autoware and Scenario simulator v2","text":"

    Scenario Simulator v2 (SS2) is a scenario testing framework specifically developed for Autoware, an open-source self-driving software platform. It serves as a tool for Autoware developers to conveniently create and execute scenarios across different simulators.

    The primary goal of SS2 is to provide Autoware developers with an efficient means of writing scenarios once and then executing them in multiple simulators. By offering support for different simulators and scenario description formats, the framework ensures flexibility and compatibility.

    The default scenario format in this framework is TIER IV Scenario Format version 2.0. The scenario defined on this format is converted by scenario_test_runner to openSCENARIO format, which is then interpreted by openscenario_interpreter. Based on this interpretation, traffic_simulator simulates traffic flow in an urban area. Each NPC has a behavior tree and executes commands from the scenario.

    The framework uses ZeroMQ Inter-Process communication for seamless interaction between the simulator and the traffic_simulator. To ensure synchronous operation of the simulators, SS2 utilizes the Request/Reply sockets provided by ZeroMQ and exchanges binarized data through Protocol Buffers. This enables the simulators to run in a synchronized manner, enhancing the accuracy and reliability of scenario testing.

    QuickStart Scenario simulator v2 with Autoware

    If you would like to see how SS2 works with Autoware using default build-in simulator - simple_sensor_simulator (without running AWSIM) - we encourage you to read this tutorial.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#combination-architecture","title":"Combination Architecture","text":"

    AWSIM scene architecture used in combination with SS2 changes considerably compared to the default scene. Here traffic_simulator from SS2 replaces TrafficSimulator implementation in AWSIM - for this reason it and its StopLines, TrafficLanes and TrafficIntersection components are removed. Also, NPCPedestrian and NPCVehicles are not added as aggregators of NPCs in Environment.

    Instead, their counterparts are added in ScenarioSimulatorConnector object that is responsible for spawning Entities of the scenario. Entity can be: Pedestrian, Vehicle, MiscObject and Ego. EgoEntity is the equivalent of EgoVehicle - which is also removed from the default scene. However, it has the same components - it still communicates with Autoware as described here. So it can be considered that EgoVehicle has not changed and NPCPedestrians and NPCVehicles are now controlled directly by the SS2.

    A detailed description of the SS2 architecture is available here. A description of the communication via ROS2 between SS2 and Autoware can be found here.

    "},{"location":"Introduction/CombinationWithAutowareAndScenarioSimulator/#sequence-diagram","title":"Sequence diagram","text":"

    In the sequence diagram, the part responsible for AWSIM communication with Autoware also remained unchanged. The description available here is the valid description of the reference shown in the diagram below.

    Communication between SS2 and AWSIM takes place via Request-Response messages, and is as follows:

    1. Launch - Autoware is started and initialized.
    2. Initialize - the environment in AWSIM is initialized, basic parameters are set.
    3. opt Ego spawn - optional, EgoEntity (with sensors) is spawned in the configuration defined in the scenario.
    4. opt NPC spawn loop - optional, all Entities (NPCs) defined in the scenario are spawned, the scenario may contain any number of each Entity type, it may not contain them at all or it may also be any combination of the available ones.
    5. update loop - this is the main loop where scenario commands are executed, first EgoEntity is updated - SS2 gets its status, and then every other Entity is updated - the status of each NPCs is set according to the scenario. Next, the simulation frame is updated - here the communication between Autoware and AWSIM takes place. The last step of the loop is to update the traffic light state.
    6. despawn loop - after the end of the scenario, all Entities spawned on the scene are despawned (including EgoEnity)
    7. Terminate - Autoware is terminated.

    Documentation of the commands used in the sequence is available here.

    "},{"location":"ProjectGuide/Directory/","title":"Directory","text":""},{"location":"ProjectGuide/Directory/#directory","title":"Directory","text":"

    AWSIM has the following directory structure. Mostly they are grouped by file type.

    AWSIM       //  root directory.\n \u2502\n \u2502\n \u251c\u2500Assets                           // Unity project Assets directory.\n \u2502  \u2502                               // Place external libraries\n \u2502  \u2502                               // under this directory.\n \u2502  \u2502                               // (e.g. RGLUnityPlugin, ROS2ForUnity, etc..)\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u251c\u2500AWSIM                         // Includes assets directly related to AWSIM\n \u2502  |                               // (Scripts, Prefabs etc.)\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Externals                  // Place for large files or\n \u2502  \u2502  |                            // external project dependencies\n \u2502  \u2502  |                            // (e.g. Ninshinjuku map asset).\n \u2502  \u2502  \u2502                            // The directory is added to `.gitignore`\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500HDRPDefaultResources       // Unity HDRP default assets.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Materials                  // Materials used commonly in Project.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Models                     // 3D models\n \u2502  \u2502  \u2502  \u2502                         // Textures and materials for 3D models\n \u2502  \u2502  \u2502  \u2502                         // are also included.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2514\u2500<3D Model>              // Directory of each 3D model.\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u251c\u2500Materials            // Materials used in 3D model.\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2502\n \u2502  \u2502  \u2502     \u2514\u2500Textures             // Textures used in 3D model.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Prefabs                    // Prefabs not dependent on a specific scene.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u251c\u2500Scenes                     // Scenes\n \u2502  \u2502  \u2502  \u2502                         // Includes scene-specific scripts, etc.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u251c\u2500Main                    // Scenes used in the simulation.\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502  \u2514\u2500Samples                 // Sample Scenes showcasing components.\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2502\n \u2502  \u2502  \u2514\u2500Scripts                    // C# scripts.\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u251c\u2500RGLUnityPlugin        // Robotec GPU LiDAR external Library.\n \u2502  \u2502                       // see: https://github.com/RobotecAI/RobotecGPULidar\n \u2502  \u2502\n \u2502  \u2502\n \u2502  \u2514\u2500Ros2ForUnity          // ROS2 communication external Library.\n \u2502                          // see: https://github.com/RobotecAI/ros2-for-unity\n \u2502\n \u251c\u2500Packages         // Unity automatically generated directories.\n \u251c\u2500ProjectSettings  //\n \u251c\u2500UserSettings     //\n \u2502\n \u2502\n \u2514\u2500docs             // AWSIM documentation. Generated using mkdocs.\n                    // see: https://www.mkdocs.org/\n
    "},{"location":"ProjectGuide/ExternalLibraries/","title":"External Libraries","text":""},{"location":"ProjectGuide/ExternalLibraries/#external-libraries","title":"External Libraries","text":"

    List of external libraries used in AWSIM.

    Library Usage URL ros2-for-unity ROS2 communication https://github.com/RobotecAI/ros2-for-unity Robtoec-GPU-LiDAR LiDAR simulation https://github.com/RobotecAI/RobotecGPULidar"},{"location":"ProjectGuide/GitBranch/","title":"Git Branch","text":""},{"location":"ProjectGuide/GitBranch/#git-branch","title":"Git branch","text":"

    The document presents the rules of branching adopted in the AWSIM development process.

    "},{"location":"ProjectGuide/GitBranch/#branches","title":"Branches","text":"branch explain main Stable branch. Contains all the latest releases. feature/*** Feature implementation branch created from main. After implementation, it is merged into main. gh-pages Documentation hosted on GitHub pages."},{"location":"ProjectGuide/GitBranch/#branch-flow","title":"Branch flow","text":"
    1. Create feature/*** branch from main.
    2. Implement in feature/*** branch.
    3. Create a PR from the feature/*** branch to main branch. Merge after review.
    "},{"location":"ProjectGuide/HotkeyList/","title":"Hotkey List","text":""},{"location":"ProjectGuide/HotkeyList/#hotkey-list","title":"Hotkey List","text":""},{"location":"ProjectGuide/HotkeyList/#vehiclekeyboardinputcs","title":"VehicleKeyboardInput.cs","text":"Key Feature D Change drive gear. P Parking gear. R Reverse gear. N Neutral gear. 1 Left turn signal. 2 Right turn signal. 3 Hazard. 4 Turn signal off. Up arrow Accelerate. Left arrow Steering (Left). Right arrow Steering (Right). Down arrow Breaking.

    W,A,S,D keys can also be used to control the vehicle, similar to the arrow keys.

    "},{"location":"ProjectGuide/HotkeyList/#followcameracs","title":"FollowCamera.cs","text":"Key Feature C Camera rotation on/off toggle. Mouse drag Rotate Camera angle. Mouse wheel Zoom in/out of camera."},{"location":"ProjectGuide/HotkeyList/#hotkeyhandlercs","title":"HotkeyHandler.cs","text":"Key Feature Esc Toggle side bar LeftCtrl + R Reset ego vehicle LeftCtrl + T Toggle traffic visibility"},{"location":"ProjectGuide/HotkeyList/#birdeyeviewcs","title":"BirdEyeView.cs","text":"Key Feature B Toggle BEV camera WASD / Arrow Keys Pan BEV camera Mouse Wheel + Drag Pan BEV camera Mouse Wheel Zoom in/out Space Snap camera to vehicle LeftCtrl + Space Follow ego vehicle on/off"},{"location":"ProjectGuide/HotkeyList/#graphy-asset","title":"Graphy Asset","text":"Key Feature F3 Toggle Graphy Visualizer"},{"location":"ProjectGuide/Scenes/","title":"Scenes","text":"

    In the AWSIM Unity project there is one main scene (AutowareSimulation) and several additional ones that can be helpful during development. This section describes the purpose of each scene in the project.

    "},{"location":"ProjectGuide/Scenes/#autowaresimulation","title":"AutowareSimulation","text":"

    The AutowareSimulation scene is the main scene that is designed to run the AWSIM simulation together with Autoware. It allows for effortless operation, just run this scene, run Autoware with the correct map file and everything should work right out of the box.

    "},{"location":"ProjectGuide/Scenes/#pointcloudmapping","title":"PointCloudMapping","text":"

    The PointCloudMapping is a scene that is designed to create a point cloud using the Unity world. Using the RGLUnityPlugin and prefab Environment - on which there are models with Meshes - we are able to obtain a *.pcd file of the simulated world.

    "},{"location":"ProjectGuide/Scenes/#sensorconfig","title":"SensorConfig","text":"

    Scene SensorConfig was developed to perform a quick test of sensors added to the EgoVehicle prefab. Replace the Lexus prefab with a vehicle prefab you developed and check whether all data that should be published is present, whether it is on the appropriate topics and whether the data is correct.

    "},{"location":"ProjectGuide/Scenes/#npcvehiclesample","title":"NPCVehicleSample","text":"

    The NPCVehicleSample was developed to conduct a quick test of the developed vehicle. Replace the taxi prefab with a vehicle prefab you developed (EgoVehicle or NPCVehicle) and check whether the basic things are configured correctly. The description of how to develop your own vehicle and add it to the project is in this section.

    "},{"location":"ProjectGuide/Scenes/#npcpedestriansample","title":"NPCPedestrianSample","text":"

    The NPCPedestrianSample was developed to conduct a quick test of the developed pedestrian. Replace the NPC prefab in NPC Pedestrian Test script with a prefab you developed and check whether the basic things are configured correctly.

    "},{"location":"ProjectGuide/Scenes/#trafficintersectionsample","title":"TrafficIntersectionSample","text":"

    The TrafficIntersectionSample was developed to conduct a quick test of the developed traffic intersection. Replace the intersection configuration with your own and check whether it works correctly. You can add additional groups of lights and create much larger, more complex sequences. A description of how to configure your own traffic intersection is in this section.

    "},{"location":"ProjectGuide/Scenes/#trafficlightsample","title":"TrafficLightSample","text":"

    The TrafficLightSample was developed to conduct a quick test of a developed traffic lights model in cooperation with the script controlling it. Replace the lights and configuration with your own and check whether it works correctly.

    "},{"location":"ProjectGuide/Scenes/#randomtrafficyielding","title":"RandomTrafficYielding","text":"

    The RandomTrafficYielding was developed to conduct a tests of a developed yielding rules at the single intersection.

    "},{"location":"ProjectGuide/Scenes/#randomtrafficyieldingbirdeye","title":"RandomTrafficYieldingBirdEye","text":"

    The RandomTrafficYielding was developed to conduct a tests of a developed yielding rules with multiple vehicles moving around the entire environment.

    "},{"location":"ProjectGuide/Scenes/#rgl-test-scenes","title":"RGL test scenes","text":"

    The scenes described below are used for tests related to the external library RGLUnityPlugin (RGL) - you can read more about it in this section.

    "},{"location":"ProjectGuide/Scenes/#lidarscenedevelop","title":"LidarSceneDevelop","text":"

    The scene LidarSceneDevelop can be used as a complete, minimalistic example of how to setup RGL. It contains RGLSceneManager component, four lidars, and an environment composed of floor and walls.

    "},{"location":"ProjectGuide/Scenes/#lidarskinnedstress","title":"LidarSkinnedStress","text":"

    The scene LidarSkinnedStress can be used to test the performance of RGL. E.g. how performance is affected when using Regular Meshes compared to Skinned Meshes. The scene contains a large number of animated models that require meshes to be updated every frame, thus requiring more resources (CPU and data exchange with GPU).

    "},{"location":"ProjectGuide/Scenes/#lidardisablingtest","title":"LidarDisablingTest","text":"

    The scene LidarDisablingTest can be used to test RGL performance with similar objects but with different configurations. It allows you to check whether RGL works correctly when various components that can be sources of Meshes are disabled (Colliders, Regular Meshes, Skinned Meshes, ...).

    "},{"location":"ProjectGuide/Scenes/#lidarinstancesegmentationdemo","title":"LidarInstanceSegmentationDemo","text":"

    The LidarInstanceSegmentationDemo is a demo scene for instance segmentation feature. It contains a set of GameObjects with ID assigned and sample lidar that publishes output to the ROS2 topic. The GameObjects are grouped to present different methods to assign IDs.

    To run demo scene:

    1. Open scene: Assets/AWSIM/Scenes/Samples/LidarInstanceSegmentationDemo.unity
    2. Run simulation
    3. Open rviz2
    4. Setup rviz2 as follows:
      • Fixed frame: world,
      • PointCloud2 topic: lidar/instance_id,
      • Topic QoS as in the screen above.
      • Channel name: enitity_id,
      • To better visualization disable Autocompute intensity and set min to 0 and max to 50.
    "}]} \ No newline at end of file diff --git a/pr-120/sitemap.xml b/pr-120/sitemap.xml index a290bb5c2..29689a293 100644 --- a/pr-120/sitemap.xml +++ b/pr-120/sitemap.xml @@ -130,6 +130,11 @@ 2024-07-19 daily + + https://autowarefoundation.github.io/AWSIM-Labs/pr-120/Components/Traffic/NPCs/RvizNPCSpawner/ + 2024-07-19 + daily + https://autowarefoundation.github.io/AWSIM-Labs/pr-120/Components/Traffic/NPCs/Vehicle/ 2024-07-19 diff --git a/pr-120/sitemap.xml.gz b/pr-120/sitemap.xml.gz index b749128c2..7f3139014 100644 Binary files a/pr-120/sitemap.xml.gz and b/pr-120/sitemap.xml.gz differ