feat: split planning sim demo into multiple pages

docs/community/support/troubleshooting/index.md

@@ -192,7 +192,7 @@ If you have any of these symptoms, please the [Performance Troubleshooting](perf
 
 ### Map does not display when running the Planning Simulator
 
-When running the Planning Simulator, the most common reason for the map not being displayed in RViz is because [the map path has not been specified correctly in the launch command](../../../demos/planning-simulation.md#lane-driving-scenario). You can confirm if this is the case by searching for `Could not find lanelet map under {path-to-map-dir}/lanelet2_map.osm` errors in the log.
+When running the Planning Simulator, the most common reason for the map not being displayed in RViz is because [the map path has not been specified correctly in the launch command](../../../demos/planning-sim/lane-driving.md). You can confirm if this is the case by searching for `Could not find lanelet map under {path-to-map-dir}/lanelet2_map.osm` errors in the log.
 
 Another possible reason is that map loading is taking a long time due to poor DDS performance. For this, please visit the [Performance Troubleshooting](performance-troubleshooting.md) page.
 
@@ -208,7 +208,7 @@ colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug --packages-up-to <the modules
 ```
 
 In this state, when a died process occurs when you run the autoware again, a core file will be created.
-Remeber to remove the size limit of the core file.
+Remember to remove the size limit of the core file.
 
 ```bash
 ulimit -c unlimited

docs/demos/.pages

@@ -1,6 +1,6 @@
 nav:
   - index.md
   - digital-twin-demos
-  - planning-simulation.md
+  - Planning simulation: planning-sim
   - rosbag-replay-simulation.md
   - scenario-simulation

docs/demos/index.md

@@ -27,7 +27,7 @@
 
 ## Planning simulation demo
 
-[:fa-cl-s fa-circle-arrow-right: Planning Simulation Demo](planning-simulation.md){ .md-button }
+[:fa-cl-s fa-circle-arrow-right: Planning Simulation Demo](planning-sim/index.md){ .md-button }
 
 ???+ abstract "Summary"
 

docs/demos/planning-sim/.pages

@@ -0,0 +1,11 @@
+nav:
+  - index.md
+  - lane-driving.md
+  - parking.md
+  - pull-over-out.md
+  - lane-change.md
+  - placing-objects.md
+  - avoidance.md
+  - traffic-light.md
+  - crosswalk.md
+  - using-launch-gui.md

docs/demos/planning-sim/avoidance.md

@@ -0,0 +1,13 @@
+# Avoidance scenario
+
+1. Set an initial pose and a goal pose in the same lane. A path will be planned.
+
+   ![set-position-and-goal](images/avoidance/set-position-and-goal.png)
+
+2. Set a "2D Dummy Bus" on the roadside. A new path will be planned.
+
+   ![set-dummy-bus](images/avoidance/set-dummy-bus.png)
+
+3. Engage the ego vehicle. It will avoid the obstacle along the newly planned path.
+
+   ![avoidance-driving](images/avoidance/avoidance-driving.png)

docs/demos/planning-sim/crosswalk.md

@@ -0,0 +1,105 @@
+# Driving through a crosswalk
+
+When driving through a crosswalk, the ego vehicle evaluates **both** the presence of pedestrians/objects **and** the state of any associated traffic lights.
+
+!!! info
+
+    For more technical details, refer to the [**autoware_behavior_velocity_crosswalk_module** documentation](https://autowarefoundation.github.io/autoware_universe/main/planning/behavior_velocity_planner/autoware_behavior_velocity_crosswalk_module/).
+
+!!! info
+
+    These examples use the **Nishishinjuku** map, the same one used in the [lane change scenario](lane-change.md).
+
+!!! tip
+
+    For these tutorials, it is easier to use **interactive dummy pedestrians** (see [Placing interactive dummy objects](placing-objects.md) above).
+
+    This way you can quickly add, move, and delete dummy pedestrians as needed.
+
+## Non-signalized crosswalk (no traffic light)
+
+### Behavior logic
+
+```mermaid
+flowchart TD
+    A["Approach **crosswalk**"] --> B{"Pedestrian somewhere on the **crosswalk**? <br/> (Pedestrian velocity is not important.)"}
+    B -- "No" --> C["Proceed without slowing down"]
+    B -- "Yes" --> D["Slow down and stop **one time**"]
+    D --> E["Wait a few seconds to confirm safe to proceed"]
+    E --> F{"Pedestrian or object on **planned path**?"}
+    F -- "Yes" --> G["Continue waiting / yield"]
+    F -- "No" --> H["Resume driving (will not stop again for this crosswalk)"]
+    H --> I["Crosswalk passed ➡️ behavior resets when encountering the same crosswalk again"]
+```
+
+!!! example "Experiment"
+
+    We will test the expected “single stop then go” behavior:
+
+    1. Place a still dummy pedestrian on the crosswalk. (Not on the planned path, just on the crosswalk.)
+
+    2. The ego vehicle will decelerate and stop before the crosswalk.
+
+    3. After waiting for a few seconds, the ego vehicle will start driving again as usual.
+
+1. Set an initial pose and a goal pose for the ego vehicle to drive through a non-signalized crosswalk. A path will be planned.
+
+   ![initial-setup](images/passing-crosswalk/non-signalized/initial-setup.png)
+
+2. Place an interactive dummy pedestrian on the crosswalk and set its pose as if it is crossing the street. It doesn't matter whether the dummy pedestrian is moving or not, as long as it is on the crosswalk.
+
+   ![place-pedestrian](images/passing-crosswalk/non-signalized/place-pedestrian.png)
+
+3. Engage the ego vehicle by clicking on `Auto`. The ego vehicle will decelerate and stop before the crosswalk. The marked **crosswalk** in the figure indicates that the stopping behavior is caused by the objects on the **crosswalk**.
+
+   ![wait-before-crosswalk](images/passing-crosswalk/non-signalized/wait-before-crosswalk.png)
+
+4. The ego vehicle will wait for about a few seconds. Then it will start moving again and pass the crosswalk.
+
+   ![pass-crosswalk](images/passing-crosswalk/non-signalized/pass-crosswalk.png)
+
+## Signalized crosswalk (with traffic light)
+
+<figure markdown="span">
+  ![test-location.png](images/passing-crosswalk/signalized/test-location.png)
+  <figcaption>Location for signalized crosswalk experiments</figcaption>
+</figure>
+
+!!! example "Experiment 1: Pedestrian Present While Traffic Light Is GREEN"
+
+    This experiment mirrors the previous one but at a signalized crosswalk.
+
+With the pedestrian near the path and the traffic light **GREEN**, the ego behaves **the same as at a non-signalized crosswalk**:
+it slows, stops, waits, then continues.
+
+![wait-for-pedestrian](images/passing-crosswalk/signalized/wait-for-pedestrian.png)
+
+!!! example "Experiment 2: Interaction of Pedestrians and a RED Traffic Light"
+
+    1. Stop before the crosswalk when the traffic light is set to `RED`. (Without pedestrians.)
+
+    2. Add a dummy pedestrian on the crosswalk while the traffic light is `RED`. (Both the traffic light and the crosswalk should affect the stopping behavior.)
+
+    3. Finally, set the traffic light to `GREEN` again and the vehicle will pass normally.
+
+1. **Stop at red (no pedestrians).**
+   Remove any existing dummy pedestrians and set the traffic light to **RED**.
+   The ego vehicle will stop before the crosswalk and wait solely because of the **traffic_light** reason.
+
+   ![stop-from-red-light](images/passing-crosswalk/signalized/stop-from-red-light.png)
+
+2. **Add a pedestrian while the light is RED.**
+   The ego remains stopped, now influenced by **both** the traffic light and the crosswalk object.
+
+   ![stop-from-red-and-pedestrian](images/passing-crosswalk/signalized/stop-from-red-and-pedestrian.png)
+
+3. **Observe how the stop reasons update.**
+   After a short period, only **traffic_light** may remain displayed.
+   Moving the pedestrian slightly (with ++shift+"🖱️ Right Click"++ drag) reintroduces both markers, but the system stabilizes back to the traffic-light reason during the wait.
+
+   ![stop-red-light-with-pedestrian.png](images/passing-crosswalk/signalized/stop-red-light-with-pedestrian.png)
+
+4. **Switch the light to GREEN.**
+   When set to green and `Auto` mode is engaged, the ego vehicle proceeds normally.
+
+   ![move-after-red-to-green.png](images/passing-crosswalk/signalized/move-after-red-to-green.png)

docs/demos/planning-sim/index.md

@@ -0,0 +1,92 @@
+# Planning simulation
+
+## Preparation
+
+### Download the sample map
+
+```bash
+gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd'
+unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip
+```
+
+- You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually.
+
+!!! info
+
+    Sample map: Copyright 2020 TIER IV, Inc.
+
+### Make sure the artifacts are downloaded
+
+Check if you have `~/autoware_data` folder and files in it.
+
+```bash
+$ cd ~/autoware_data
+$ ls -C -w 30
+image_projection_based_fusion
+lidar_apollo_instance_segmentation
+lidar_centerpoint
+tensorrt_yolo
+tensorrt_yolox
+traffic_light_classifier
+traffic_light_fine_detector
+traffic_light_ssd_fine_detector
+yabloc_pose_initializer
+```
+
+If not, please, follow [Manual downloading of artifacts](https://github.com/autowarefoundation/autoware/tree/main/ansible/roles/artifacts).
+
+---
+
+!!! info "[Using Autoware Launch GUI](using-launch-gui.md)"
+
+    If you prefer a graphical user interface (GUI) over the command line for launching and managing your simulations, refer to the [Using Autoware Launch GUI](using-launch-gui.md) section at the end of this document for a step-by-step guide.
+
+---
+
+<div style="text-align: center;" markdown="1">
+
+[:fa-cl-s fa-film: Reference Video Tutorials](https://drive.google.com/file/d/1bs_dX1JJ76qHk-SGvS6YF9gmekkN8fz7/view?usp=sharing){ .md-button style="margin: 5px" }
+
+</div>
+
+---
+
+## Basic simulations
+
+<div style="text-align: center;" markdown="1">
+
+[Lane Driving](lane-driving.md){ .md-button style="margin: 5px" }
+[Parking](parking.md){ .md-button style="margin: 5px" }
+[Pull out and pull over](pull-over-out.md){ .md-button style="margin: 5px" }
+[Lane Change](lane-change.md){ .md-button style="margin: 5px" }
+
+</div>
+
+## Advanced simulations
+
+<div style="text-align: center;" markdown="1">
+
+[:fa-cl-s fa-cube: Placing Dummy Objects](placing-objects.md){ .md-button style="margin: 5px" }
+[Avoidance](avoidance.md){ .md-button style="margin: 5px" }
+[Traffic Light Recognition Simulation](traffic-light.md){ .md-button style="margin: 5px" }
+[Driving Through a Crosswalk](crosswalk.md){ .md-button style="margin: 5px" }
+
+</div>
+
+## Increase the maximum velocity
+
+The original Autoware is designed to operate at a wide speed range. But for safety reasons, the default maximum velocity has been limited to **15 km/h**.
+Because of this, even if you drag the slider to a higher speed in the RViz panel, the system will not allow it.
+
+To run Autoware at a higher speed, you can modify the `max_vel` parameter in the config file [autoware_launch/config/planning/scenario_planning/common/common.param.yaml](https://github.com/autowarefoundation/autoware_launch/blob/main/autoware_launch/config/planning/scenario_planning/common/common.param.yaml) located in the `autoware_launch` repository.
+
+!!! example
+
+    Set `max_vel` to `20.0` (20 m/s = 72 km/h).
+    Then launch the planning simulator, place the vehicle and set the velocity limit with the slider.
+
+![increase-max-velocity](images/others/increase-max-velocity.png)
+
+## Create your own map
+
+The content above takes place in the planning simulator using a sample map. If you are interested in running Autoware with maps of your own environment, please visit the [How to Create Vector Map](../../tutorials/integrating-autoware/creating-maps/index.md) section for guidance.

docs/demos/planning-sim/lane-change.md

@@ -0,0 +1,25 @@
+# Lane change scenario
+
+1. Download and unpack Nishishinjuku map.
+
+   ```bash
+   gdown -O ~/autoware_map/ 'https://github.com/tier4/AWSIM/releases/download/v1.1.0/nishishinjuku_autoware_map.zip'
+   unzip -d ~/autoware_map ~/autoware_map/nishishinjuku_autoware_map.zip
+   ```
+
+2. Launch autoware with Nishishinjuku map with following command:
+
+   ```bash
+   source ~/autoware/install/setup.bash
+   ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autoware_map/nishishinjuku_autoware_map vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit
+   ```
+
+   ![open-nishishinjuku-map](images/lane-change/open-nishishinjuku-map.png)
+
+3. Set an initial pose and a goal pose in adjacent lanes.
+
+   ![set-position-and-goal](images/lane-change/set-position-and-goal.png)
+
+4. Engage the ego vehicle. It will make a lane change along the planned path.
+
+   ![lane-changing](images/lane-change/lane-changing.png)

docs/demos/planning-sim/lane-driving.md

@@ -0,0 +1,52 @@
+# Lane driving scenario
+
+## 1. Launch Autoware
+
+```bash
+source ~/autoware/install/setup.bash
+ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit
+```
+
+!!! warning
+
+    Note that you cannot use `~` instead of `$HOME` here.
+
+    If `~` is used, the map will fail to load.
+
+![after-autoware-launch](images/lane-following/after-autoware-launch.png)
+
+## 2. Set an initial pose for the ego vehicle
+
+![set-initial-pose](images/lane-following/set-initial-pose.png)
+
+a) Click the `2D Pose estimate` button in the toolbar, or hit the `P` key.
+
+b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the initial pose. An image representing the vehicle should now be displayed.
+
+!!! warning
+
+    Remember to set the initial pose of the car in the same direction as the lane.
+
+    To confirm the direction of the lane, check the arrowheads displayed on the map.
+
+## 3. Set a goal pose for the ego vehicle
+
+a) Click the `2D Goal Pose` button in the toolbar, or hit the `G` key.
+
+b) In the 3D View pane, click and hold the left-mouse button, and then drag to set the direction for the goal pose. If done correctly, you will see a planned path from initial pose to goal pose.
+
+![set-goal-pose](images/lane-following/set-goal-pose.png)
+
+## 4. Start the ego vehicle
+
+Now you can start the ego vehicle driving by clicking the `Auto` button in the `AutowareStatePanel`.
+Alternatively, you can manually start the vehicle by running the following command:
+
+```bash
+source ~/autoware/install/setup.bash
+ros2 service call /api/operation_mode/change_to_autonomous autoware_adapi_v1_msgs/srv/ChangeOperationMode {}
+```
+
+After that, `Auto` button will be selected and grayed out.
+
+![start-driving](images/lane-following/start-driving.png)

docs/demos/planning-sim/parking.md

@@ -0,0 +1,10 @@
+# Parking scenario
+
+1. Set an initial pose and a goal pose, and engage the ego vehicle.
+
+   ![after-set-goal-pose](images/parking/after-set-goal-pose.png)
+
+2. When the vehicle approaches the goal, it will switch from lane driving mode to parking mode.
+3. After that, the vehicle will maneuver into the destination parking spot.
+
+   ![parking-maneuver](images/parking/parking-maneuver.png)

docs/demos/planning-sim/placing-objects.md

@@ -0,0 +1,27 @@
+# Placing dummy objects
+
+1. Click the `2D Dummy Car` or `2D Dummy Pedestrian` button in the toolbar.
+2. Set the pose of the dummy object by clicking and dragging on the map.
+3. Set the velocity of the object in `Tool Properties -> 2D Dummy Car/Pedestrian` panel.
+
+!!! note
+
+    Changes to the `velocity` parameter will only affect objects placed after the parameter is changed.
+
+![set-dummy-car](images/lane-following/place-dummy-car.png)
+
+!!! tip "Delete all dummy objects"
+
+    Click the `Delete All Objects` button in the toolbar and then click anywhere in the 3D View pane to complete it.
+
+## Placing interactive dummy objects
+
+Click the `Interactive` button in the toolbar to create the next dummy object in interactive mode.
+
+![set-interactive-dummy-car](images/lane-following/check-interactive.png)
+
+!!! info
+
+    - **Add an interactive dummy object:** ++shift+"🖱️ Right Click"++ on the map.
+    - **Delete an interactive dummy object:** ++alt+"🖱️ Right Click"++ on the object.
+    - **Move an existing interactive dummy object:** ++"🖱️ Right Click"++ and hold on the object. Then drag and drop it to the desired location.

docs/demos/planning-sim/pull-over-out.md

@@ -0,0 +1,9 @@
+# Pull out and pull over scenario
+
+1. In a pull out scenario, set the ego vehicle at the road shoulder.
+
+   ![pullover-pullout](images/pullover-pullout/pullover-pullout.png)
+
+2. Set a goal and then engage the ego vehicle.
+
+3. In a pull over scenario, similarly set the ego vehicle in a lane and set a goal on the road shoulder.