简介基于深度排序DeepSORT和开源计算机视觉库OpenCV的ROI区域行人测速统计系统是一份面向计算机视觉与智能监控开发者的完整项目包。该系统针对特定区域内行人速度检测与统计难题结合YOLO等检测算法与多目标跟踪技术演示了从视频预处理到目标跟踪、速度估算的全流程。包内含20个文件主要类型为10个Python脚本、9个示意图和1个说明文档Python代码覆盖数据整理、模型训练、CPU与GPU检测及速度估计等模块示意图便于对照调试整体压缩包仅8.72MB目前已有37人学习参考。这套方案不仅展示了深度排序在深度特征提取与匹配策略上的优化思路也提供了开源计算机视觉库的图像处理实践通过分析跟踪目标位置变化并结合时间信息估算速度适用于交通路口、公共场所人流监控与城市规划等场景对于需要快速搭建行人测速原型或研究多目标跟踪算法的学生和开发者可作为结构清晰的入门与改造成参考。1. 拆解 DeepSORT OpenCV 的 ROI 行人测速统计系统这份工程包到底能干什么如果你接到过“在固定机位视频里数人、测速”这类需求大概率会对 Deepsort OpenCV 这套组合不陌生OpenCV 负责图像处理与视频流读取DeepSORT 负责多目标跟踪ROI感兴趣区域负责限定统计范围。这份《基于 Deepsort 和 OpenCV 的 ROI 区域行人测速统计系统.zip》把这四件事打包成了一个可运行的工程包不是论文级别的复杂方案更不是只有思路没有代码的伪资源而是带具体模块、配置和可视化输出的一整套实现。它是做什么的简单说输入一段监控视频或 RTSP 流系统在画面里画出一个或多个 ROI 区域对进入区域的行人做检测 跟踪在区域内通过触发线完成测速同时输出流量计数。它适合三类人一是做安防或园区管理项目、需要快速交付 demo 的工程师二是用 OpenCV 做图像处理课题、需要一套完整参考代码的学生三是想搞懂“单目相机测速到底怎么标定、怎么写触发逻辑”的算法从业者。这套东西能帮你省掉从零搭骨架的时间但坑也不少下面按“原理 → 复现 → 参数 → 踩坑 → 进阶”的顺序逐个说清楚。2. 从架构到模块为什么要用 DeepSORTROI 到底充当什么角色2.1 整体数据流检测、跟踪、区域过滤、测速统计四层分工先把整个系统的数据流捋一遍方便你拿到代码后能快速定位每一段逻辑在做什么。一套完整的 ROI 行人测速统计系统通常不是单文件脚本而是按下面这个链路切的视频输入层cv2.VideoCapture读取本地 mp4 / avi 或 RTSP 网络流逐帧输出 BGR 图像。目标检测层对每一帧做行人检测一般用 YOLOv5 / YOLOv8 或 SSD输出每个目标的 bboxx, y, w, h和置信度。注意这份资源的核心是 DeepSORT 与 OpenCV检测器往往是封装好的你替换检测权重文件即可。目标跟踪层DeepSORT 接收检测框序列用卡尔曼滤波预测目标在下一帧的位置再用匈牙利算法把当前帧检测框和历史轨迹做匹配并分配稳定的 track id。ROI 与计数层只有 bbox 中心点落在 ROI 多边形内的目标才参与统计配合触发线判断行人“进入”还是“离开”进而完成计数和速度测量。可视化输出层把 ROI 多边形、触发线、目标框、track id、瞬时速度、累计流量叠加到视频上写 mp4 或显示窗口。这套结构里最容易忽略的是第二、三层的接口关系检测器输出的是原始像素坐标DeepSORT 只负责“关联”和“预测”不做语义分类。所以如果你换了检测器输出格式必须统一成x1, y1, x2, y2, score这种列表结构否则 DeepSORT 的Tracks初始化就会直接报错。常见做法是写一个detector.py做封装把不同检测框架的预测结果全部转成上述格式再喂给 tracker。2.2 DeepSORT 比 SORT 强在哪级联匹配与外观特征很多人在 YouTube 和博客上看到的是十几年前的 SORTSimple Online and Realtime Tracking演示——它只靠卡尔曼滤波 IOU 匹配速度快但 ID Switch 频繁行人间一旦交叉遮挡编号立刻乱跳。DeepSORT 在 SORT 基础上加了 128 维外观特征ReID 特征用余弦距离度量两帧目标的“长相”相似度再与马氏距离做加权融合。这套系统选择 DeepSORT 是有现实原因的行人测速需要稳定的 track id因为速度计算依赖同一 id 的多帧轨迹如果用纯 SORT一个行人穿过另一人背后id 变了速度就会被错误重置统计出来的结果根本没有可用性。实现里你大概率会看到类似这样的核心参数不同版本略有差异但语义一致# deep_sort/tracker.py 中的关键参数 max_dist 0.2 # 特征余弦距离阈值越小对长相要求越严 max_iou_distance 0.7 # IOU 距离阈值目标形变过大时放宽匹配 max_age 70 # 目标丢失 N 帧后仍保留轨迹用于短暂遮挡恢复 n_init 3 # 新轨迹至少要连续命中 3 帧才被确认避免虚检造成抖动逻辑说明max_dist控制的是 ReID 特征匹配的严格程度行人侧身、背包、光线变化都会让特征漂移设小了会把同一个人当成新目标设大了又会把不同人混淆。max_age是遮挡恢复的关键行人被栏杆或另一人完全挡住时卡尔曼会继续预测位置但若超过 70 帧还没重新检测到轨迹就被删掉。这几个参数在你复现时是最值得反复调的后面避坑章节我会讲实际踩过的组合。2.3 ROI 多边形与触发线设计为什么不能全屏统计全屏统计在固定机位下会出现三个问题。第一画面远端行人占比小检测框抖动大跟踪稳定性差第二画面边缘经常有半个身体进入又退出产生无效轨迹第三不同距离对应的像素尺度不同直接用全屏像素算速度误差会被放大。ROI 的作用是直接把统计范围切出来。常见实现是在图像上定义一组多边形顶点[(x1,y1), (x2,y2), ...]用cv2.pointPolygonTest或射线法判断目标 bbox 中心点是否在区域内。这里有一个工程经验ROI 不要紧贴画面边缘最好留出 2030 像素的缓冲带避免跟踪轨迹在边界处抖入抖出造成重复计数。触发线则分为进入线和离开线两条也可以合并成一条虚拟线圈行人中心点首次跨过进入线就记一次“进入”跨过离开线记一次“离开”中间经过的时间差用来反推速度。由于这份资源涉及真实物理测速还需要一个标定配置文件# config/roi_config.yaml 典型结构 roi_polygon: [[860, 500], [1280, 500], [1280, 720], [860, 720]] # 多边形顶点 entry_line: [[900, 600], [1230, 600]] # 进入触发线两端坐标 exit_line: [[900, 680], [1230, 680]] # 离开触发线两端坐标 distance_entry_exit_m: 5.0 # 两条触发线之间的真实距离米 calibrated_ppxm: 12.5 # 每像素对应的实际尺寸米用于距离换算逻辑说明calibrated_ppxm这个值不是拍脑袋填的它必须在现场用已知长度物体或者行人走固定距离标定第 4 章会专门讲。distance_entry_exit_m和触发线垂直距离是对应的测速时用“跨线时间差 真实距离 / 速度”反推。注意如果触发线不垂直于行人行走方向需要按夹角修正否则速度会系统性偏低。3. 从压缩包到跑通全流程目录结构、环境配置与关键运行步骤3.1 工程目录与数据集的组织方式一般这种打包资源内部会有清晰的目录划分拿到手后不要急着运行先把结构看清楚它能直接反映作者的工程习惯。常见布局如下. ├── config/ # 所有可调参数 │ ├── roi_config.yaml # ROI 坐标、触发线坐标 │ ├── track_config.yaml # DeepSORT 参数 │ └── speed_config.yaml # 测速标定参数 ├── deep_sort/ # DeepSORT 核心代码 │ ├── detector/ # 目标检测封装 │ ├── tracker.py # 卡尔曼 匈牙利 级联匹配 │ └── embedder.py # ReID 特征提取基于 PyTorch ├── utils/ │ ├── video_reader.py # 视频/RTSP读取封装 │ ├── draw.py # 可视化画框、画线、写文字 │ └── geometry.py # 点与多边形关系、距离计算 ├── main.py # 主入口按帧循环处理 ├── requirements.txt └── weights/ # 检测模型权重yolov5s.pt / 或者 ONNXmain.py通常是一个大循环每帧执行 detect → track → filter → speed_estimate → draw。建议你首先打开main.py找到process_frame函数看它是同步推理还是异步拉流。同步推理代码简单但 RTSP 场景下帧率波动会导致视频变卡异步拉流会多一个线程队列但代码复杂度高。这套资源如果跑本地视频同步就够用了。3.2 requirements 与 OpenCV 安装最常翻车的一步环境装不上是这类资源复现率低的第一大原因。requirements.txt里大概率会有这些核心依赖opencv-python 4.5、numpy、torch或改为 onnxruntime、scipy匈牙利算法库。你要特别小心两个点OpenCV 版本不要用太新的主版本一些老代码在 OpenCV 4.8 上会报cv2.findContours返回值个数变化的问题不过本工程不太涉及但保险起见 4.5 到 4.7 区间最稳。Linux 服务器上如果直接用 pip 装 OpenCV它默认不带 CUDA 加速如需 GPU 推理一般用opencv-python的官方 wheel 版本即可不必自己编译源码。我之前在 Jetson 上试过源码编译 OpenCV那才是真的血泪——编译三小时最后发现自己编译的版本和 DeepSORT 里某个函数不兼容直接回退到 pip 版本。安装步骤建议这样走# 创建独立环境避免污染系统 Python conda create -n speed_system python3.8 -y conda activate speed_system # 先装 PyTorchCPU版即可ReID特征提取用不到太大规模计算 pip install torch1.13.1cpu torchvision0.14.1cpu -f https://download.pytorch.org/whl/torch_stable.html # 再装 OpenCV 系列 pip install opencv-python4.6.0.66 opencv-contrib-python4.6.0.66参数说明opencv-python是基础库opencv-contrib-python包含扩展模块如 tracking 相关。选择 4.6.0.66 是因为这个版本对多边形操作、视频编码等接口的稳定性最好且兼容 py3.8。PyTorch 用 CPU 版就够因为 DeepSORT 的特征提取网络很小逐帧跑 CPU 也能达到几十毫秒级别真正吃算力的是检测网络。如果报ModuleNotFoundError: No module named sklearn之类直接pip install scikit-learn即可这类小依赖经常在 requirements 里漏掉。3.3 运行入口与参数配置先拿 demo 视频验证再换自己的视频拿到工程后能直接跑通 demo 就等于成功了一半。常见做法是作者提供一段demo.mp4你可以先不修改任何代码执行如下命令python main.py \ --config config/roi_config.yaml \ --video data/demo.mp4 \ --output output/result.mp4 \ --show参数含义--config指定 ROI 和测速参数文件--video输入视频路径--output结果视频输出路径--show开启实时显示窗口服务器环境记得去掉否则会cv2.imshow崩溃。如果 demo 能正常画框、计数、显示速度再替换成你自己的视频。自己视频的坑在于拍摄机位、光线、目标尺寸和 demo 差异很大你需要重新标定 ROI 和calibrated_ppxm。很多人直接拿 demo 的参数跑自己视频结果速度漂得非常离谱这不是代码 bug是标定失效。我的习惯是先把roi_config.yaml里的多边形画在视频第一帧上手动拖动调整让它严格框住要统计的区域然后再跑速度测量。OpenCV 提供的cv2.imshow setMouseCallback可以做一个简易的交互式标定窗口但这份资源里如果没提供交互工具你直接改 yaml 里的坐标值再重跑即可因为坐标是明文可改的。4. 测速与统计实现细节距离标定、触发线逻辑和速度平滑4.1 单目相机测速的三个前提为什么必须先标定像素与真实距离行人测速统计系统里最容易被轻视的就是“像素速度”和“真实速度”的映射关系。你从屏幕上看目标每秒移动 50 个像素但这条路径在真实世界里可能是 1 米也可能是 5 米——取决于镜头距离地面的高度、俯仰角、焦距。如果摄像头从高处向下俯拍同样一段真实距离在地面附近投影的像素数远大于远端。所以任何不标定的像素测速都是玄学这里的标定指的是确认“像素坐标差”与“真实世界距离”之间的换算关系。最常用的方法是两点标定法在真实场景的地面上选取两个点用卷尺量出两者距离D然后在画面中读出这两个点的像素坐标差Δp则calibrated_ppxm Δp / D单位像素/米。注意这只是平均换算比如果行人不在标定线所在的深度平面上会有透视误差。进阶一点可以用地平面上多条平行线的灭点校正但作为一个工程包两点标定已经足够让误差控制在 ±10% 以内。4.2 触发线测速实现与像素位移法的对比两种常见测速实现方式在这个工程里大概率用的是触发线法因为它对抖动更鲁棒对比项帧间像素位移法触发线法原理计算同一 id 相邻帧 bbox 中心位移乘换算系数再乘帧率记录目标穿过进入线和离开线的时刻用真实距离除以时间差对单帧抖动敏感度高检测框抖动直接混入速度低只看两次跨线时刻对跟踪 id 稳定性要求高id 切换会算出错误速度中等只需保证跨线瞬间 id 稳定适用场景匀速直线运动的短时测速区域通行测速、流量统计如果代码里用的是帧间位移法速度计算大致长这样def estimate_speed(track, pixel_per_meter, fps, step5): 根据轨迹列表估算目标速度像素位移法 :param track: 目标轨迹元素为 (frame_idx, cx, cy) :param pixel_per_meter: 每米对应的像素数 :param fps: 视频帧率 :param step: 每隔多少帧取一个点降低抖动 if len(track) 12: # 轨迹太短速度不可信 return 0.0 start track[0] end track[-1] dx_pixel end[1] - start[1] dy_pixel end[2] - start[2] dist_pixel (dx_pixel ** 2 dy_pixel ** 2) ** 0.5 dist_meter dist_pixel / pixel_per_meter time_sec (end[0] - start[0]) / fps speed_ms dist_meter / time_sec if time_sec 0 else 0.0 return round(speed_ms * 3.6, 2) # 换算成 km/h逻辑说明这里用step5而不是相邻两帧是为了间隔几帧取一个点减轻 bbox 中心抖动带来的距离计算误差。end[0] - start[0]是帧号差除以fps才是真实秒数。注意框中心点的抖动在小目标身上非常明显所以轨迹至少要积累 12 个点才开始算速度。触发线法则完全不同它记录行人中心点第一次越过进入线时的帧号t_entry和越过离开线时的帧号t_exit然后用distance_entry_exit_m / ((t_exit - t_entry) / fps)得出速度。触发线法的好处是它对单帧抖动几乎免疫因为它只关心两条线之间的真实距离不关心中间轨迹。坏处是如果行人在两条线之间停留、掉头或走弧线速度会被严重低估。4.3 速度平滑与异常值剔除不想看到速度数字乱跳必须做这步不管用哪种测速方式原始速度序列都会伴随毛刺。常见场景是一个静止在画面里的人因为检测框轻微抖动速度在 0 和 8 km/h 之间反复横跳。解决办法是加一个滑窗中值滤波代码模式如下def smooth_speed(speed_history, window_size5): 对历史速度序列做中值滤波 :param speed_history: 保存最近 N 次计算出的速度 :param window_size: 滑窗大小 if len(speed_history) window_size: return speed_history[-1] if speed_history else 0.0 window speed_history[-window_size:] window.sort() return window[len(window) // 2]逻辑说明中值滤波比均值滤波更适合速度这类有突发离群值的信号一个强跳变不会把整体结果拉偏。window_size取 5 或 7 比较合适太小压不住毛刺太大会让加速、减速的响应变慢。我一般会在主循环里持有一个speed_history字典key 是 track idvalue 是最近的速度列表超过一定长度就截断避免内存膨胀。这套工程里速度逻辑的完整细节我不可能凭标题全部还原但通常不外乎上面两种方案的组合先用区域过滤保证只有 ROI 内的目标参与计时再结合触发线测速最后做中值平滑输出到叠加层。5. 避坑排查与常见问题复现这套系统时最常踩的五个坑5.1 现象视频显示正常但计数始终为 0现象ROI 画出来了目标框也在画面里但入口线处没有触发任何计数终端也不打印任何计数日志。原因绝大多数情况是 ROI 多边形坐标和触发线坐标不匹配或者触发线不在 ROI 内部。更隐蔽的一种是ROI 的坐标是按原图尺寸标注的但代码在送入检测器前先把图像 resize 了检测框坐标又还原到原图而 ROI 判断时用到的是 resize 后的坐标直接错位。解决在代码中统一坐标参照系。我一般强制规定所有坐标点在进入process_frame时就已经是“原始视频分辨率”下的坐标ROI 配置 yaml 里的坐标也写成原图尺寸resize 只发生在检测器内部检测输出必须映射回原图。你可以打印一帧里的目标中心点和 ROI 顶点坐标手动点验一遍。5.2 现象DeepSORT 的 id 频繁切换同一个人编号一直在变现象行人正常行走画面中他的 track id 从 5 跳到 12再跳到 18导致速度无法连贯计算统计人数虚高。原因典型的两类原因。一是检测阈值设得太低比如 0.3大量低质量检测框进入 tracker虚检打断了连续轨迹导致新的轨迹频繁初始化二是max_dist设得太大外观特征匹配过于宽松同一目标的不同帧被判为不同目标。解决把检测置信度提到 0.5 以上同时把n_init从 3 提到 5——也就是目标必须连续出现 5 帧才被确认这样虚检会被快速清理。如果遮挡太严重适当放宽max_age到 90 帧允许长遮挡恢复。5.3 现象速度结果明显偏低人明明走得很快画面里却只有 2 km/h现象现场走一圈系统显示速度不到 3 km/h与实际步行速度严重不符。原因距离标定失效。大概率是calibrated_ppxm或distance_entry_exit_m配置错了也可能是行人在两条触发线之间走的不是直线而是斜穿导致实际行走距离大于两条线的垂直距离。解决先拿一段标定视频做“空跑验证”。我在实际项目中会让一个人以匀速走 10 米视频记录从触发线到离开线的时间反推真实速度再用系统输出对比如果偏差超过 15%就修正标定值。斜穿场景下要把触发线布置成垂直于行人主流方向否则必须在速度公式里除一个 cos(夹角) 修正系数。5.4 现象ROI 区域不生效画面外的人也被计数现象目标跑出 ROI 多边形很远系统还在统计他的轨迹计数结果明显不可信。原因ROI 判断用的不是目标中心点而是 bbox 左上角或者pointPolygonTest的参数用法不对、代码里用了isContourConvex之类错误函数。解决把判断逻辑简化为cv2.pointPolygonTest(roi, (cx, cy), False) 0其中(cx, cy)是 bbox 中心点。另外确认 ROI 凸包是否闭合OpenCV 对凹多边形也能处理不过如果你用fillPoly生成掩码再检查是不会出错的若直接用pointPolygonTest有些版本需要多边形顶点按顺时针或逆时针排列建议打印首尾点检查闭合性。5.5 现象程序能跑但 CPU 占用 100%帧率只有 5fps现象1080p 视频在普通笔记本上跑得很卡输出视频像是幻灯片。原因检测网络在没有 GPU 的情况下要开销大头而 DeepSORT 的 ReID 特征也要 CPU 稀疏矩阵计算。很多人忽略了一个更简单的优化全图检测 全图特征提取而实际上只有 ROI 区域内的目标才需要测速。解决把检测范围限制在 ROI 的扩大外接矩形内即待检测区域 ROI 多边形的最小外接矩形 少量 margin。这样能直接减少 40%60% 的计算量。此外可以降低检测输入分辨率到 640 或 416速度精度损失很小但帧率能提两倍。这一步做完仍不够再考虑 GPU 或 TensorRT 加速。6. 进阶把测速精度从“能看”做到“能交代”大部分复现的人停在了“能跑、有数字”这一层但真正交付给甲方或老师的时候数字的可信度才是焦点。我的建议是主动做一个精度验证闭环在固定机位下录制一个已知速度的视频段由一个人按正常步行速度横穿 ROI 区域手持秒表记录通过时间作为真值速度。然后让系统跑同样的视频把系统输出与真值对比算出平均绝对误差。如果误差超过 3 km/h就要回到标定参数去查而不是直接交付。# 精度验证脚本伪代码 true_speed_kmh 4.8 # 通过秒表和距离算出的真值 system_speed_kmh [4.1, 4.7, 5.2, 4.4, 4.9] # 同一人多次经过的系统输出 mae sum([abs(s - true_speed_kmh) for s in system_speed_kmh]) / len(system_speed_kmh) print(fMAE: {mae:.2f} km/h, 相对误差: {mae / true_speed_kmh * 100:.1f}%)这里的关键是多次测量取平均不同时段的光线、行人位置都有细微差异单次测量没有意义。我会至少测 5 组数据计算相对误差在 ±10% 以内才确认标定有效。这一步做完你再去看系统输出的“某人速度 4.8 km/h”就有底气告诉别人这是可信的而不是黑匣子里的一个随机整数。从那以后我每次做这种测速统计项目都强制自己先跑一遍空跑验证——把已知速度的视频喂进去看系统能不能还原出正确数字。这个习惯帮我避免了很多次现场交付时被问得哑口无言的情况希望帮到你。本文还有配套的精品资源点击获取 DeepSORT+OpenCV的ROI行人测速统计系统：原理、工程实现与避坑指南
简介基于深度排序DeepSORT和开源计算机视觉库OpenCV的ROI区域行人测速统计系统是一份面向计算机视觉与智能监控开发者的完整项目包。该系统针对特定区域内行人速度检测与统计难题结合YOLO等检测算法与多目标跟踪技术演示了从视频预处理到目标跟踪、速度估算的全流程。包内含20个文件主要类型为10个Python脚本、9个示意图和1个说明文档Python代码覆盖数据整理、模型训练、CPU与GPU检测及速度估计等模块示意图便于对照调试整体压缩包仅8.72MB目前已有37人学习参考。这套方案不仅展示了深度排序在深度特征提取与匹配策略上的优化思路也提供了开源计算机视觉库的图像处理实践通过分析跟踪目标位置变化并结合时间信息估算速度适用于交通路口、公共场所人流监控与城市规划等场景对于需要快速搭建行人测速原型或研究多目标跟踪算法的学生和开发者可作为结构清晰的入门与改造成参考。1. 拆解 DeepSORT OpenCV 的 ROI 行人测速统计系统这份工程包到底能干什么如果你接到过“在固定机位视频里数人、测速”这类需求大概率会对 Deepsort OpenCV 这套组合不陌生OpenCV 负责图像处理与视频流读取DeepSORT 负责多目标跟踪ROI感兴趣区域负责限定统计范围。这份《基于 Deepsort 和 OpenCV 的 ROI 区域行人测速统计系统.zip》把这四件事打包成了一个可运行的工程包不是论文级别的复杂方案更不是只有思路没有代码的伪资源而是带具体模块、配置和可视化输出的一整套实现。它是做什么的简单说输入一段监控视频或 RTSP 流系统在画面里画出一个或多个 ROI 区域对进入区域的行人做检测 跟踪在区域内通过触发线完成测速同时输出流量计数。它适合三类人一是做安防或园区管理项目、需要快速交付 demo 的工程师二是用 OpenCV 做图像处理课题、需要一套完整参考代码的学生三是想搞懂“单目相机测速到底怎么标定、怎么写触发逻辑”的算法从业者。这套东西能帮你省掉从零搭骨架的时间但坑也不少下面按“原理 → 复现 → 参数 → 踩坑 → 进阶”的顺序逐个说清楚。2. 从架构到模块为什么要用 DeepSORTROI 到底充当什么角色2.1 整体数据流检测、跟踪、区域过滤、测速统计四层分工先把整个系统的数据流捋一遍方便你拿到代码后能快速定位每一段逻辑在做什么。一套完整的 ROI 行人测速统计系统通常不是单文件脚本而是按下面这个链路切的视频输入层cv2.VideoCapture读取本地 mp4 / avi 或 RTSP 网络流逐帧输出 BGR 图像。目标检测层对每一帧做行人检测一般用 YOLOv5 / YOLOv8 或 SSD输出每个目标的 bboxx, y, w, h和置信度。注意这份资源的核心是 DeepSORT 与 OpenCV检测器往往是封装好的你替换检测权重文件即可。目标跟踪层DeepSORT 接收检测框序列用卡尔曼滤波预测目标在下一帧的位置再用匈牙利算法把当前帧检测框和历史轨迹做匹配并分配稳定的 track id。ROI 与计数层只有 bbox 中心点落在 ROI 多边形内的目标才参与统计配合触发线判断行人“进入”还是“离开”进而完成计数和速度测量。可视化输出层把 ROI 多边形、触发线、目标框、track id、瞬时速度、累计流量叠加到视频上写 mp4 或显示窗口。这套结构里最容易忽略的是第二、三层的接口关系检测器输出的是原始像素坐标DeepSORT 只负责“关联”和“预测”不做语义分类。所以如果你换了检测器输出格式必须统一成x1, y1, x2, y2, score这种列表结构否则 DeepSORT 的Tracks初始化就会直接报错。常见做法是写一个detector.py做封装把不同检测框架的预测结果全部转成上述格式再喂给 tracker。2.2 DeepSORT 比 SORT 强在哪级联匹配与外观特征很多人在 YouTube 和博客上看到的是十几年前的 SORTSimple Online and Realtime Tracking演示——它只靠卡尔曼滤波 IOU 匹配速度快但 ID Switch 频繁行人间一旦交叉遮挡编号立刻乱跳。DeepSORT 在 SORT 基础上加了 128 维外观特征ReID 特征用余弦距离度量两帧目标的“长相”相似度再与马氏距离做加权融合。这套系统选择 DeepSORT 是有现实原因的行人测速需要稳定的 track id因为速度计算依赖同一 id 的多帧轨迹如果用纯 SORT一个行人穿过另一人背后id 变了速度就会被错误重置统计出来的结果根本没有可用性。实现里你大概率会看到类似这样的核心参数不同版本略有差异但语义一致# deep_sort/tracker.py 中的关键参数 max_dist 0.2 # 特征余弦距离阈值越小对长相要求越严 max_iou_distance 0.7 # IOU 距离阈值目标形变过大时放宽匹配 max_age 70 # 目标丢失 N 帧后仍保留轨迹用于短暂遮挡恢复 n_init 3 # 新轨迹至少要连续命中 3 帧才被确认避免虚检造成抖动逻辑说明max_dist控制的是 ReID 特征匹配的严格程度行人侧身、背包、光线变化都会让特征漂移设小了会把同一个人当成新目标设大了又会把不同人混淆。max_age是遮挡恢复的关键行人被栏杆或另一人完全挡住时卡尔曼会继续预测位置但若超过 70 帧还没重新检测到轨迹就被删掉。这几个参数在你复现时是最值得反复调的后面避坑章节我会讲实际踩过的组合。2.3 ROI 多边形与触发线设计为什么不能全屏统计全屏统计在固定机位下会出现三个问题。第一画面远端行人占比小检测框抖动大跟踪稳定性差第二画面边缘经常有半个身体进入又退出产生无效轨迹第三不同距离对应的像素尺度不同直接用全屏像素算速度误差会被放大。ROI 的作用是直接把统计范围切出来。常见实现是在图像上定义一组多边形顶点[(x1,y1), (x2,y2), ...]用cv2.pointPolygonTest或射线法判断目标 bbox 中心点是否在区域内。这里有一个工程经验ROI 不要紧贴画面边缘最好留出 2030 像素的缓冲带避免跟踪轨迹在边界处抖入抖出造成重复计数。触发线则分为进入线和离开线两条也可以合并成一条虚拟线圈行人中心点首次跨过进入线就记一次“进入”跨过离开线记一次“离开”中间经过的时间差用来反推速度。由于这份资源涉及真实物理测速还需要一个标定配置文件# config/roi_config.yaml 典型结构 roi_polygon: [[860, 500], [1280, 500], [1280, 720], [860, 720]] # 多边形顶点 entry_line: [[900, 600], [1230, 600]] # 进入触发线两端坐标 exit_line: [[900, 680], [1230, 680]] # 离开触发线两端坐标 distance_entry_exit_m: 5.0 # 两条触发线之间的真实距离米 calibrated_ppxm: 12.5 # 每像素对应的实际尺寸米用于距离换算逻辑说明calibrated_ppxm这个值不是拍脑袋填的它必须在现场用已知长度物体或者行人走固定距离标定第 4 章会专门讲。distance_entry_exit_m和触发线垂直距离是对应的测速时用“跨线时间差 真实距离 / 速度”反推。注意如果触发线不垂直于行人行走方向需要按夹角修正否则速度会系统性偏低。3. 从压缩包到跑通全流程目录结构、环境配置与关键运行步骤3.1 工程目录与数据集的组织方式一般这种打包资源内部会有清晰的目录划分拿到手后不要急着运行先把结构看清楚它能直接反映作者的工程习惯。常见布局如下. ├── config/ # 所有可调参数 │ ├── roi_config.yaml # ROI 坐标、触发线坐标 │ ├── track_config.yaml # DeepSORT 参数 │ └── speed_config.yaml # 测速标定参数 ├── deep_sort/ # DeepSORT 核心代码 │ ├── detector/ # 目标检测封装 │ ├── tracker.py # 卡尔曼 匈牙利 级联匹配 │ └── embedder.py # ReID 特征提取基于 PyTorch ├── utils/ │ ├── video_reader.py # 视频/RTSP读取封装 │ ├── draw.py # 可视化画框、画线、写文字 │ └── geometry.py # 点与多边形关系、距离计算 ├── main.py # 主入口按帧循环处理 ├── requirements.txt └── weights/ # 检测模型权重yolov5s.pt / 或者 ONNXmain.py通常是一个大循环每帧执行 detect → track → filter → speed_estimate → draw。建议你首先打开main.py找到process_frame函数看它是同步推理还是异步拉流。同步推理代码简单但 RTSP 场景下帧率波动会导致视频变卡异步拉流会多一个线程队列但代码复杂度高。这套资源如果跑本地视频同步就够用了。3.2 requirements 与 OpenCV 安装最常翻车的一步环境装不上是这类资源复现率低的第一大原因。requirements.txt里大概率会有这些核心依赖opencv-python 4.5、numpy、torch或改为 onnxruntime、scipy匈牙利算法库。你要特别小心两个点OpenCV 版本不要用太新的主版本一些老代码在 OpenCV 4.8 上会报cv2.findContours返回值个数变化的问题不过本工程不太涉及但保险起见 4.5 到 4.7 区间最稳。Linux 服务器上如果直接用 pip 装 OpenCV它默认不带 CUDA 加速如需 GPU 推理一般用opencv-python的官方 wheel 版本即可不必自己编译源码。我之前在 Jetson 上试过源码编译 OpenCV那才是真的血泪——编译三小时最后发现自己编译的版本和 DeepSORT 里某个函数不兼容直接回退到 pip 版本。安装步骤建议这样走# 创建独立环境避免污染系统 Python conda create -n speed_system python3.8 -y conda activate speed_system # 先装 PyTorchCPU版即可ReID特征提取用不到太大规模计算 pip install torch1.13.1cpu torchvision0.14.1cpu -f https://download.pytorch.org/whl/torch_stable.html # 再装 OpenCV 系列 pip install opencv-python4.6.0.66 opencv-contrib-python4.6.0.66参数说明opencv-python是基础库opencv-contrib-python包含扩展模块如 tracking 相关。选择 4.6.0.66 是因为这个版本对多边形操作、视频编码等接口的稳定性最好且兼容 py3.8。PyTorch 用 CPU 版就够因为 DeepSORT 的特征提取网络很小逐帧跑 CPU 也能达到几十毫秒级别真正吃算力的是检测网络。如果报ModuleNotFoundError: No module named sklearn之类直接pip install scikit-learn即可这类小依赖经常在 requirements 里漏掉。3.3 运行入口与参数配置先拿 demo 视频验证再换自己的视频拿到工程后能直接跑通 demo 就等于成功了一半。常见做法是作者提供一段demo.mp4你可以先不修改任何代码执行如下命令python main.py \ --config config/roi_config.yaml \ --video data/demo.mp4 \ --output output/result.mp4 \ --show参数含义--config指定 ROI 和测速参数文件--video输入视频路径--output结果视频输出路径--show开启实时显示窗口服务器环境记得去掉否则会cv2.imshow崩溃。如果 demo 能正常画框、计数、显示速度再替换成你自己的视频。自己视频的坑在于拍摄机位、光线、目标尺寸和 demo 差异很大你需要重新标定 ROI 和calibrated_ppxm。很多人直接拿 demo 的参数跑自己视频结果速度漂得非常离谱这不是代码 bug是标定失效。我的习惯是先把roi_config.yaml里的多边形画在视频第一帧上手动拖动调整让它严格框住要统计的区域然后再跑速度测量。OpenCV 提供的cv2.imshow setMouseCallback可以做一个简易的交互式标定窗口但这份资源里如果没提供交互工具你直接改 yaml 里的坐标值再重跑即可因为坐标是明文可改的。4. 测速与统计实现细节距离标定、触发线逻辑和速度平滑4.1 单目相机测速的三个前提为什么必须先标定像素与真实距离行人测速统计系统里最容易被轻视的就是“像素速度”和“真实速度”的映射关系。你从屏幕上看目标每秒移动 50 个像素但这条路径在真实世界里可能是 1 米也可能是 5 米——取决于镜头距离地面的高度、俯仰角、焦距。如果摄像头从高处向下俯拍同样一段真实距离在地面附近投影的像素数远大于远端。所以任何不标定的像素测速都是玄学这里的标定指的是确认“像素坐标差”与“真实世界距离”之间的换算关系。最常用的方法是两点标定法在真实场景的地面上选取两个点用卷尺量出两者距离D然后在画面中读出这两个点的像素坐标差Δp则calibrated_ppxm Δp / D单位像素/米。注意这只是平均换算比如果行人不在标定线所在的深度平面上会有透视误差。进阶一点可以用地平面上多条平行线的灭点校正但作为一个工程包两点标定已经足够让误差控制在 ±10% 以内。4.2 触发线测速实现与像素位移法的对比两种常见测速实现方式在这个工程里大概率用的是触发线法因为它对抖动更鲁棒对比项帧间像素位移法触发线法原理计算同一 id 相邻帧 bbox 中心位移乘换算系数再乘帧率记录目标穿过进入线和离开线的时刻用真实距离除以时间差对单帧抖动敏感度高检测框抖动直接混入速度低只看两次跨线时刻对跟踪 id 稳定性要求高id 切换会算出错误速度中等只需保证跨线瞬间 id 稳定适用场景匀速直线运动的短时测速区域通行测速、流量统计如果代码里用的是帧间位移法速度计算大致长这样def estimate_speed(track, pixel_per_meter, fps, step5): 根据轨迹列表估算目标速度像素位移法 :param track: 目标轨迹元素为 (frame_idx, cx, cy) :param pixel_per_meter: 每米对应的像素数 :param fps: 视频帧率 :param step: 每隔多少帧取一个点降低抖动 if len(track) 12: # 轨迹太短速度不可信 return 0.0 start track[0] end track[-1] dx_pixel end[1] - start[1] dy_pixel end[2] - start[2] dist_pixel (dx_pixel ** 2 dy_pixel ** 2) ** 0.5 dist_meter dist_pixel / pixel_per_meter time_sec (end[0] - start[0]) / fps speed_ms dist_meter / time_sec if time_sec 0 else 0.0 return round(speed_ms * 3.6, 2) # 换算成 km/h逻辑说明这里用step5而不是相邻两帧是为了间隔几帧取一个点减轻 bbox 中心抖动带来的距离计算误差。end[0] - start[0]是帧号差除以fps才是真实秒数。注意框中心点的抖动在小目标身上非常明显所以轨迹至少要积累 12 个点才开始算速度。触发线法则完全不同它记录行人中心点第一次越过进入线时的帧号t_entry和越过离开线时的帧号t_exit然后用distance_entry_exit_m / ((t_exit - t_entry) / fps)得出速度。触发线法的好处是它对单帧抖动几乎免疫因为它只关心两条线之间的真实距离不关心中间轨迹。坏处是如果行人在两条线之间停留、掉头或走弧线速度会被严重低估。4.3 速度平滑与异常值剔除不想看到速度数字乱跳必须做这步不管用哪种测速方式原始速度序列都会伴随毛刺。常见场景是一个静止在画面里的人因为检测框轻微抖动速度在 0 和 8 km/h 之间反复横跳。解决办法是加一个滑窗中值滤波代码模式如下def smooth_speed(speed_history, window_size5): 对历史速度序列做中值滤波 :param speed_history: 保存最近 N 次计算出的速度 :param window_size: 滑窗大小 if len(speed_history) window_size: return speed_history[-1] if speed_history else 0.0 window speed_history[-window_size:] window.sort() return window[len(window) // 2]逻辑说明中值滤波比均值滤波更适合速度这类有突发离群值的信号一个强跳变不会把整体结果拉偏。window_size取 5 或 7 比较合适太小压不住毛刺太大会让加速、减速的响应变慢。我一般会在主循环里持有一个speed_history字典key 是 track idvalue 是最近的速度列表超过一定长度就截断避免内存膨胀。这套工程里速度逻辑的完整细节我不可能凭标题全部还原但通常不外乎上面两种方案的组合先用区域过滤保证只有 ROI 内的目标参与计时再结合触发线测速最后做中值平滑输出到叠加层。5. 避坑排查与常见问题复现这套系统时最常踩的五个坑5.1 现象视频显示正常但计数始终为 0现象ROI 画出来了目标框也在画面里但入口线处没有触发任何计数终端也不打印任何计数日志。原因绝大多数情况是 ROI 多边形坐标和触发线坐标不匹配或者触发线不在 ROI 内部。更隐蔽的一种是ROI 的坐标是按原图尺寸标注的但代码在送入检测器前先把图像 resize 了检测框坐标又还原到原图而 ROI 判断时用到的是 resize 后的坐标直接错位。解决在代码中统一坐标参照系。我一般强制规定所有坐标点在进入process_frame时就已经是“原始视频分辨率”下的坐标ROI 配置 yaml 里的坐标也写成原图尺寸resize 只发生在检测器内部检测输出必须映射回原图。你可以打印一帧里的目标中心点和 ROI 顶点坐标手动点验一遍。5.2 现象DeepSORT 的 id 频繁切换同一个人编号一直在变现象行人正常行走画面中他的 track id 从 5 跳到 12再跳到 18导致速度无法连贯计算统计人数虚高。原因典型的两类原因。一是检测阈值设得太低比如 0.3大量低质量检测框进入 tracker虚检打断了连续轨迹导致新的轨迹频繁初始化二是max_dist设得太大外观特征匹配过于宽松同一目标的不同帧被判为不同目标。解决把检测置信度提到 0.5 以上同时把n_init从 3 提到 5——也就是目标必须连续出现 5 帧才被确认这样虚检会被快速清理。如果遮挡太严重适当放宽max_age到 90 帧允许长遮挡恢复。5.3 现象速度结果明显偏低人明明走得很快画面里却只有 2 km/h现象现场走一圈系统显示速度不到 3 km/h与实际步行速度严重不符。原因距离标定失效。大概率是calibrated_ppxm或distance_entry_exit_m配置错了也可能是行人在两条触发线之间走的不是直线而是斜穿导致实际行走距离大于两条线的垂直距离。解决先拿一段标定视频做“空跑验证”。我在实际项目中会让一个人以匀速走 10 米视频记录从触发线到离开线的时间反推真实速度再用系统输出对比如果偏差超过 15%就修正标定值。斜穿场景下要把触发线布置成垂直于行人主流方向否则必须在速度公式里除一个 cos(夹角) 修正系数。5.4 现象ROI 区域不生效画面外的人也被计数现象目标跑出 ROI 多边形很远系统还在统计他的轨迹计数结果明显不可信。原因ROI 判断用的不是目标中心点而是 bbox 左上角或者pointPolygonTest的参数用法不对、代码里用了isContourConvex之类错误函数。解决把判断逻辑简化为cv2.pointPolygonTest(roi, (cx, cy), False) 0其中(cx, cy)是 bbox 中心点。另外确认 ROI 凸包是否闭合OpenCV 对凹多边形也能处理不过如果你用fillPoly生成掩码再检查是不会出错的若直接用pointPolygonTest有些版本需要多边形顶点按顺时针或逆时针排列建议打印首尾点检查闭合性。5.5 现象程序能跑但 CPU 占用 100%帧率只有 5fps现象1080p 视频在普通笔记本上跑得很卡输出视频像是幻灯片。原因检测网络在没有 GPU 的情况下要开销大头而 DeepSORT 的 ReID 特征也要 CPU 稀疏矩阵计算。很多人忽略了一个更简单的优化全图检测 全图特征提取而实际上只有 ROI 区域内的目标才需要测速。解决把检测范围限制在 ROI 的扩大外接矩形内即待检测区域 ROI 多边形的最小外接矩形 少量 margin。这样能直接减少 40%60% 的计算量。此外可以降低检测输入分辨率到 640 或 416速度精度损失很小但帧率能提两倍。这一步做完仍不够再考虑 GPU 或 TensorRT 加速。6. 进阶把测速精度从“能看”做到“能交代”大部分复现的人停在了“能跑、有数字”这一层但真正交付给甲方或老师的时候数字的可信度才是焦点。我的建议是主动做一个精度验证闭环在固定机位下录制一个已知速度的视频段由一个人按正常步行速度横穿 ROI 区域手持秒表记录通过时间作为真值速度。然后让系统跑同样的视频把系统输出与真值对比算出平均绝对误差。如果误差超过 3 km/h就要回到标定参数去查而不是直接交付。# 精度验证脚本伪代码 true_speed_kmh 4.8 # 通过秒表和距离算出的真值 system_speed_kmh [4.1, 4.7, 5.2, 4.4, 4.9] # 同一人多次经过的系统输出 mae sum([abs(s - true_speed_kmh) for s in system_speed_kmh]) / len(system_speed_kmh) print(fMAE: {mae:.2f} km/h, 相对误差: {mae / true_speed_kmh * 100:.1f}%)这里的关键是多次测量取平均不同时段的光线、行人位置都有细微差异单次测量没有意义。我会至少测 5 组数据计算相对误差在 ±10% 以内才确认标定有效。这一步做完你再去看系统输出的“某人速度 4.8 km/h”就有底气告诉别人这是可信的而不是黑匣子里的一个随机整数。从那以后我每次做这种测速统计项目都强制自己先跑一遍空跑验证——把已知速度的视频喂进去看系统能不能还原出正确数字。这个习惯帮我避免了很多次现场交付时被问得哑口无言的情况希望帮到你。本文还有配套的精品资源点击获取