# 停机引导 ParkingSpaceGuide

ParkingSpaceGuide 使用一台平面相机、一台雷达和一块显示屏完成停机位引导。

当前硬件和输出方式：

- 相机：`Device/MvsDevice`
- 雷达：`Device/RsLidarDevice`
- 显示屏：`Device/LedDisplayDevice`
- 组播：`Nets/UDPClient`
- 2D 机型识别：`AppAlgo/AAPGS_model`（RK3588 Linux AArch64）

算法入口位于：

`ParkingSpaceGuideApp/Presenter/Src/DetectPresenter.cpp`

机型识别由雷达算法按距离触发，相机软触发取图后调用 AAPGS 分类模型，
当前支持 `A320` 和 `B737`。ARM DEB 将模型安装到
`/opt/rk3588-ai/models/model.yaml`，运行库安装到
`/opt/rk3588-ai/lib`。开发环境也会搜索可执行文件同级的
`AAPGS_model`；可通过环境变量覆盖：

- `AAPGS_MODEL_CONFIG`：模型 YAML 的完整路径
- `AAPGS_MODEL_ROOT`：AAPGS SDK 根目录
- `AAPGS_RUNTIME_LIBRARY`：`libyolo_runtime.so.2` 的完整路径

Windows 构建保留界面与业务流程，但不执行仅支持 RK3588 的 NPU 推理。

Windows 原生相机接口依赖海康 MVS Runtime。仓库中的
`MvCameraControl.Net.dll` 是 .NET 包装器，不能替代 C++ 程序需要的
`MvCameraControl.dll`。应运行
`Device/SDK/MVS/MVS_Win_STD_5.0.0_260417/MVS_STD_5.0.0_260417.exe`
安装 x64 Runtime 和驱动；典型 DLL 路径为
`C:/Program Files (x86)/Common Files/MVS/Runtime/Win64_x64/MvCameraControl.dll`。
Windows 运行目录还需要与构建类型匹配的 `HC_planeLocalization.dll`、
`baseAlgorithm.dll` 和 `opencv_world320.dll`（Debug 使用
`opencv_world320d.dll`）。

## 本地多帧仿真

程序可通过启动参数读取本地雷达点云和相机图片。初始化完成后，需要在界面点击“开始”，才会运行完整的停机引导处理与发布链路：

```text
ParkingSpaceGuideApp --simulate-dir <目录> [--sim-interval <毫秒>] [--sim-loop]
```

参数说明：

- `--simulate-dir <目录>`：仿真数据目录，别名为 `--sim-dir`。
- `--sim-interval <毫秒>`：每对“点云 + 图像”的检测周期，默认 `100` 毫秒；单帧处理超过该周期时，下一帧立即开始。
- `--sim-loop`：循环回放目录中的数据；未指定时只回放一轮，一轮结束后界面显示仿真完成。

程序启动时会把目录内的全部 TXT 点云和 BMP 图像加载到内存，但不会自动回放。点击“开始”后只读取内存数据进行检测；点击“停止”可中止回放。停止或单轮完成后再次点击“开始”，会从第一帧重新回放。
内存占用取决于全部点云转换为 `PointXYZI` 和全部 BMP 解码后的大小；内存不足或任一文件加载失败时，仿真初始化失败，无法开始回放。

仿真目录要求：

- 至少包含 2 个 `.txt` 雷达数据文件，程序按文件名中的数字自然顺序逐帧回放，例如 `LaserData_2.txt` 排在 `LaserData_10.txt` 前。
- TXT 使用 `Utils/CloudUtils` 的 `LaserDataLoader` 格式；坐标单位和坐标轴方向应与实时雷达输出一致（毫米，X 向右、Y 向下、Z 为纵向）。
- 至少包含 1 个 `.bmp` 平面相机图片。回放总帧数以 TXT 点云数量为准，第 `i` 个点云与第 `i % BMP数量` 张图片配对；BMP 较少时循环复用，BMP 较多时多出的图片不延长回放。

仿真数据仍进入正常检测与发布链路，因此界面结果与当前 BMP 预览、LED、UDP 和 HTTP 对接逻辑均会执行。UDP 广播默认未启用；需要 UDP 输出时，请在 `ParkingSpaceGuideConfig/config/config.xml` 中将 `UdpBroadcast` 的 `enabled` 设置为 `true`。

例如仿真数据位于 `D:/Simulation/ParkingSpaceGuide`：

```text
ParkingSpaceGuideApp --simulate-dir D:/Simulation/ParkingSpaceGuide
```

循环回放并将检测周期调整为 200 毫秒：

```text
ParkingSpaceGuideApp --sim-dir D:/Simulation/ParkingSpaceGuide --sim-interval 200 --sim-loop
```

相对目录以程序启动时的当前工作目录为基准，也可以传入绝对目录。

仿真模式不按文件序号伪造状态。每帧点云进入 `planeLocalization`，输出距停机点、横向偏差、航向角和机鼻位置；应用再根据多帧速度、连续稳定帧、丢失帧及配置阈值计算 `WAIT -> START -> CAPTURE -> TRACKING -> CENTER/AZIMUTH -> APPROACH -> SLOW -> STOP -> OK`，并处理越位、提前停止、目标丢失、超速和系统错误。

算法参数页面按结构体分为独立 Tab：飞机停机几何、地面调平、聚类生长、引导判定、流程判定和机型识别。当前版本不保留旧中心线/停机线配置兼容逻辑。

文档：

- 详细设计：`详细设计.md`
- 对接协议：`停机引导对接协议.md`

LED 输出当前从 `ledDisplay.startAddress` 开始写 8 个保持寄存器：

1. valid
2. guideCode
3. distance high word
4. distance low word
5. lateralOffset high word
6. lateralOffset low word
7. angle high word
8. angle low word