场景 API

这个模块提供了与仿真环境交互的主要接口，用于建立连接、获取场景数据以及向场景发送控制命令。

类参考

class metacar.SceneAPI[源代码]

SceneAPI 是与仿真环境通信的主要接口。

该类封装了与仿真环境建立连接、获取场景信息、读取车辆状态以及发送控制命令等功能。使用流程通常是：创建实例 -> 连接 -> 获取静态数据 -> 进入主循环获取动态数据并发送控制命令。

connect()[源代码]

与场景建立连接，会产生阻塞，直到与场景连接成功。

此方法会阻塞执行，直到成功与仿真环境建立连接并完成握手。连接成功后会加载场景静态数据，可通过 get_scene_static_data() 获取。

get_scene_static_data()[源代码]

获取场景静态信息，仅在 connect() 函数调用后可用

此方法返回加载的场景静态数据，包括路线、道路信息和子场景信息。必须在调用 connect() 方法后才能使用。

返回:: 场景静态数据

main_loop()[源代码]

生成器，每次迭代返回 SimCarMsg 和图像帧，场景结束时退出。

此方法是一个生成器，每次迭代会返回当前的仿真车辆消息和摄像头图像帧。当场景结束或连接中断时，生成器会自动退出。

返回:

元组 (sim_car_msg, frames)，其中:

sim_car_msg: SimCarMsg 对象，包含车辆状态、传感器数据等信息
frames: 当前相机视图的列表，每个元素为 CameraFrame 对象

retry_level()[源代码]

重试关卡

增加重试关卡计数器，在下一次发送控制命令时会通知场景重试当前关卡。

set_vehicle_control(vc: VehicleControl, vla_extension: VLAExtensionOutput | None = None)[源代码]

发送车辆控制命令到仿真环境

将给定的车辆控制命令发送到场景，用于控制车辆的油门、刹车、转向等行为。

参数:

vc -- 车辆控制命令，包含油门、刹车、转向等参数
vla_extension -- VLA 相关的输出，非 VLA 场景为 None

skip_level()[源代码]

跳过关卡

增加跳过关卡计数器，在下一次发送控制命令时会通知场景跳过当前关卡。

基本使用流程

使用 SceneAPI 的一般流程如下：

创建 SceneAPI 实例
调用 connect() 与仿真环境建立连接
调用 get_scene_static_data() 获取场景静态信息
使用 main_loop() 生成器获取实时数据
在循环中调用 set_vehicle_control() 发送控制命令

示例

from metacar import SceneAPI, VehicleControl

# 创建 API 并连接
api = SceneAPI()
api.connect()

# 获取静态数据
static_data = api.get_scene_static_data()
print(f"路线点数: {len(static_data.route)}")

# 主循环
for sim_car_msg, frames in api.main_loop():
    # 创建控制命令
    vc = VehicleControl()
    vc.throttle = 0.5

    # 发送控制命令
    api.set_vehicle_control(vc)