# 停机引导系统详细设计

## 1. 目标

项目：`App/ParkingSpaceGuide`

设备：

- 雷达：`Device/RsLidarDevice`
- 2D 相机：`Device/MvsDevice`
- LED 屏：`Device/LedDisplayDevice`，ModbusTCP
- 组播：`VrNets/UDPClient`

功能点：

1. 标定
- 地面标定、停止线标定均调用算法接口
- 应用保存算法返回结果，失败时显示原因
2. 雷达
- 正常工作主检测设备；
- 低频找飞机，发现飞机后 10fps 检测。
3. 2D 相机
- 只用于机型识别
4. 输出
- 检测结果更新 UI 结果列表、LED 显示、组播 JSON。

## 2. 输出结果

| 输出项 | 字段 | 单位 | 说明 |
| --- | --- | --- | --- |
| 机型 | `modelType` | - | 算法识别结果；未识别成功时为“未知”。 |
| 到停止线距离 | `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 -- 正常 --> D{选择标定类型}

    D -- 地面标定 --> E[加载地面标定参数]
    E --> F[采集雷达点云]
    F --> G[调用 CalibrateGround]
    G --> H{地面标定结果}
    H -- 成功 --> I[保存地面标定结果]
    H -- 失败 --> J[显示失败原因]

    D -- 停止线标定 --> K[检查地面标定结果]
    K --> L{是否有地面标定}
    L -- 无 --> M[提示先做地面标定]
    L -- 有 --> N[加载地面标定结果]
    N --> O[输入停止线/中心线信息]
    O --> P[调用 CalibrateStopLine]
    P --> Q{停止线标定结果}
    Q -- 成功 --> R[保存停止线标定结果]
    Q -- 失败 --> S[显示失败原因]
```

### 5.2 地面标定

输入：

- 地面标定参数，至少包含采集帧数，默认建议 `N >= 10`。
- 多帧雷达点云。

输出：

- `groundCalibrationResult`
- `calibrationTime`

### 5.3 停止线标定

前提：
- 现场提供停止线、中心线或测量信息。

输入：

- `groundCalibrationResult`
- 停止线/中心线现场输入信息

输出：

- `stopLineCalibrationInput`
- `stopLineCalibrationResult`
- `countdownStartDistance`
- `modelVerifyDistance = 12000mm`

## 6. 正常工作模式

### 6.1 工作流程

```mermaid
%%{init: {"flowchart": {"curve": "linear"}} }%%
flowchart TD
    A([启动]) --> B{设备和标定检查}
    B -- 异常 --> C[输出 ERROR / STOPSBU]
    B -- 缺标定 --> D[提示补做标定]
    B -- 正常 --> E[进入待机]

    E --> F[低频采集雷达点云]
    F --> G[调用飞机存在检测接口]
    G --> H{飞机存在检测结果}
    H -- 无飞机 --> F
    H -- 阻挡/遮挡 --> I[输出 GateBlocked / ViewBlocked]
    I --> F
    H -- 有飞机 --> J[进入 10fps 检测]

    J --> K[10fps 采集雷达点云]
    K --> L[调用 DetectParkingSpaceGuide]
    L --> M{检测结果}
    M -- 失败 --> N[显示原因并输出错误状态]
    N --> K
    M -- 成功 --> O{是否需要机型识别}
    O -- 是 --> P[采集 2D 图像并调用识别接口]
    O -- 否 --> Q[使用检测结果]
    P --> R[更新 UI / LED / 组播]
    Q --> R
    R --> K
```

### 6.2 雷达

- 主检测设备。
- 无飞机时低频检测。
- 发现飞机后 10fps 检测。
- 输出距离、偏移、偏角、异常状态、引导状态等结果。

### 6.3 2D 相机

- 只用于机型识别。
- 是否触发由算法检测接口返回。
- 成功后更新 `modelType`。
- 失败时显示算法返回原因。

### 6.4 输出

UI 结果列表字段：

- 时间
- `parkId`
- `targetId`
- `modelType`
- `distanceToStop`
- `lateralOffset`
- `bodyYawAngle`
- 速度
- `guideState`
- `confidence`

更新规则：

- 当前目标按 `parkId + targetId` 更新。
- 不做每帧无限追加。

LED 显示：

- WAIT
- TRACKING
- SLOW
- STOP
- OK
- TOOFAR
- IDFAIL
- VIEWBLOCKED
- GATEBLOCK
- ERROR
- STOPSBU

组播：

- 使用 JSON。
- 端口：`8800`。
- 雷达进入 10fps 后按检测结果输出，可配置限频。
- 检测失败或无结果也发送状态包。

## 7. 配置

```xml
<Business parkId="P01"
          targetId="T001"/>

<Calibration>
  <Ground enabled="true"
          frameCount="10"
          result="算法返回的地面标定结果"/>
  <StopLine input="现场输入的停止线和中心线信息"
            result="算法返回的停止线和中心线标定结果"
            countdownStartDistance="30000"
            modelVerifyDistance="12000"/>
</Calibration>

<WorkMode airplaneProbeIntervalMs="1000"
          trackingFps="10"
          uiUpdateIntervalMs="200"
          udpOutputIntervalMs="100"/>

<UdpBroadcast enabled="false"
              address="239.255.0.1"
              port="8800"/>
```

配置页面需要支持修改：

- `parkId`
- `targetId`
- 组播参数
- LED 参数
- 雷达参数
- 相机参数
- 标定参数
- 工作模式参数

## 8. 算法接口

应用不实现算法，只对接接口。

| 接口 | 输入 | 输出 |
| --- | --- | --- |
| `CalibrateGround` | 雷达点云、地面标定参数 | 成功标志、地面标定结果、失败原因 |
| `CalibrateStopLine` | 地面标定结果、停止线/中心线输入 | 成功标志、停止线标定结果、失败原因 |
| `DetectAirplanePresence` | 雷达点云、配置参数 | 是否有飞机、阻挡/遮挡状态、失败原因 |
| `DetectParkingSpaceGuide` | 雷达点云、2D 图像、标定结果、工作参数、上一帧算法状态 | 检测结果、引导状态、下一帧算法状态、是否需要机型识别 |
| `RecognizeModel2D` | 2D 图像、检测上下文 | 机型、置信度、失败原因 |

## 9. 异常处理

| 异常 | 处理 |
| --- | --- |
| 雷达断开 | 停止检测，LED/组播输出错误状态。 |
| 相机断开 | 雷达检测继续，机型识别不可用。 |
| LED 断开 | 检测和组播继续，UI 提示。 |
| 组播初始化失败 | 检测和 LED 继续，UI/日志提示。 |
| 地面标定缺失 | 禁止进入正常检测。 |
| 停止线标定缺失 | 禁止输出距离和 STOP/TOOFAR。 |
| 算法接口失败 | 显示失败原因，输出错误状态。 |

## 10. 验收

标定：

- 地面标定结果可保存和加载。
- 停止线标定结果可保存和加载。
- 标定失败显示原因，不覆盖旧结果。

正常工作：

- 无飞机时低频检测。
- 发现飞机后进入 10fps 检测。
- UI、LED、组播同步更新。
- 机型识别按算法触发。
- 12m 前未完成机型验证时进入 IDFAIL。
- STOP、OK、TOOFAR、SLOW、ERROR 等状态输出正确。