CARLA 执行

把生成的路网与场景真正跑进 CARLA：加载 .xodr 建成可驾驶世界、 播放 .xosc 驱动车辆、并截图。

1. 工具参数

1.1 run_road_in_carla

1.2 run_scenario_in_carla

1.3 list_carla_maps

返回服务端版本、当前地图、可用地图列表。

1.4 run_traffic_light_demo

在含红绿灯的内置地图上演示信号灯条件与信号灯动作：挑一盏灯，沿来车方向后退 约 35m 布设自车，先冻结为红灯，到 red_hold 后切绿，自车按 TrafficSignalCondition(green) 起步。

2. 对话示例

CARLA 连上了吗
把十字路口路网加载进 CARLA 并截图
在 CARLA 里播放 cut_in 场景，第 2 秒和第 5 秒各截一张图
把 wrong_way 场景跑 6 秒看看效果

3. 代码示例

import carla_runner as CR
from scenario_templates import build
from osc_builder import write_scenario
from xosc_player import parse_xosc, play

# 1. 连接并加载路网
client = CR.connect()
world = CR.load_xodr_world(client, "output/straight.xodr")
CR.clear_actors(world)

# 2. 准备场景
spec = build("cut_in", seed=1)
write_scenario(spec, "output/cut_in.xosc")
sc = parse_xosc("output/cut_in.xosc")

# 3. 播放并截图
res = play(world, sc, duration=8.0, capture_at=[2.0, 5.0],
           out_dir="output/shots")
print(res["events_fired"], "/", res["events_total"])

4. 路网加载流程

load_xodr_world() 会先把文件内容读出来，检查 <planView/> 是否有几何， 再交给 Client.generate_opendrive_world()。加载耗时约 2 秒。

5. 播放器支持范围

5.1 支持

边沿检测支持 rising / falling / risingOrFalling / none 四种 ConditionEdge。

触发结构按 esmini 语义求值：

• 多个 ConditionGroup 之间 OR，组内多个 Condition 之间 AND
• 每个 Condition 可带 delay，需连续成立 N 秒才触发
• TriggeringEntities 决定条件求值主体（未声明时回落到 ManeuverGroup 的 Actor）
• Story / Act / Sequence 全层级遍历；一个 ManeuverGroup 的多个 Actor 各展开一份事件
• <ParameterDeclarations> 的 $name / ${name} 在解析前静态替换
• StopTrigger 与 StartTrigger 同一套语义，满足即提前结束
• SpeedActionDynamics 支持 step / linear / cubic / sinusoidal， dynamicsDimension 支持 time 与 rate
• LongitudinalDistanceAction 的 maxAcceleration / maxDeceleration 作为 IDM 的 $a_{\max}$ / $b$，输出加速度再按上限夹一次

5.2 不支持

以下会记入 unsupported 并明确返回，不会静默跳过：

6. 返回结果

run_scenario_in_carla 返回执行统计：

✅ OpenSCENARIO 场景已在 CARLA 中播放

场景：lead_brake.xosc
实体 3 个，成功布景 3 个
时长 6.00s（120 帧）
事件 4 个，已触发 3 个
已触发的动作：
   t=0.00s ego   ego_longitudinal_distance_ev follow=15.00
   t=0.05s lead  lead_speed_ev              speed=13.00
   t=2.05s lead  lead_speed_ev              speed=0.00
未执行（超出播放器范围）：
   - 事件 ego_standstill_ev 的条件 StandStillCondition 未满足
截图：
   - output/shots/t02.00.png
   - output/shots/t04.00.png

若场景配置了 StopTrigger，摘要末尾会多一行实际运行时长与结束原因， 结果 JSON 对应 ended_at 与 stop_reason（duration / stop_trigger）两个字段。

7. 12 个模板的实测结果

以下是 python llm/tools/run_regression.py --carla --duration 5 的实测输出 （自建 straight 路网，每个模板跑 5 秒）：

lead_brake / cut_in / unprotected_turn / overtake 各有一个事件未触发， 是条件本身未满足（前车没在时限内完全静止 / 时距没降到阈值 / 5 秒内没走完 变道），不是播放器缺陷；--duration 拉长即可触发。

signal_phase 依赖地图自带的红绿灯，自建路网里没有，离线编译正常、实跑请用 run_traffic_light_demo（内置地图）：

2026-11 红绿灯相位演示：Town03，红灯 4 秒后切绿，自车起步

效果见效果展示。

8. 注意事项