chore(autoware_crosswalk_traffic_light_estimator): fix docs (#9822)

* fix docs Signed-off-by: MasatoSaeki <[email protected]> * fix docs Signed-off-by: MasatoSaeki <[email protected]> * add tlr output image Signed-off-by: MasatoSaeki <[email protected]> * modify sentense Signed-off-by: MasatoSaeki <[email protected]> * modify sentense Signed-off-by: MasatoSaeki <[email protected]> * refactor readme Signed-off-by: MasatoSaeki <[email protected]> * fix docs Signed-off-by: MasatoSaeki <[email protected]> * fix Signed-off-by: MasatoSaeki <[email protected]> * style(pre-commit): autofix --------- Signed-off-by: MasatoSaeki <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
autowarefoundation · Jan 15, 2025 · b69241f · b69241f
1 parent 65f6417
commit b69241f
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 18 deletions.
diff --git a/perception/autoware_crosswalk_traffic_light_estimator/README.md b/perception/autoware_crosswalk_traffic_light_estimator/README.md
@@ -1,40 +1,85 @@
-# crosswalk_traffic_light_estimator
+# autoware_crosswalk_traffic_light_estimator
 
 ## Purpose
 
-`crosswalk_traffic_light_estimator` is a module that estimates pedestrian traffic signals from HDMap and detected vehicle traffic signals.
+`autoware_crosswalk_traffic_light_estimator` estimates pedestrian traffic signals which can be summarized as the following two tasks:
+
+- Estimate pedestrian traffic signals that are not subject to be detected by perception pipeline.
+- Estimate whether pedestrian traffic signals are flashing and modify the result.
+
+This module works without `~/input/route`, but its behavior is outputting the subscribed results as is.
 
 ## Inputs / Outputs
 
 ### Input
 
-| Name                                 | Type                                             | Description        |
-| ------------------------------------ | ------------------------------------------------ | ------------------ |
-| `~/input/vector_map`                 | `autoware_map_msgs::msg::LaneletMapBin`          | vector map         |
-| `~/input/route`                      | `autoware_planning_msgs::msg::LaneletRoute`      | route              |
-| `~/input/classified/traffic_signals` | `tier4_perception_msgs::msg::TrafficSignalArray` | classified signals |
+| Name                                 | Type                                                  | Description        |
+| ------------------------------------ | ----------------------------------------------------- | ------------------ |
+| `~/input/vector_map`                 | autoware_map_msgs::msg::LaneletMapBin                 | vector map         |
+| `~/input/route`                      | autoware_planning_msgs::msg::LaneletRoute             | optional: route    |
+| `~/input/classified/traffic_signals` | autoware_perception_msgs::msg::TrafficLightGroupArray | classified signals |
 
 ### Output
 
-| Name                       | Type                                                    | Description                                               |
-| -------------------------- | ------------------------------------------------------- | --------------------------------------------------------- |
-| `~/output/traffic_signals` | `autoware_perception_msgs::msg::TrafficLightGroupArray` | output that contains estimated pedestrian traffic signals |
+| Name                       | Type                                                  | Description                                               |
+| -------------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
+| `~/output/traffic_signals` | autoware_perception_msgs::msg::TrafficLightGroupArray | output that contains estimated pedestrian traffic signals |
 
 ## Parameters
 
-| Name                          | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default value |
-| :---------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
-| `use_last_detect_color`       | `bool`   | If this parameter is `true`, this module estimates pedestrian's traffic signal as RED not only when vehicle's traffic signal is detected as GREEN/AMBER but also when detection results change GREEN/AMBER to UNKNOWN. (If detection results change RED or AMBER to UNKNOWN, this module estimates pedestrian's traffic signal as UNKNOWN.) If this parameter is `false`, this module use only latest detection results for estimation. (Only when the detection result is GREEN/AMBER, this module estimates pedestrian's traffic signal as RED.) | `true`        |
-| `last_detect_color_hold_time` | `double` | The time threshold to hold for last detect color.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `2.0`         |
+| Name                          | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default value |
+| :---------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
+| `use_last_detect_color`       | bool   | If this parameter is `true`, this module estimates pedestrian's traffic signal as RED not only when vehicle's traffic signal is detected as GREEN/AMBER but also when detection results change GREEN/AMBER to UNKNOWN. (If detection results change RED or AMBER to UNKNOWN, this module estimates pedestrian's traffic signal as UNKNOWN.) If this parameter is `false`, this module use only latest detection results for estimation. (Only when the detection result is GREEN/AMBER, this module estimates pedestrian's traffic signal as RED.) | true          |
+| `last_detect_color_hold_time` | double | The time threshold to hold for last detect color. The unit is second.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 2.0           |
+| `last_colors_hold_time`       | double | The time threshold to hold for history detected pedestrian traffic light color. The unit is second.                                                                                                                                                                                                                                                                                                                                                                                                                                                | 1.0           |
 
 ## Inner-workings / Algorithms
 
+When the pedestrian traffic signals **are detected** by perception pipeline
+
+- If estimates the pedestrian traffic signals are flashing, overwrite the results
+- Prefer the output from perception pipeline, but overwrite it if the pedestrian traffic signals are invalid(`no detection`, `backlight`, or `occlusion`)
+
+When the pedestrian traffic signals **are NOT detected** by perception pipeline
+
+- Estimate the color of pedestrian traffic signals based on detected vehicle traffic signals, HDMap, and route
+
+### Estimate whether pedestrian traffic signals are flashing
+
+```plantumul
+start
+if (the pedestrian traffic light classification result exists)then
+    : update the flashing flag according to the classification result(in_signal) and last_signals
+    if (the traffic light is flashing?)then(yes)
+      : update the traffic light state
+    else(no)
+      : the traffic light state is the same with the classification result
+if (the classification result not exists)
+    : the traffic light state is the same with the estimation
+ : output the current traffic light state
+end
+```
+
+#### Update flashing flag
+
+<div align="center">
+  <img src="images/flashing_state.png" width=50%>
+</div>
+
+#### Update traffic light status
+
+<div align="center">
+  <img src="images/traffic_light.png" width=50%>
+</div>
+
+### Estimate the color of pedestrian traffic signals
+
 ```plantuml
 
 start
-:subscribe detected traffic signals & HDMap;
+:subscribe detected traffic signals, HDMap, and route;
 :extract crosswalk lanelets from HDMap;
-:extract road lanelets that conflicts crosswalk;
+:extract road lanelets that conflicts crosswalk from route;
 :initialize non_red_lanelets(lanelet::ConstLanelets);
 if (Latest detection result is **GREEN** or **AMBER**?) then (yes)
   :push back non_red_lanelets;
@@ -58,7 +103,7 @@ end
 
 If traffic between pedestrians and vehicles is controlled by traffic signals, the crosswalk traffic signal maybe **RED** in order to prevent pedestrian from crossing when the following conditions are satisfied.
 
-### Situation1
+#### Situation1
 
 - crosswalk conflicts **STRAIGHT** lanelet
 - the lanelet refers **GREEN** or **AMBER** traffic signal (The following pictures show only **GREEN** case)
@@ -70,7 +115,7 @@ If traffic between pedestrians and vehicles is controlled by traffic signals, th
   <img src="images/intersection1.svg" width=80%>
 </div>
 
-### Situation2
+#### Situation2
 
 - crosswalk conflicts different turn direction lanelets (STRAIGHT and LEFT, LEFT and RIGHT, RIGHT and STRAIGHT)
 - the lanelets refer **GREEN** or **AMBER** traffic signal (The following pictures show only **GREEN** case)

diff --git a/perception/autoware_crosswalk_traffic_light_estimator/images/flashing_state.png b/perception/autoware_crosswalk_traffic_light_estimator/images/flashing_state.png
diff --git a/perception/autoware_crosswalk_traffic_light_estimator/images/traffic_light.png b/perception/autoware_crosswalk_traffic_light_estimator/images/traffic_light.png