Add H.264 inference session recording and replay

README.md

@@ -96,3 +96,40 @@ NPP 用于 UYVY 转换、YOLO 缩放填充、RTMW 仿射裁剪；CUDA 用于通
 相机超时回归测试：`./tests/run_camera_timeout.sh`；加 `--wall-clock` 验证默认 6 次超时约 12 秒。测试直接编译实际相机代码，使用模拟采集和转换器，无需摄像头、GPU 或 OpenCV；不覆盖视频回放路径。
 
 板端真实摄像头 / TensorRT 恢复与停止测试记录见 [Orin 测试报告](tests/ORIN_TEST_REPORT.md)。
+
+## 推理过程录制与视频回灌
+
+当前 `inference-only` 分支支持 H.264/MP4 会话；默认关闭，不再为会话逐帧保存图片。
+
+```bash
+# 录制实际完成推理的帧，Ctrl+C / SIGTERM 正常停止并封装视频
+./run_camera.sh --record-session output/sessions/drive-001
+
+# 视频解码后重新运行 YOLO、RTMW、融合与风险推理；文件结束自动退出
+./run_camera.sh --replay-session output/sessions/drive-001 --save-results
+
+# 同时保存回灌后的新视频及推理过程，便于对比
+./run_camera.sh --replay-session output/sessions/drive-001 \
+  --record-session output/sessions/drive-001-replay
+```
+
+独立包使用同样参数，例如 `./orin/run.sh --record-session output/sessions/drive-001`。
+会话路径相对于当前工作目录；录制目录必须尚不存在，避免覆盖原始记录。
+
+会话内容：
+
+- `frames.mp4`：H.264 有损压缩视频，按完成推理的顺序编码，尺寸与原图一致。
+- `frames/*.json`：对应视频帧序号、原推理帧号、完整采集元数据、检测框、原始/隔离关键点、融合记录、最终结果与耗时。
+- `frames.txt`：视频帧与 JSON 的顺序索引。
+- `session.json`、`door_mask.json`：录制时的推理参数、分辨率、名义帧率、门区副本、模型路径与大小。
+- `complete.json`：正常停止后写入的帧数与视频大小，用于检查会话是否完成。
+
+回灌不打开摄像头。它恢复会话中的分辨率、检测阈值、人数上限、风险阈值和门区，使用 `--config` 指定的当前 TensorRT 引擎，按顺序尽快推理，不按墙钟时间限速。视频使用配置的固定名义帧率；真实采集间隔和断流间隔以 JSON 中的纳秒时间戳为准。原始采集时间在再次录制时保存为 `source_capture`，回灌耗时使用本次运行的单调时钟。
+
+编码使用 OpenCV 的 FFmpeg H.264 编码器；需 OpenCV `videoio` 与可用的 H.264 编码支持，宽高必须为正偶数。不支持时明确报错。当前使用软件编解码，会增加 CPU、编码延迟和磁盘开销；保存对象是完成推理的帧，并非相机全部原始帧。H.264 有损压缩和不同引擎可能改变检测、关键点与风险结果，不承诺逐位一致。模型只记录来源和大小，不复制引擎，也不保证大小相同即模型相同；精确对比应使用同一组引擎。
+
+Ctrl+C / SIGTERM 会封装已写入的视频，`CameraPipeline::join()` 返回前完成收尾。强制杀进程、断电或写入失败可能留下 `frames.pending.mp4`；缺少完成标记的会话拒绝回灌。编码器封装后检查帧数，回灌遇到缺帧、缺失 JSON、损坏索引或解码错误会报错，不静默跳帧。录制没有自动限时或磁盘轮转，请按可用空间控制录制时长。
+
+编解码及会话回归：`./tests/run_session.sh`，无需摄像头或 TensorRT。真实摄像头与 TensorRT 验证脚本：`python3 tests/orin_session_test.py --binary build/camera_risk --config config/camera.json --output /tmp/new-session-test`；输出目录必须不存在，脚本不会停止已有部署进程。
+
+本次实机结果与未覆盖范围见 [H.264 会话测试报告](tests/ORIN_SESSION_REPORT.md)。