GrabBag/App/DroneScrewbolt/Doc/project_design.md

DroneScrewbolt 项目设计文档

1. 项目定位

DroneScrewbolt 采用远端服务端和地面端控制应用分离的结构。

• DroneScrewServer：部署在远端板卡，直接连接双目相机，负责采集、推流、算法检测和 ZMQ 协议服务。
• WDRemoteReceiver：地面端通信库，封装设备发现、控制命令、检测结果订阅和原始图像订阅。
• DroneScrewCtrlApp：地面端用户应用，负责连接远端服务、切换工作模式、展示图像和检测结果，并提供参数配置入口。

服务端是算法和设备控制中心，地面端不直接操作相机和算法，只通过 WDRemoteReceiver 调用服务端能力。

2. 工作模式

2.0 模式参数总表

模式	控制命令	detectMode	相机降采样	采集/处理帧率	图像输出	压缩参数	视频链路	result 输出	地面端显示	测试入口
距离检测(RTMP/RTSP)	start_stream / stop_stream	不使用	关闭 binning，使用 DecimationHorizontal/Vertical=4x4 相机端抽样下采样；4096x3000 输出 1024x750；曝光直接使用配置曝光	30fps	单路实时视频，默认 1024x750	H.264，Rtsp.bitrateKbps 默认 4096Kbps，GOP 固定为 fps/2，约 0.5s	DroneScrewServer 内部推 rtmp://127.0.0.1:1935/live/dronescrew，地面端拉 rtsp://<server-ip>:8554/live/dronescrew	DetectDistance 持续发布 boxes/distances，协议距离单位为 mm	DroneScrewCtrlApp 拉 RTSP，测距结果 overlay 和列表按 m 显示	Test\WDRemoteReceiverTest 的 LiveStream
精准检测(双图 raw)	set_detect_mode=binocular 后 start / stop	binocular	1x1/关闭 binning	2fps	左图 + 右图，全分辨率 raw	zlib 无损压缩，失败时 raw 兜底	关闭 RTSP/RTMP	Detect 精准检测结果持续发布	用于联调/测试双目 raw 链路；正式 DroneScrewCtrlApp 默认不进入该传输方式	Test\WDRemoteReceiverTest 选择 binocular 后 Start
精准检测(单图 raw)	set_detect_mode=mono 后 start / stop	mono	1x1/关闭 binning	2fps	左图，右图为空；4096x3000 输入压缩后约 1024x750	固定有损压缩：Mono8 先按 1/4 缩放，再 MJPEG quality=25；不动态算带宽、不跳帧	关闭 RTSP/RTMP	Detect 精准检测结果持续发布，result 坐标系固定为算法输入原图尺寸	DroneScrewCtrlApp 使用压缩后左图显示，raw/result 按 frameId 对齐后按原图坐标比例叠框，图像中只标框和序号，列表显示每个目标	Test\WDRemoteReceiverTest 选择 mono 后 Start

程序	定位	应覆盖的模式
Test\WDRemoteReceiverTest	通信库和模式链路测试工具	距离检测、精准检测双图 raw、精准检测单图 raw
DroneScrewCtrlApp	正式地面端用户程序	距离检测(RTSP + result) 和精准检测单图 raw(MJPEG + result)

2.1 距离检测模式

距离检测模式用于实时观察和距离检测。

服务端行为：

• 双目相机关闭 binning，固定使用 DecimationHorizontal/Vertical=4x4 相机端抽样下采样采集。
• Decimation 是相机输出阶段的像素抽样降采样，不是压缩，也不是求平均/求和合并；它会改变相机输出分辨率，4096x3000 在 4x4 decimation 后输出 1024x750。
• MVS SDK 自带 Features.xml 中未提供 BinningMode、Average、Sum 这类 binning 合并模式选择；已确认的 DecimationHorizontal/Vertical 描述为 image sub-sampling，因此距离模式固定使用 decimation 来保持与精准检测相同的曝光语义。
• 距离检测和精准检测使用同一个配置曝光值；运行中通过 set_exposure 修改曝光时也直接按当前配置曝光下发，不再按 binning 倍率做 /16 换算。
• 当前设计帧率为 30fps。
• 现场双目相机分别连接两个独立 USB 控制器；1024x750 Mono8 30fps 单路原始数据约 23MB/s（约 184Mbps），两路分摊到独立 USB2.0 控制器后按 30fps 设计。该约束不适用于两台相机共用同一个 USB2.0 root hub 的接法。
• 算法走 DetectDistance 距离检测 pipeline。
• 启动实时视频链路：服务端内部 RTMP 推到本机 mediamtx，地面端通过 RTSP 拉取配置指定的单路相机画面。
• 同时通过 ZMQ result 通道发布距离检测结果。

地面端行为：

• 通过 RTSP 拉流显示实时画面。
• 同时订阅 ZMQ result，接收距离检测结果。
• result 中的 boxes/distances 用于显示检测框和距离信息；协议内距离仍以 mm 保存，地面端距离检测 UI 按 m 显示。
• 该模式不依赖 ZMQ raw 图像通道显示画面。

设计要求：

• 距离检测模式必须同时具备 RTSP 拉流和 result 订阅。
• 地面端进入距离检测模式时不能停止 result 订阅。
• 服务端 start_stream 不能只被理解为“单纯推流”，它代表“decimation 距离检测 + 实时推流”。

2.2 精准螺栓检测模式

精准螺栓检测模式用于高分辨率螺栓检测。

服务端行为：

• 双目相机关闭 binning，使用原始分辨率采集。
• 当前设计帧率为 2fps。
• 算法走 Detect 精准检测 pipeline。
• 停止实时视频链路。
• 通过 ZMQ raw 图像通道发布图像。
• 通过 ZMQ result 通道发布检测框和距离结果。

地面端行为：

• 不拉 RTSP。
• 订阅 ZMQ raw 图像，用 raw 左目图作为显示画面。
• 订阅 ZMQ result，用检测结果叠加检测框并展示列表。正式地面端按最新帧刷新结果列表：精准检测显示每个目标，距离检测显示最新测距结果。
• raw 图像和 result 必须按 frameId 对齐后再叠加；单图 raw 显示图为压缩后尺寸，但 result 坐标系保持算法输入原图尺寸，由地面端按比例缩放绘制。
• 地面端绘制时必须把已经匹配的 raw/result 成对送入绘制队列，不能在绘制线程再读取“最新结果”；框坐标只按 result 的 imageWidth/imageHeight 到当前 QImage 像素尺寸缩放，QGraphicsView 的 fitInView 只负责最终显示缩放。
• 默认可使用 detectMode=mono，只传左目 raw 图以降低网络带宽；算法内部仍使用服务端双目输入。

设计要求：

• detectMode 只影响 raw 图像传输内容，不代表算法变为单目。
• 精准检测模式启动后应持续检测，不应只处理一帧或两帧后停止。

2.3 检测图像保存

服务端进入检测状态后，必须把进入算法的左右图像对异步保存到本地磁盘。保存线程独立于检测线程，检测线程只负责深拷贝图像并放入保存队列，PNG 编码和写盘由保存线程完成。

目录规则：

• 根目录固定为 /home/cat。
• 二级目录为启动当天日期，格式 yyyyMMdd。
• 三级目录为当前检测模式：距离检测为 distance，精准单图 raw 为 precision_mono，精准双图 raw 为 precision_binocular。
• 文件名按本轮检测序号从 1 开始递增：leftImage_N.png、rightImage_N.png。

示例：

• /home/cat/20260629/distance/leftImage_1.png
• /home/cat/20260629/distance/rightImage_1.png

保存失败或队列满时只记录日志，不允许阻塞检测线程或导致检测流程退出。

3. 通信通道

通道	默认端口	模式	用途
UDP discovery	5554	广播/应答	地面端搜索 DroneScrewServer
ZMQ control	5555	REQ/REP	start/stop/open/get_info/参数设置
ZMQ result	5556	PUB/SUB	检测结果 boxes/distances
ZMQ raw	5557	PUB/SUB	精准检测模式下的 raw 图像
RTMP publish	1935	FFmpeg/FLV	DroneScrewServer 推到本机 mediamtx 的内部入口
RTSP pull	8554	RTSP/TCP	地面端和 VLC 从 mediamtx 拉取距离检测实时画面

3.1 实时推流设计

实时推流只属于距离检测模式，也就是 start_stream 对应的 LiveStream 状态。它不是单独的视频功能，而是和 4x4 decimation 采集、DetectDistance 距离检测、result 发布一起启动。

服务端推流链路：

1. start_stream 到达 DroneScrewServer。
2. 服务端停止精准检测相关状态，配置相机为距离检测模式：binning=1x1、decimation=4x4，默认 30fps。
3. 服务端启动单路实时画面编码，输入为 Mono8，缩放到配置尺寸，转换为 NV12。
4. CVrFFMediaPusher 使用 Rockchip MPP 编码 H.264，码率由 Rtsp.bitrateKbps 配置，默认 4096Kbps；GOP 按当前 fps 的一半设置，30fps 时约 0.5s，减少新客户端等待关键帧的时间。
5. 服务端内部推流地址固定为 rtmp://127.0.0.1:1935/live/dronescrew。
6. mediamtx 接收 RTMP publish，并对外提供 RTSP 拉流。
7. 对外拉流地址通过 discovery/get_info/start_stream 返回给地面端，格式为 rtsp://<板子IP>:8554/live/dronescrew。

端口边界：

• 1935 是服务端内部 RTMP publish 端口，只给 DroneScrewServer 推到本机 mediamtx 使用。
• 8554 是客户端 RTSP pull 端口，DroneScrewCtrlApp、VLC、ffplay 都必须拉这个端口。
• 配置文件 <Rtsp port="..."> 表示对外 RTSP pull 端口，不表示内部 RTMP publish 端口。
• 如果旧配置误写成 1935，服务端应警告并自动改用 8554 作为对外拉流端口。

mediamtx 职责：

• 监听 rtmpAddress: :1935，接收服务端内部 RTMP 推流。
• 监听 rtspAddress: :8554，给地面端提供 RTSP 拉流。
• 路径使用 /live/dronescrew，不需要为该路径预先创建固定配置，按 publisher 动态建立。

地面端拉流链路：

1. DroneScrewCtrlApp 通过 WDRemoteReceiver 发送 start_stream。
2. WDRemoteReceiver 启动 result 订阅，关闭 raw 订阅。
3. start_stream 成功后，DroneScrewCtrlApp 读取服务端返回或 get_info 返回的 rtsp 字段。
4. 拉流地址以服务端返回为准；如果服务端未返回地址，则用配置中的 serverIp + rtspPort + rtspPath 生成兜底地址。
5. 地面端必须把旧地址 rtmp://...:1935/... 规范化为 rtsp://...:8554/...。
6. 如果服务端返回 0.0.0.0、127.0.0.1 或 localhost，地面端必须替换为发现到的服务端 IP。
7. start_stream 成功返回后，认为服务端 RTSP 链路已经建立；DroneScrewCtrlApp 固定多次打开本地 RTSP puller，默认最多 5 次、间隔 500ms，每次 open/read 超时按 5s 处理。成功标准不是 puller Start() 返回，而是收到并解码出第一帧 RTSP 图像；探测参数为 probesize=262144、analyzeduration=500000us、fflags=nobuffer、max_delay=0、reorder_queue_size=0。
8. 本地 RTSP puller 多次启动或首帧等待全部失败时，只提示“服务端已开流但本地拉流未启动”，不能自动发送 stop_stream；服务端 LiveStream 状态必须保持运行，便于用户用 VLC/ffplay 或网络工具继续定位 8554 拉流问题。

低延迟约束：

• 服务端 RTMP/FLV muxer 使用 flush packets、零 interleave delay，并且单视频流直接 av_write_frame，避免 muxer 为多流交织排序引入等待。
• 服务端每个 IDR 内嵌 SPS/PPS，GOP 约 0.5s，降低 VLC/DroneScrewCtrlApp 中途接入时等待关键帧的时间。
• 地面端点击“开始实时显示”后必须立即弹出“正在拉流，请稍候...”提示框，同时禁用开始/检测按钮；StartLiveStream() 返回后关闭提示框，并按结果切换 UI 状态。
• 地面端收到第一帧 RTSP 后显示“RTSP 已出图”，用于区分“服务端已开流”和“画面已经解码显示”两个阶段。

现场日志判定：

• FFMediaPusher: init done (...) 表示编码器和封装器初始化成功。
• [RTMP] pusher init ok ... push=rtmp://127.0.0.1:1935/live/dronescrew pull=rtsp://<板子IP>:8554/live/dronescrew 表示内部推流地址和外部拉流地址已经拆清。
• FFMediaPusher: connected to mediamtx, header written 表示服务端已经连上 mediamtx，RTMP 头已写入。
• [LIVE] started ... url=rtsp://<板子IP>:8554/live/dronescrew 表示 LiveStream 状态已启动。
• start_stream 返回 ok=true 且 rawImagePublish=false 是正确状态，距离检测模式显示走 RTSP，不走 raw。
• start_stream 成功返回后如果地面端多次打开 RTSP 或等待首帧仍失败，应按真实错误处理，不自动发送 stop_stream 关闭服务端 LiveStream；优先检查拉流 URL、mediamtx 和 8554 端口。
• 同尺寸推流时服务端直接拷贝 Mono8 到 NV12 Y 平面，不调用 RGA；只有输入输出尺寸不一致时才尝试 RGA 缩放，失败后回退 CPU 缩放继续推流。

VLC 或地面端提示“输入无法被打开”时，优先检查：

1. 拉流 URL 是否为 rtsp://<板子IP>:8554/live/dronescrew，不能是 rtsp://<板子IP>:1935/...。
2. mediamtx 服务是否运行，且 rtspAddress: :8554、rtmpAddress: :1935 是否被监听。
3. 服务端是否打印 connected to mediamtx, header written。
4. 服务端是否已有相机帧进入 pushRtspFrame，日志中的 rtsp_push 是否增长、rtsp_fail 是否增长。
5. 网络侧是否允许地面端访问板卡 8554 端口。

4. 控制命令

核心命令：

• open：按 machineCode 打开指定服务端并返回服务信息。
• get_info：读取服务端运行状态、相机参数、算法参数和端口信息。
• start_stream：进入距离检测模式，开启 decimation 4x4 下采样、RTSP 推流和 result 发布。
• stop_stream：退出距离检测模式，停止推流和距离检测。
• start：进入精准螺栓检测模式，关闭 binning 和 decimation，开启 raw/result 发布。
• stop：退出精准螺栓检测模式。
• single：执行单次精准检测。
• set_detect_mode：设置精准检测模式下 raw 图像传输方式，支持 mono/binocular。
• set_exposure / set_gain：下发相机曝光和增益。
• set_algo_params：下发算法参数。
• swap_cameras：交换左右相机角色。

5. 结果数据

检测结果由服务端通过 topic=result 发布，地面端由 WDRemoteReceiver 解析为 WDRemoteDetectionFrame。

主要字段：

• frameId：帧号。
• timestampUs：时间戳。
• imageWidth / imageHeight：检测坐标对应的图像尺寸。
• success：算法是否成功。
• errorCode：错误码或算法拒绝原因。
• message：详细消息。
• boxes：检测框列表。
• distances：距离结果列表，协议单位为 mm；距离检测 UI 显示时换算为 m，精准螺杆/螺栓相关尺寸和坐标保持原图坐标语义。

距离检测模式和精准检测模式都应发布 result。区别在于图像显示来源不同：距离检测模式显示 RTSP，精准检测模式显示 raw。

6. 原始图像数据

raw 图像使用 topic=raw 发布，主要服务于精准检测模式。

当前协议：

• payload = WDRemoteBinocularRawImageHeader + leftData + rightData。
• magic 为 BIWI。
• 支持 raw、png、mjpeg、zlib 压缩标识。
• 精准检测双图 raw 使用 zlib 无损压缩，左右图同时发送；zlib 失败时回退 raw。
• 精准检测单图 raw 使用固定有损压缩比例：Mono8 左图先按 1/4 缩放，再用 MJPEG quality=25 编码；不按运行时 payload 动态计算带宽，不因为带宽丢 raw 帧。
• 单图 raw 的 result 仍使用算法原始图像坐标，服务端发布 result 前把 imageWidth/imageHeight 固定为算法输入左图尺寸，地面端按显示图尺寸做比例叠框。
• MJPEG 编码失败时可回退 zlib/raw，保证图像链路不断。
• detectMode=mono 时 right 字段为空，仅传 left。

7. 组件职责边界

DroneScrewServer

负责：

• 相机连接、左右角色、曝光/增益、binning/decimation、采集频率。
• 两种 pipeline 切换：DetectDistance 和 Detect。
• 实时视频链路：RTMP publish 到本机 mediamtx，并向地面端发布 RTSP pull URL。
• ZMQ control/result/raw 服务。
• UDP discovery。
• 算法参数加载和更新。

不负责：

• 地面端 UI 状态。
• 用户交互流程。

WDRemoteReceiver

负责：

• 搜索和连接服务端。
• 封装控制命令。
• 订阅 result。
• 订阅 raw。
• 解析服务端 JSON 和 raw payload。
• 通过回调把数据交给业务层。

不负责：

• UI 显示。
• 算法业务判断。
• 画框叠加。

DroneScrewCtrlApp

负责：

• 用户操作入口。
• 服务端连接状态展示。
• 距离检测模式：RTSP 画面 + result 距离结果展示。
• 精准检测模式：raw 图像 + result 检测框展示。
• 曝光、增益、算法参数配置。
• 单次检测测试。

不负责：

• 直接操作相机。
• 直接调用算法。
• 解析底层 ZMQ 协议细节。

8. 推荐状态流

8.1 地面端启动

1. 创建 WDRemoteReceiver。
2. 注册 event/result/raw 回调。
3. UDP 搜索服务端。
4. 通过 machineCode open。
5. get_info 更新 UI 参数。

8.2 进入距离检测模式

1. 地面端停止精准检测模式相关 raw 订阅。
2. 地面端保持或启动 result 订阅。
3. 地面端发送 start_stream。
4. 服务端开启 decimation 4x4 下采样采集。
5. 服务端启动 RTSP 推流。
6. 服务端持续执行 DetectDistance。
7. 地面端拉 RTSP 显示画面。
8. 地面端接收 result 显示距离检测结果。

8.3 进入精准螺栓检测模式

1. 地面端停止 RTSP 拉流。
2. 地面端发送 stop_stream。
3. 地面端设置 detectMode，默认 mono。
4. 地面端启动 result/raw 订阅。
5. 地面端发送 start。
6. 服务端关闭 binning 和 decimation，停止 RTSP 推流。
7. 服务端持续执行 Detect。
8. 服务端发布 raw/result。
9. 地面端用 raw 图像叠加 result 检测框。

8.4 停止

距离检测模式停止：

• 地面端发送 stop_stream。
• 服务端停止 RTSP 推流和距离检测。

精准检测模式停止：

• 地面端发送 stop。
• 服务端停止精准检测线程。
• 地面端停止 raw/result 订阅。

全部停止：

• 地面端释放 RTSP puller。
• 发送 stop。
• 发送 stop_stream。

9. 实现约束

• 两种模式互斥，不能同时启动 RTSP 距离检测和 raw 精准检测。
• 服务端算法始终使用双目输入。
• detectMode=mono 只减少地面端 raw 图像传输量。
• 距离检测模式必须订阅 result，否则只能看到画面，看不到距离检测结果。
• 精准检测模式依赖 raw 图像显示，不依赖 RTSP。
• 服务端开始检测后应持续处理最新有效帧；相机不同步时应使用最新缓存帧继续推进，不能因为 ready 标志被清空而停住。

10. 状态机约束

10.1 服务端状态

服务端只允许三种外部可见状态：

状态	RTSP	raw PUB	result PUB	算法 pipeline	相机降采样
Idle	关闭	关闭	无业务结果	无	精准默认配置：binning=1x1, decimation=1x1
LiveStream	开启	关闭	持续发布	DetectDistance	binning=1x1, decimation=4x4
Detection	关闭	开启	持续发布	Detect	binning=1x1, decimation=1x1

合法转换：

• Idle -> LiveStream：收到 start_stream。
• Idle -> Detection：收到 start。
• LiveStream -> Idle：收到 stop_stream。
• Detection -> Idle：收到 stop。
• LiveStream -> Detection：必须先 stop_stream 成功，再 start 成功。
• Detection -> LiveStream：必须先 stop 成功，再 start_stream 成功。

非法或无效转换：

• LiveStream 状态下收到 start，应返回模式冲突或由调用方先 stop_stream。
• Detection 状态下收到 start_stream，应返回模式冲突或由调用方先 stop。
• LiveStream 状态下收到 stop 不应关闭距离检测结果链路。
• Detection 状态下收到 stop_stream 不应关闭精准检测线程。

10.2 WDRemoteReceiver 本地状态

WDRemoteReceiver 使用 Idle / LiveStream / Detection 记录最后一次已确认的远端模式：

本地状态	result 订阅	raw 订阅	地面端图像来源
Idle	关闭	关闭	无
LiveStream	开启	关闭	RTSP puller
Detection	开启	开启	ZMQ raw

状态推进规则：

• 只有控制命令返回成功后才更新本地状态。
• 停旧模式失败时保留旧状态，不能提前置为 Idle。
• 旧模式已确认停止，但新模式启动或订阅失败时，必须清理已打开订阅并进入 Idle。
• StopWork 只在停止当前活跃模式成功时关闭订阅并进入 Idle；停止非当前模式不能破坏当前模式的订阅。
• Disconnect 必须关闭 result/raw 订阅并进入 Idle。