GrabBag/App/ParkingSpaceGuide/Doc/详细设计.md

停机引导系统详细设计

1. 目标

项目：App/ParkingSpaceGuide

设备：

• 雷达：Device/RsLidarDevice
• 2D 相机：Device/MvsDevice
• LED 屏：Device/LedDisplayDevice，ModbusTCP
• 组播：Nets/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 检测结果。

数据流：

RsLidarDevice -> 算法检测接口 -> 检测结果
MvsDevice     -> 算法机型识别接口 -> modelType
检测结果      -> UI / LED / 组播 / 日志

5. 标定模式

原则：

• 标定算法由算法模块提供。
• 应用只负责采集数据、调用接口、显示结果、保存结果。
• parkId 是业务配置，不参与标定。
• 接口失败时只显示失败原因，不覆盖旧结果。

5.1 标定流程

%%{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 工作流程

%%{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. 配置

<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 等状态输出正确。