[FEATURE] Port Carla run_synchronization with SUMO signal light sync via traffic light table

[yunlishao]

Workflow: One Issue, One Branch, Four PRs

Test scenario: MLK EcoDriving from xil_oct_sumo_carla branch (tests/Applications/SUMO_CARLA_EcoDriving)
Carla FBX: MLK_noped1002_final_debug.fbx (on SharePoint)
Scope: Standalone Python scripts under /Carla — no TrafficLayer integration required for this issue. Full FIXS integration (referencing the existing C++ VirCarlaEnv Carla API) will be a future issue.

All work on one branch (e.g., feature/#120-run-sync), with PRs:

PR	Phase	Deliverable	Prerequisite	Due
PR 1	SUMO + Carla map import	Import the MLK scenario into SUMO (verify network loads, standalone SUMO runs). Import the FBX into Carla/Unreal, including how signal lights are automatically imported and generated in Unreal. Document the import steps. Verify Carla loads the map successfully.	None	Mar 2
PR 2	Signal light mapping table	Understand and verify the full SUMO-to-Carla signal light mapping. Either use the existing extract_sumo_tls_as_table.py script to generate the traffic_light_table.csv, or document what manual steps are needed. Ensure we have a complete mapping table for the MLK scenario.	None (parallel with PR 1)	Mar 2
PR 3	Design doc for ported run_synchronization.py	Understand what Carla 0.9.15's default run_synchronization.py does, identify what needs to be updated/added for FIXS signal light sync (CSV table loading, SUMO-as-master signal sync). Write a design document (.md under Carla/ folder) describing the plan — what the ported script will include, its API, and how it differs from the Carla default. If broader architectural context is needed, reference or link from doc/.	PR 1 & PR 2 merged	Mar 13
PR 4	Implementation + Demo	Code the standalone run_synchronization.py under Carla/ folder. Must load the CSV signal mapping table, sync SUMO signal states to Carla each tick (SUMO is always the signal master), and handle vehicle synchronization. End-to-end test using the MLK EcoDriving scenario with a working demo (screenshot/video).	PR 3 merged	Apr 13

How to work

1. Create branch feature/#120-run-sync from main
2. Reference this issue in each PR (e.g., "Part of [FEATURE] Port Carla run_synchronization with SUMO signal light sync via traffic light table #120")
3. PR 1 and PR 2 can proceed in parallel; PR 3–4 are sequential

---

Roles

• Developer: @west053 — implement and submit PRs
• Reviewer: @Kazawaryu — review and approve PRs before merge

---

Is your feature request related to a problem?
Currently, FIXS does not include Carla's default run_synchronization script for SUMO co-simulation. The existing signal light synchronization logic lives inside the C++ VirCarlaEnv component (specifically in BridgeHelper — see BridgeHelper::readTrafficLightTable, BridgeHelper::map_Sumo_traffic_light_state_to_Carla, and the traffic light sync loop in mainVirCarla.cpp), but there is no standalone Python-based run_synchronization script that can be used independently with the Carla Python API. This makes it difficult to run SUMO-Carla co-simulation without the full VirCarlaEnv C++ pipeline.

Describe the solution you'd like

1. Port Carla 0.9.15's default run_synchronization.py into the Carla/ folder as a starting point for SUMO-Carla co-simulation.
2. Add a signal light synchronization function that:
   • Reads a traffic light mapping table (CSV format, mapping SUMO junction IDs and link IDs to Carla traffic light positions — same format used by BridgeHelper::readTrafficLightTable in VirCarlaEnv/VirCarlaEnv/BridgeHelper.cpp). See existing examples: tests/SumoCarla/test_scenarios/Shallowford_.../traffic_light_table.csv and tests/SumoCarla/test_scenarios/Town01_.../traffic_light_table.csv.
   • Maps SUMO signal states to Carla traffic light states (equivalent to BridgeHelper::map_Sumo_traffic_light_state_to_Carla).
   • Always assumes SUMO is controlling the signal lights (i.e., SUMO is the source of truth for signal state; Carla traffic lights are frozen and set from SUMO state each tick).
3. The output should be a self-contained, ported run_synchronization script inside the Carla/ folder that can run SUMO-Carla co-simulation with signal light sync out of the box.

Additional context and future direction

• Carla's built-in SUMO co-simulation tools (run_synchronization.py) do not support custom SUMO-to-Carla traffic light table mapping, so signal mapping must be added.
• Eventually, we want a Python API version of VirCarlaEnv that is more similar to run_synchronization and compatible with the full FIXS ecosystem. The existing C++ VirCarlaEnv remains valuable as it connects to the full FIXS socket-based pipeline. This standalone script is a first step toward a run_synchronization that is compatible with full FIXS.
• The traffic light mapping table is defined and used by VirCarlaEnv/VirCarlaEnv/BridgeHelper (specifically readTrafficLightTable at BridgeHelper.cpp:232 and state mapping at BridgeHelper.cpp:191). The table CSV contains columns for junction ID, link ID, x, y, z, and heading.
• The VirCarlaEnv debug launch arguments reference this table: -t ..\..\tests\SumoCarla\test_scenarios\Shallowford_after_calibration_banleftturn_AdjustedFixedTime_V3\traffic_light_table.csv
• Existing Python utilities in tests/SumoCarla/utils/ (e.g., trafficlight_helper.py, extract_sumo_tls_as_table.py) and tests/SumoCarla/carla_scripts/ may be useful references.
• The Carla 0.9.15 wheel is already present at Carla/carla-0.9.15-cp310-cp310-win_amd64.whl.

Environment (if feature is environment-specific)

• Python version: 3.10 (Carla 0.9.15 wheel)
• CARLA version: 0.9.15
• SUMO version: 1.21