光流点跟踪测速

计算机视觉课程实验(大三下):基于 Shi-Tomasi 角点与金字塔 LK 光流点跟踪,结合交比不变量射影测距,从单目视频估计跑步者的运动速度。

任务背景

课程实验二「基于光流点跟踪的运动对象速度估计」:在自行拍摄的视频中人工选择跟踪对象,用光流点跟踪完成目标跟踪,再利用透视几何换算真实距离并给出速度。
实验限制:只能使用光流点跟踪,禁止 YOLO、SuperVision 等深度学习检测器,禁止 OpenCV 内置目标跟踪器(CSRT/KCF 等),禁止用 Homography 把 ROI 变换到米制空间。
实现流程:首帧人工标注人体框与三条真实位置已知的参考线;框内提取 Shi-Tomasi 角点,金字塔 Lucas-Kanade 前后向跟踪并剔除坏点;以中位数位移更新人体框(Median Flow 思想);测速锚点取框底边中心上方位置;由跑向灭点与参考线交点构造一维射影映射(等价于交比不变量)把像素坐标换算成米制距离;最后用 0.25 s 滑动窗口、1.5 s 局部 Huber 拟合与因果 Hampel 中位数滤波输出稳定速度。
实验数据:8 组原始 4K@60fps 视频及同源派生的 1080p/540p、30fps 版本共 34 组,用于比较分辨率、帧率、机位与标定几何对测速的影响。

内容结构

路径	说明
`main.py`	命令行主入口:读标定、执行跟踪测速、写出 CSV 与叠加视频
`reference_calibration.py`	交互式标定工具:点选三条参考线、人体框、跑向辅助线并存为 JSON
`monocular_speed/config.py`	LK 参数与流水线参数的 dataclass 配置
`monocular_speed/geometry.py`	灭点求解、参考线交点、一维射影(交比)测距与几何质量判定
`monocular_speed/lk_track.py`	Shi-Tomasi 角点提取、金字塔 LK 多点跟踪、Median Flow 人体框更新
`monocular_speed/speed.py`	滑动窗口测速、Huber 轨迹拟合、Hampel 稳定器、CSV 写出
`monocular_speed/vis_util.py`	叠加视频与调试可视化输出
`sources/*.json`	各视频的标定文件(参考线端点、人体框);原始视频体积大,未入库
`output/`、`output_manual/`	逐样本 `tracking_speed.csv` 与三份汇总 CSV;叠加视频 mp4 未入库
`report_assets_new/report_data.json`	实验结果汇总数据
`IMPROVEMENTS.md`	方法改进记录与分辨率/帧率对比结论
`NOTES.md`	英文使用说明与调参笔记
`pyproject.toml`、`uv.lock`	依赖声明与版本锁定

运行方法

依赖(Python ≥ 3.10):numpy>=1.26、opencv-python>=4.9、matplotlib>=3.8,见 pyproject.toml。

# 安装依赖(任选其一)
uv sync
pip install numpy opencv-python matplotlib

# 1) 对自备视频做交互式标定,生成 sources/<名称>.json
uv run python reference_calibration.py sources\your_video.mp4

# 2) 跟踪测速,结果写入 output\<名称>\
uv run python main.py sourcesk_60fps_3.json --reference-positions 0,4,8 --min-projective-denominator 0.25 --fit-window-seconds 1.5

说明:仓库不含原始视频与叠加结果视频(单文件最大近百 MB);sources/*.json 中的 video 字段指向本机视频路径,复现实验需自备同源视频或重新标定。跟踪器可用 --tracker bbox|robust|single 切换,默认为人工框初始化的 Median Flow 方案。

来源声明

课程框架:实验要求、评分项与「仅限光流点跟踪」的限制来自课程实验二课件,课程文档与实验报告未入库。
自研范围:monocular_speed 包、main.py、reference_calibration.py 及全部标定/结果数据为本人独立完成。
参考来源:OpenCV 官方文档中 goodFeaturesToTrack 与 calcOpticalFlowPyrLK 的用法示例;Median Flow 的中位数位移更新思想参考了相关跟踪论文的公开描述,未复用任何现成跟踪器实现。
实验视频均为自行拍摄;国际田联 400 m 标准跑道画线资料仅用于设计参考线间距,该资料未入库。