# 停机引导系统详细设计
## 1. 目标
项目：`App/ParkingSpaceGuide`
设备：
- 雷达：`Device/RsLidarDevice`
- 2D 相机：`Device/MvsDevice`
- LED 屏：`Device/LedDisplayDevice`，ModbusTCP
- 组播：`Nets/UDPClient`
功能点：
1. 标定
- 地面标定、停止线标定均调用算法接口
- 应用保存算法返回结果，失败时显示原因
2. 雷达
- 正常工作主检测设备；
- 低频找飞机，发现飞机后 10fps 检测。
3. 2D 相机
- 用于飞机目标检测，以及飞机停稳后的轮挡区域人员检测
4. 输出
- 检测结果更新 UI 结果列表、LED 显示、组播 JSON。
## 2. 输出结果
| 输出项 | 字段 | 单位 | 说明 |
| --- | --- | --- | --- |
| 选择机型 | `expectedModelType` | - | 操作员点击开始前选择的期望机型。 |
| 机型 | `modelType` | - | 算法识别结果；未识别成功时为“未知”。 |
| 机型匹配 | `modelMatched` | - | 实际识别机型、期望机型和置信度均通过校验时为 `true`。 |
| 细分机型校验能力 | `modelVerificationSupported` | - | 通用飞机检测模型不能区分 A320/B737 时为 `false`。 |
| 轮挡区域人员 | `personInChockRegion` | - | 裁剪后的轮挡 ROI 内是否检测到人员。 |
| 轮挡确认 | `chocksConfirmed` | - | 连续有效检测达到配置次数。 |
| 到停止线距离 | `distanceToStop` | mm | 未到线为正，到线为 0，越线为负。 |
| 机身偏转角 | `bodyYawAngle` | degree | 算法输出。 |
| 横向偏移 | `lateralOffset` | mm | 算法输出。 |
| 停机位 | `parkId` | - | 业务配置参数，不属于标定。 |
| 目标编号 | `targetId` | - | 业务配置或上位系统分配。 |
| 异常状态 | `hasException` | bool | 是否有异常；对应组播协议中的异常情况。 |
| 引导状态 | `guideState` | - | WAIT、TRACKING、SLOW、STOP、OK、TOOFAR、ERROR 等。 |
| 置信度 | `confidence` | - | 算法输出。 |
## 3. 坐标定义
- X 轴：横向，向右为正。
- Y 轴：垂向，向下为正。
- Z 轴：纵向，飞机运行方向为负方向。
- 引导中心线：由停止线标定结果定义，不固定为 `X=0`。
- 停止线：由停止线标定结果定义。
应用不计算坐标关系，只保存标定结果并传给算法接口。
## 4. 模块职责
| 模块 | 职责 |
| --- | --- |
| `ParkingSpaceGuidePresenter` | 设备初始化、调用算法接口、分发结果到 UI/LED/组播。 |
| `DetectPresenter` | 算法接口调用入口。 |
| `ConfigManager` | 加载、保存、页面修改配置。 |
| `RsLidarDevice` | 采集雷达点云。 |
| `MvsDevice` | 搜索并采集 2D 平面相机图像。 |
| `LedDisplayDevice` | 输出 LED 显示结果。 |
| `UDPClient` | 组播发送 JSON 检测结果。 |
数据流：
```text
RsLidarDevice -> 算法检测接口 -> 检测结果
MvsDevice -> 算法机型识别接口 -> modelType
检测结果 -> UI / LED / 组播 / 日志
```
## 5. 标定模式
原则：
- 标定算法由算法模块提供。
- 应用只负责采集数据、调用接口、显示结果、保存结果。
- `parkId` 是业务配置，不参与标定。
- 接口失败时只显示失败原因，不覆盖旧结果。
### 5.1 标定流程
```mermaid
%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart TD
A([进入标定]) --> B{设备状态}
B -- 异常 --> C[显示原因]
B -- 正常 --> E[加载地面标定参数]
E --> F[采集雷达点云]
F --> G[调用 CalibrateGround]
G --> H{地面标定结果}
H -- 成功 --> I[保存地面标定结果]
H -- 失败 --> J[显示失败原因]
```
### 5.2 地面标定
输入：
- 地面标定参数，至少包含采集帧数，默认建议 `N >= 10`。
- 多帧雷达点云。
输出：
- `groundCalibrationResult`
- `calibrationTime`
### 5.3 停机几何配置
当前版本直接配置调平坐标系中的停机点、引导线远点、引导范围、引导线过滤范围及机鼻到前轮距离，不保留旧中心线/停机线兼容结构。
## 6. 正常工作模式
### 6.1 工作流程
```mermaid
%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart TD
A([启动]) --> B{设备和标定检查}
B -- 异常 --> C[输出 ERROR]
B -- 缺标定 --> D[提示补做标定]
B -- 正常 --> E[进入待机]
E --> F[操作员可选 A320 / B737 或不选机型]
F --> G[点击开始]
G --> H[发布 WAIT 零值状态并锁定参数控件]
H --> I[按帧采集雷达点云]
I --> J[调用 planeLocalization 和引导状态计算]
J --> K{检测结果}
K -- 失败 --> L[显示原因并输出错误状态]
L --> I
K -- 成功 --> M{进入 25m 且尚未完成机型验证}
M -- 是 --> N[提交异步采图、ROI 裁剪和飞机检测任务]
M -- 否 --> O[使用点云引导结果]
N --> O
N -. 任务完成 .-> P[合并机型结果并更新 UI / LED / UDP / HTTP]
O --> P
P --> Q{飞机到位并稳定停止}
Q -- 否 --> I
Q -- 是 --> R[保持 STOP 并周期检测轮挡 ROI 人员]
R --> T{连续检测达到稳定次数}
T -- 否 --> I
T -- 是 --> U[发布 21 / CHOCK ON]
U --> S[停止检测并进入休眠]
S --> E
```
### 6.2 雷达
- 主检测设备。
- 点击开始即可进入检测；机型可选，未选择时以实际识别结果继续流程。
- 点击开始后由点云实测距离决定 WAIT、START、CAPTURE 和后续引导状态，不使用虚拟距离。
- 已有有效测量时，若当前帧的距离变化或横向偏移变化任一项超过对应配置阈值，则判为误检并忽略，状态机继续使用上一有效测量。
- 输出距离、偏移、偏角、异常状态、引导状态等结果。
### 6.3 2D 相机
- 使用 AAPGS 目标检测模型识别飞机和人员。
- 是否触发由算法检测接口返回，默认在距离不大于 25m 时最多验证两次。
- 飞机检测区域由 `roiX`、`roiY`、`roiWidth`、`roiHeight` 配置为归一化 ROI；相机原图先按 ROI 裁剪，`RecognizeModel2D` 只接收裁剪图像。
- 常规雷达、机型识别和人员检测结果均显示相机全图；机型模型只接收飞机 ROI，人员模型只接收轮挡 ROI，人员检测框转换回原图坐标后叠加到全图。
- 飞机采图、ROI 裁剪和模型推理在独立任务中执行，不占用雷达点云检测线程。任务未完成时的新机型识别触发只跳过本次提交，当前雷达帧仍正常完成定位和状态更新；任务完成后由检测循环合并结果。
- 操作员选择值保存为本次会话的 `expectedModelType`，不作为检测结果显示。
- 当前通用 COCO 模型检测到飞机时写入 `modelType=飞机`，并设置 `modelVerificationSupported=false`，不伪造 A320/B737 匹配结果；未来细分模型返回 A320/B737 时再执行精确匹配。
- 达到最大次数仍不一致时输出 `STOP+IDFAIL`，并显示算法返回原因。
- 飞机稳定停止后保持 `STOP`，按配置周期裁剪轮挡 ROI 并仅对裁剪图检测人员；ROI 内连续检测到人员达到稳定次数后发布 `CHOCK ON` 并结束会话。
### 6.4 输出
UI 结果列表字段：
- 时间
- `parkId`
- `targetId`
- `expectedModelType`
- `modelType`
- `modelMatched`
- `distanceToStop`
- `lateralOffset`
- `bodyYawAngle`
- 速度
- `guideState`
- `confidence`
更新规则：
- 当前目标按 `parkId + targetId` 更新。
- 不做每帧无限追加。
LED 按 0720 式样输出：
- 显示状态：1、2、5、6、7、8、10、15、16、17、20、21、22。
- 清屏状态：3、4、9、11、12、13、14、18、19、23、24。
- 白色行只清空 LED 动态区，不影响 UI、UDP 和 HTTP 的完整状态数据。
### 6.5 急停输入
- 板卡接口使用 `/sys/external_gpio/jwsioc_inout_gpio3` 配置方向，启动或故障重连时写入 `0` 设置为输入。
- 周期读取 `/sys/external_gpio/jwsioc_gpio3`，只接受 `0` 或 `1`。
- 急停采用常闭安全回路：正常时 I/O3 与 GND 闭合，读取 `0`；按下急停或线路断开时回路断开，读取 `1` 并锁存急停。
- 默认轮询周期为 10ms、消抖时间为 50ms。方向配置失败、电平文件不可读或内容非法时按急停输入不可用处理，停止检测并禁止重新开始。
- START 需要已点击开始且实测距离不大于 100m；CAPTURE 为 25m 至 80m；SLOW 为 15m 内且接近速度不小于 2m/s；STOP 容差为正负 0.1m；TOOFAR 为越线不小于 0.5m。
组播：
- 使用 JSON。
- 端口：`8800`。
- 雷达进入 10fps 后按检测结果输出，可配置限频。
- 检测失败或无结果也发送状态包。
## 7. 配置
```xml
...
```
配置页面需要支持修改：
- `parkId`
- `targetId`
- 组播参数
- LED 参数
- 雷达参数
- 相机参数
- 标定参数
- 工作模式参数
## 8. 算法接口
应用调用单帧定位算法，并在其输出上实现多帧停机流程状态机。
| 接口 | 输入 | 输出 |
| --- | --- | --- |
| `CalibrateGround` | 雷达点云、地面标定参数 | 成功标志、地面标定结果、失败原因 |
| `DetectAirplanePresence` | 雷达点云、配置参数 | 是否有飞机、阻挡/遮挡状态、失败原因 |
| `wd_planeLocalization` | 二维扫描线、地面调平、停机几何、聚类生长参数 | 距离、横向偏差、航向角、机鼻位置、错误码 |
| `DetectParkingSpaceGuide` | 雷达点云、帧时间、算法参数、上一帧状态 | 检测结果、完整引导状态、下一帧状态、是否需要机型识别 |
| `RecognizeModel2D` | 按飞机 ROI 裁剪后的 2D 图像、检测上下文 | 机型、置信度、失败原因 |
## 9. 异常处理
| 异常 | 处理 |
| --- | --- |
| 雷达断开 | 停止检测，LED/组播输出错误状态。 |
| 相机断开 | 雷达检测继续，机型识别不可用。 |
| 急停按下或线路断开 | 锁存紧急停止，停止当前检测；恢复闭合后仍需重新点击开始。 |
| 急停 sysfs 不可用 | 按失效保护处理，停止检测并禁止启动。 |
| LED 断开 | 检测和组播继续，UI 提示。 |
| 组播初始化失败 | 检测和 LED 继续，UI/日志提示。 |
| 地面标定缺失 | 禁止进入正常检测。 |
| 停止线标定缺失 | 禁止输出距离和 STOP/TOOFAR。 |
| 算法接口失败 | 显示失败原因，输出错误状态。 |
## 10. 验收
标定：
- 地面标定结果可保存和加载。
- 停止线标定结果可保存和加载。
- 标定失败显示原因，不覆盖旧结果。
正常工作：
- 初始化完成后保持待机，不自动开始算法检测。
- 操作员点击开始后按配置周期处理雷达点云；未选择机型时以实际识别结果完成流程。
- UI、LED、组播同步更新。
- 机型识别按算法触发。
- 25m 内按配置次数进行机型一致性验证，达到最大次数仍失败时进入 IDFAIL。
- START、CAPTURE、CENTER、SLOW、STOP、TOOFAR、IDFAIL、ERROR 等状态及 LED 清屏规则输出正确。