4. 使用指南

4.1 配置

入口文件：config/perception/perception.lua → config/autonomy.lua

注意：当前 AUTONOMY_PERCEPTION 为空表，且未挂入 AUTONOMY 根表；system/options.cpp 亦未加载 perception 配置。以下为规划中的配置结构。

-- config/autonomy.lua（规划）
AUTONOMY = {
    perception = AUTONOMY_PERCEPTION,
}

规划字段：

字段	说明	默认建议
`enabled`	是否启动 PerceptionServer	`false`（当前）
`frequency`	感知循环频率 (Hz)	`10.0`
`plugins`	启用的感知插件列表	待实现
`yolo.model_path`	ONNX 模型路径	—
`yolo.confidence_threshold`	检测置信度阈值	`0.5`
`yolo.nms_threshold`	NMS IoU 阈值	`0.45`

4.2 PerceptionServer API（规划）

API	用途	状态
`Start()` / `Shutdown()`	启停感知循环	❌
`Process(sensor_data)`	处理单帧传感器数据	❌
`GetDetections()`	获取最新检测结果	❌
`GetObstacles()`	获取障碍列表	❌

4.3 vision_msgs 消息

感知输出使用 commsgs::vision_msgs 命名空间：

消息	用途
`BoundingBox2D`	2D 旋转检测框（像素坐标）
`BoundingBox2DArray`	带 Header 的 2D 框数组
`BoundingBox3D`	3D 检测框（米制）
`Detection2D`	单目标：框 + 分类 + 置信度
`Detection2DArray`	2D 检测数组
`Detection3D` / `Detection3DArray`	3D 检测
`Classification`	分类结果

BoundingBox2D 示例：

commsgs::vision_msgs::BoundingBox2D box;
box.center.position.x = 320.0;  // 像素
box.center.position.y = 240.0;
box.center.theta = 0.0;         // 弧度，逆时针为正
box.size_x = 100.0;
box.size_y = 80.0;

4.4 common/network 推理 API

API	说明
`BackendFactory::Create(opts)`	创建 ONNX/TensorRT 引擎
`Engine::Run(inputs, &outputs)`	执行推理
`Engine::Warmup()`	静态 shape 模型预热
`RunPipeline(sample, opts)`	预处理 + 推理一体化
`Decode(...)`	YOLO 网格头解码
`Nms(...)`	非极大值抑制

线程安全：Engine 非线程安全，每线程一个实例或外部加锁。

4.5 障碍感知（costmap 路径，当前可用）

激光障碍感知通过 map/costmap_2d 配置，无需 PerceptionServer：

-- config/map/costmap.lua
obstacle_layer = {
    observation_sources = "scan",
    scan = {
        topic = "/scan",
        max_obstacle_height = 2.0,
        min_obstacle_height = 0.0,
        obstacle_range = 2.5,
        raytrace_range = 3.0,
        marking = true,
        clearing = true,
    },
}

C++ 侧 ObstacleLayer::updateBounds() 将观测写入 costmap 栅格。

4.6 系统集成（规划）

// system::Autonomy 构造流程（规划）
perception_ = std::make_shared<perception::PerceptionServer>(options_.perception_options());
perception_->Start();

// 传感器回调
sensor_consumer->OnImage() → perception_->Process(image);
sensor_consumer->OnLaserScan() → costmap_->updateLaser(scan);  // 当前路径

相机/激光 ──→ PerceptionServer ──→ vision_msgs
                    │
                    └──→ ObstacleLayer ──→ costmap ──→ Planning

4.7 驱动层转发（规划）

config/driver/driver.lua 中相机配置预留了向 perception 转发：

front_camera = {
    topic = "/camera/front/image_raw",
    forward_targets = {"perception"},
}

4.8 故障排查

现象	可能原因	处理
costmap 无障碍	激光 topic 未订阅	检查 `observation_sources` 与 topic 名
ONNX 推理失败	模型路径错误或 EP 不可用	确认 `model_path`；CUDA EP 需 ORT GPU 版
TF 变换失败	传感器 frame 未发布	检查 `sensor_frame` 与 transform 树
检测框偏移	内参或预处理不匹配	核对 `GetSpatialSize` 与训练分辨率
PerceptionServer 未启动	模块未接入 Autonomy	当前预期行为；使用 costmap 路径