# 点位格式转换

## 用途

把采点工具导出的 odom JSON 转成 `config/racing_control.yaml` 中比赛总控可直接读取的 ROS 参数。

## 输入文件约定

- `main_.json`：保存 `qr`、`back` 和 `entry` 点时，`back` 用作二维码识别后的过渡点。
- `post_qr_pose` 是二维码识别后、进入 `entry_pose` 前的可调过渡点；没有单独采点时可以先填成 `entry_pose`。
- `main_1.json`：顺时针路线点，最后一个点名为 `home`。
- `main_2.json`：逆时针路线点，最后一个点名为 `home`。
- `main_1.json` 和 `main_2.json` 的第 4 个路线点是 VLM 拍摄点。正式参数用 `vlm_waypoint_number: 4` 表示，不依赖原始点名。
- 默认 `vlm_capture_mode: stop`：总控先规划到第 4 点，停车触发 `/sign4return=9`，等待 `vlm_capture_wait_sec` 后立即继续规划剩余路线。
- 备选 `vlm_capture_mode: pass_through`：总控规划整条路线，车辆经过第 4 点附近 `pass_through_vlm_trigger_radius` 范围时触发 `/sign4return=9`，不停车。

## 输出 YAML 字段

`racing_control.yaml` 中所有点位均使用扁平数组：

```yaml
[x, y, yaw_radians]
```

- `x`：`point.odom.pose.pose.position.x`
- `y`：`point.odom.pose.pose.position.y`
- `yaw_radians`：`point.yaw_degrees * pi / 180`

字段映射：

- `main_.json` 中 `qr` -> `qr_pose`
- `main_.json` 中 `back` -> `post_qr_pose`
- `main_.json` 中 `entry` -> `entry_pose`
- 如需二维码后过渡点，可把采到的新点写入 `post_qr_pose`；不需要该点时设置 `use_post_qr_pose: false`。

## VLM 单帧图像转发

- 默认 `enable_vlm_image_relay: false`，总控只发布 `/sign4return=9` 触发 VLM。
- 设置 `enable_vlm_image_relay: true` 后，总控会缓存 `vlm_image_input_topic` 的最新 `sensor_msgs/msg/CompressedImage`，即将触发 VLM 时先发布一帧到 `vlm_image_output_topic`，再发布 `/sign4return=9`。
- 如需让 VLM 使用这帧图片，把 VLM 节点的 `image_topic` 设置成 `/vlm_image`。
- `main_1.json` 中除 `home` 外的所有点 -> `clockwise_waypoints`
- `main_1.json` 中 `home` -> `clockwise_home_pose`
- `main_2.json` 中除 `home` 外的所有点 -> `counterclockwise_waypoints`
- `main_2.json` 中 `home` -> `counterclockwise_home_pose`

## 转换流程

1. 读取 JSON 的 `points` 数组，保持原始顺序。
2. 对每个点提取 `x`、`y` 和 `yaw_degrees`。
3. 把 `yaw_degrees` 转成弧度。
4. 写入 `config/racing_control.yaml` 对应字段。
5. 路线点不要包含 `home`；`home` 单独写入对应的 `*_home_pose`。
6. 转换后运行：
   `colcon build --packages-select racing_control --cmake-args -DBUILD_TESTING=ON`
7. 再运行：
   `colcon test --packages-select racing_control && colcon test-result --verbose --test-result-base build/racing_control`

## 注意事项

- 不要把 `saved_at`、`captured_at`、`twist`、`covariance` 等采集元数据写入正式 YAML。
- 不要依赖 `goal_004`、`goal_011` 这类采点名称判断 VLM 点；使用第几个路线点更稳定。
- 如果现场重新采点，只替换 YAML 中的点位参数，不需要改 C++ 流程代码。
- 如果要从停车拍照改成经过拍照，只改 `vlm_capture_mode` 和触发半径，点位格式不用变化。
