GrabBag/App/ParkingSpaceGuide/Doc/ParkingSpaceGuide.md

# 停机引导 ParkingSpaceGuide

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

当前硬件和输出方式：

- 相机：`Device/MvsDevice`
- 雷达：`Device/RsLidarDevice`
- 显示屏：`Device/LedDisplayDevice`
- 组播：`Nets/UDPClient`
- 2D 飞机/人员检测：`AppAlgo/AAPGS_model`（RK3588 Linux AArch64）

算法入口位于：

`ParkingSpaceGuideApp/Presenter/Src/DetectPresenter.cpp`

飞机目标检测由雷达算法按距离触发。相机原图按机型识别参数中的归一化 ROI 裁剪，模型只接收 ROI 图像，但界面始终显示相机原始全图。采图、裁剪和推理在独立任务中执行，不阻塞雷达点云检测。已有机型任务尚未完成时，只跳过本次机型识别提交，雷达帧仍正常处理。飞机停稳后，相机按配置周期检测轮挡区域内的人员；人员模型同样只接收裁剪后的轮挡 ROI，检测框映射回全图显示。
当前通用 COCO 检测模型只能识别“飞机”，不能区分 `A320` 和 `B737`，因此不会把选择机型伪装成检测结果。
ARM DEB 将模型安装到
`/opt/rk3588-ai/models/yolov8n/yolov8n.yaml`，运行库安装到
`/opt/rk3588-ai/lib`。开发环境也会搜索可执行文件同级的
`AAPGS_model`；可通过环境变量覆盖：

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

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 -> CHOCK ON`。停稳后持续显示 STOP，轮挡 ROI 裁剪图连续检测到人员达到配置次数后发布状态 21，随后结束会话并进入休眠。

机型选择不是启动必填项。未选择机型时可直接点击“开始”，流程使用实际二维识别结果，不执行期望机型一致性比对。流程判定参数中的 `distanceChangeThreshold` 和 `lateralOffsetChangeThreshold` 分别限制相邻有效测量的距离变化和横向偏移变化；任一项超阈值时当前帧按误检忽略，并保留上一有效状态。

算法参数页面按结构体分为独立 Tab：飞机停机几何、地面调平、聚类生长、引导判定、流程判定、机型识别和人员检测。机型识别 Tab 可配置飞机 ROI 的 `X/Y/宽度/高度`，均使用图像宽高归一化的 `0~1` 坐标，且区域必须完整落在图像内。当前版本不保留旧中心线/停机线配置兼容逻辑。

文档：

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

## 远程显示端 ParkingSpaceGuideView

`ParkingSpaceGuideView` 是独立桌面程序。它持续使用 UDP 搜索局域网内的 `ParkingSpaceGuideApp`，发现后通过 ZeroMQ 选择机型、开始或停止引导，并订阅完整检测状态。服务端只增加后台网络服务，不修改 `ParkingSpaceGuideApp` 现有页面。

View 左侧约 2/3 区域使用 `QPainter` 按 0720 状态式样实时绘制引导屏，放大时不依赖状态位图；右侧约 1/3 显示机型选择、控制按钮、状态含义、下一步动作和测量结果。选择机型与算法检测机型分开显示，选择值不会作为检测结果回填。

ARM AArch64 可按独立目标构建和打包：

```text
./GrabBagPrj/buildArmPrj.sh ParkingSpaceGuideView
./GrabBagPrj/project_pkg_desktop.sh ParkingSpaceGuideView
```

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