简介面向计算机视觉初学者与目标跟踪方向的学习者这份项目围绕遮挡与重叠场景下的单目标跟踪展开将卡尔曼滤波的预测—更新机制与最大IOU匹配结合用于缓解目标被部分遮挡或相互重叠时跟丢的问题属于机器学习在视觉任务中的进阶实践素材。压缩包共338个文件、约25.87MB主体为327个txt标签文件配套4个xml配置、2个Python脚本及少量pyc缓存与1段mp4测试视频标签与视频可直接用于跑通跟踪流程并评估效果。已有514人学习下载。读者可从中获得卡尔曼滤波器初始化与参数设置的实现思路理解预测与更新步骤如何平滑跟踪噪声并借助辅助工具模块中的图像处理、目标检测与IOU计算等通用函数掌握跟踪评估环节再通过测试视频观察遮挡后重新找回目标的表现目录按算法实现、辅助工具、标签数据与测试素材划分便于逐模块拆解与二次调试。1. 遮挡下的单目标跟踪为什么“预测”比“检测”更靠谱监控画面里两个人擦肩而过跟踪框“唰”地跳到另一个人身上这是目标跟踪在遮挡与重叠场景下最典型的失败情形。做计算机视觉的同学大多遇过这种情况检测器每帧都能输出一个框可目标被挡住三五帧后检测结果立刻归零整条轨迹就断在那里再出现时已经认不出来了。这个项目做的事很朴素用卡尔曼滤波维护目标运动的连续状态用灰度模板匹配提供一个成本很低的观测再叠一层状态机判断“这次的观测到底可不可信”当目标被遮挡、或被重叠目标干扰时让跟踪器依然保持对目标的关联。它不依赖 GPU也不加载预训练权重核心逻辑两百来行 PythonCPU 上跑 640×480 的视频能到六十帧上下。适合两类人一是在边缘盒子或嵌入式板子上做跟踪、不想背负整套深度学习框架的开发者二是刚接触目标跟踪想沿着状态估计这条主线把 predict/update、新息门控、重检测一次串起来的人。整个项目最值钱的不是那个 8 维矩阵而是“观测不可信时该怎么办”的判断逻辑代码不长但要把它调稳还是有不少细节需要注意。2. 工程骨架拆解从读帧到出框的三段流水线与目录职责2.1 选型为什么是“模板匹配做观测 卡尔曼滤波做状态”很多刚上手的人会默认“跟踪 检测 ID 匹配”其实在单目标跟踪的经典解法里检测器只是可选项。遮挡发生时检测器给不出框两个目标重叠时检测器给出两个框且分数接近——这两个问题都不是“换个更强的检测器”能根治的缺的是对目标运动的连续建模。卡尔曼滤波的价值恰好在这里它不产生观测只维护一个“目标大概在哪、朝哪个方向走、走多快”的信念观测断了它还能靠匀速模型外推十几帧等目标重新露出来再接上。所以这个项目的流水线是三段第一段是观测器在预测框周围扩一圈搜索窗用首帧抠出来的灰度模板做归一化互相关匹配取响应峰值位置当观测第二段是卡尔曼滤波器把观测塞进 update或者判断这次观测不可信就只做 predict第三段是状态机与外观校验用峰值、峰值旁瓣比、新息马氏距离三个量决定当前处于 tracking、occluded 还是 lost。三段之间是单向数据流每段都能单独替换这也是后面二次开发最省事的地方。方案遮挡 5 帧后两目标重叠CPU 单帧耗时额外依赖检测器逐帧输出直接丢框框在两个目标间跳20~60 ms模型与权重相关滤波类方法框缓慢漂到遮挡物上易被邻近目标吸走5~15 ms需 FFT尺度固定孪生网络类方法依赖额外重检测模块相对较好15~40 msGPUGPU 与权重模板观测 卡尔曼 状态机靠外推维持重现后重捕靠峰值抑制与新息门控3~8 ms仅 numpy、opencv表格里最后一行就是这个项目的定位。它不追求在每帧都给出最准的框而是追求“不要错得离谱”这对于长时间无人值守的摄像头场景反而更重要——框偶尔大两个像素没人管框跳到隔壁人身上就是事故。2.2 目录结构与模块职责工程刻意做得很扁全部逻辑集中在一个包里方便直接拷进别的项目sot-kalman-occlusion/ ├── configs/ │ └── default.yaml # 阈值、噪声、搜索窗全部外置 ├── sot/ │ ├── __init__.py │ ├── kalman.py # 8 维状态量的预测/门控更新 │ ├── observer.py # 灰度模板匹配观测器 峰值抑制 │ ├── appearance.py # 灰度直方图做二次外观校验 │ ├── fsm.py # tracking/occluded/lost/dead 状态机 │ ├── tracker.py # 把上面四者串起来的主循环 │ └── viz.py # 画框、画状态、画响应热力图 ├── tools/ │ ├── run_video.py # 单视频推理入口 │ └── eval_seq.py # 逐帧 IoU 评测输出失败区间 ├── data/ │ └── demo.mp4 └── requirements.txtkalman.py只认 numpy 数组不碰图像可以单独拿去做别的状态估计observer.py只认图像和预测框不关心卡尔曼tracker.py是唯一的胶水层所有跨模块的判断都在这里发生。这种切法的好处是调参时你能明确知道该改哪个文件——框抖动改kalman.py的噪声匹配飘改observer.py的搜索窗状态乱跳改fsm.py的阈值。2.3 环境准备与第一次跑通依赖只有四个包版本不用卡太死opencv 用 4.x 任意小版本都行# requirements.txt numpy1.23 opencv-python4.7 PyYAML6.0 tqdm4.65装完直接跑 demo。--init给的是首帧的目标框格式x,y,w,h单位像素左上角为原点python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python tools/run_video.py \ --video data/demo.mp4 \ --init 322,186,94,132 \ --config configs/default.yaml \ --save out/demo_track.mp4 \ --show-state参数含义逐个说清--video支持本地文件和摄像头序号传0就走默认摄像头--init必须落在目标完整可见的帧上别拿被遮挡的第一帧初始化模板一旦抠错后面全是错的--config不传就走内置默认值--save不给就只弹窗不落盘--show-state会在框上方叠加当前状态和外观分调试时强烈建议打开很多时候你以为是滤波飘了其实是状态机一直在 occluded 里出不来。跑完终端会打印总帧数、平均耗时和丢失帧数三个数先用这三个数判断工程是否正常再去看画面。3. 卡尔曼滤波核心8 维状态量的预测、门控与 Joseph 更新3.1 状态量怎么定中心点加宽高各配一维速度状态向量定成[cx, cy, w, h, vx, vy, vw, vh]前四个是观测能直接量到的量后四个是滤波器自己推的。用中心点而不是左上角是因为匀速模型下中心点的运动更接近线性——左上角的位置同时受宽高变化影响目标一缩放左上角就带上了一个伪速度这是新手最容易忽略的问题。import numpy as np def xywh_to_cxcywh(box): x, y, w, h box return np.array([x w / 2.0, y h / 2.0, w, h], dtypenp.float64) def cxcywh_to_xywh(state): cx, cy, w, h state[:4] return np.array([cx - w / 2.0, cy - h / 2.0, w, h], dtypenp.float64) class KalmanBoxTracker: def __init__(self, box, q_scale1e-2, r_scale5e-2, p_scale10.0): self.x np.zeros(8, dtypenp.float64) self.x[:4] xywh_to_cxcywh(box) # 状态转移位置 上一帧位置 速度 * dt self.F np.eye(8) for i in range(4): self.F[i, i 4] 1.0 # 观测矩阵只能看到 cx, cy, w, h self.H np.zeros((4, 8)) self.H[:4, :4] np.eye(4) self.P np.eye(8) * p_scale # 速度项的过程噪声给大一个量级允许目标突然加速或急停 self.Q np.diag([q_scale] * 4 [q_scale * 10] * 4) self.R np.eye(4) * r_scale self.age 0三个噪声矩阵的物理含义要分清P是初始不确定度p_scale10表示“我一开始对目标位置没那么自信”给大一点能让前几帧快速收敛Q是过程噪声描述“运动模型有多不靠谱”速度项乘 10 是给机动留余量R是观测噪声描述“模板匹配给出的框有多不准”这个值越大滤波器越倾向于相信自己的预测抗遮挡能力越强但响应变慢。3.2 predict 与 update门控 Joseph 形式def predict(self, dt1.0): F self.F.copy() for i in range(4): F[i, i 4] dt # 丢帧时用真实时间间隔别硬写 1 self.x F self.x self.P F self.P F.T self.Q # 宽高不能塌缩成 0否则协方差矩阵会退化 self.x[2] max(self.x[2], 4.0) self.x[3] max(self.x[3], 4.0) self.age 1 return cxcywh_to_xywh(self.x) def innovation(self, box): z xywh_to_cxcywh(box) S self.H self.P self.H.T self.R # 新息协方差 y z - self.H self.x # 新息 d2 float(y np.linalg.solve(S, y)) # 马氏距离平方 return z, S, y, d2 def update(self, box, gate13.28): z, S, y, d2 self.innovation(box) if d2 gate: return False, d2 # 观测离预测太远判为不可信跳过这次更新 K self.P self.H.T np.linalg.inv(S) self.x self.x K y # Joseph 形式数值上保证 P 对称正定长序列不会崩 I_KH np.eye(8) - K self.H self.P I_KH self.P I_KH.T K self.R K.T return True, d2predict()里的dt不是摆设。摄像头掉帧、视频时间戳不均匀时固定dt1会让速度项积分超调表现为目标一停框反而往前冲出去一截。update()里那个gate是整个抗遮挡逻辑的第一道闸门新息马氏距离平方服从 4 自由度卡方分布超过阈值就说明这次观测和预测差得太离谱八成是匹配到了背景或者邻近目标。观测维度90% 分位95% 分位99% 分位47.789.4913.28610.6412.5916.81门控阈值建议先用 99% 分位对应的 13.28跑一段有遮挡的序列把每帧的d2打到日志里看分布。如果正常跟踪时d2就已经常在 10 以上说明R给小了观测被过度信任如果目标明明在动、d2却长期贴着 0那是Q太小滤波器变成了低通滤波跟不上机动。3.3 噪声参数怎么调三条经验规则调参这件事没什么玄学按现象对号入座就行。框在静止目标上高频抖动把r_scale往上调从 0.05 试到 0.2让滤波器多信自己目标急转弯时框甩出去半个身位再慢慢回来把q_scale调大给过程噪声更多空间目标被遮住几帧后重新出现框却回不到原位那就是P在遮挡期间被压得太小inflate系数不够这个问题放到下一章的状态机里解决。还有一个常被忽略的点模板更新。很多人以为模板越新越好其实遮挡期间更新模板等于把遮挡物学进去目标再出现时反而匹配不上。我的做法是只在tracking状态下以极低学习率更新template_update: 0.02即 2% 的混合比例并且在遮挡结束后的前 5 帧暂停更新等新息稳定了再恢复。4. 遮挡与重叠判定三重可信度、状态机迁移与峰值抑制4.1 三重可信度峰值、峰值旁瓣比、新息距离只看归一化互相关峰值是不够的。纹理丰富的背景也可能给出 0.6 的峰值而目标被半透明遮挡时峰值掉到 0.3 却仍然是对的。所以判断可信度要三个量一起看import cv2 import numpy as np class TemplateObserver: def __init__(self, frame, box): x, y, w, h [int(round(v)) for v in box] gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) self.template gray[y:y h, x:x w].copy() # 原尺寸保存不用缩放 self.tpl_hist self._hist(self.template) staticmethod def _hist(gray, bins32): h cv2.calcHist([gray], [0], None, [bins], [0, 256]) cv2.normalize(h, h, 1.0, 0.0, cv2.NORM_L1) return h.flatten().astype(np.float32) def locate(self, frame, pred_box, scale2.0, distractorsNone): gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) x, y, w, h pred_box cx, cy x w / 2.0, y h / 2.0 sw, sh w * scale, h * scale sx int(round(cx - sw / 2.0)) sy int(round(cy - sh / 2.0)) H, W gray.shape x0, y0 max(0, sx), max(0, sy) x1, y1 min(W, sx int(sw)), min(H, sy int(sh)) if x1 - x0 self.template.shape[1] or y1 - y0 self.template.shape[0]: return None, 0.0, 0.0 # 搜索窗比模板还小直接放弃 patch gray[y0:y1, x0:x1] resp cv2.matchTemplate(patch, self.template, cv2.TM_CCOEFF_NORMED) if distractors: # 重叠目标的位置在响应图上置负 for (dx, dy, dw, dh) in distractors: px, py int(dx - x0), int(dy - y0) m int(max(dw, dh) * 0.5) resp[max(0, py - m):max(0, py m), max(0, px - m):max(0, px m)] -1.0 _, peak, _, loc cv2.minMaxLoc(resp) psr float((peak - resp.mean()) / (resp.std() 1e-6)) # 峰值位置还原回整图坐标 box np.array([x0 loc[0], y0 loc[1], self.template.shape[1], self.template.shape[0]], dtypenp.float64) # 外观二次校验直方图距离抗形变但区分度低做加权用 crop gray[int(box[1]):int(box[1] box[3]), int(box[0]):int(box[0] box[2])] hist self._hist(crop) bh float(cv2.compareHist(self.tpl_hist, hist, cv2.HISTCMP_BHATTACHARYYA)) score 0.7 * max(0.0, peak) 0.3 * (1.0 - bh) return box, float(score), psrpeak是匹配相似度psr描述的是“峰值比周围的平均水平高出多少个标准差”——它比峰值本身更能说明问题。目标在干净背景上时 PSR 常在 8 以上一旦发生遮挡响应图会被抹平PSR 迅速掉到 3 以下而此时的峰值可能还有 0.4光看峰值根本发现不了。第三重是新息距离d2由卡尔曼那边给出三者一起进状态机。4.2 状态机tracking、occluded、lost、dead 的迁移class TrackFSM: STATES (tracking, occluded, lost, dead) def __init__(self, cfg): self.score_th cfg[score_th] # 外观分下限 self.psr_th cfg[psr_th] # 响应锐度下限 self.lost_after cfg[lost_after] # 连续不可信多少帧转 lost self.max_lost cfg[max_lost] # 连续多少帧后判死 self.state tracking self.miss 0 def step(self, score, psr, gate_ok): visible (score self.score_th) and (psr self.psr_th) and gate_ok if visible: self.miss 0 self.state tracking return self.state self.miss 1 if self.state tracking: self.state occluded # 先降级别急着判丢失 if self.miss self.lost_after: self.state lost if self.miss self.max_lost: self.state dead return self.state状态迁移的关键设计在于“降级而非跳级”。刚被挡住一两帧就直接判 lost会导致目标一露头就得做全图重检测误检率飙升先降到 occluded 只做预测等miss累计到lost_after默认 8 帧再进 lost这 8 帧足够扛过大部分行人擦肩、车辆会车。dead是硬止损max_lost默认 40 帧到了就彻底放弃并向外层抛事件避免在一个已经不存在目标上无限空转。4.3 重叠场景搜索窗缩放、干扰物抑制与配置项两个目标重叠时最典型的失败是匹配峰值跳到邻近目标身上。locate()里的distractors参数就是为这件事准备的把上一帧其他目标的框传进去在响应图的对应区域填 -1等于强制模板匹配“不许看那里”。代价是如果两个目标完全重合连正确位置也会被抹掉这时候score会掉下来状态机自然转入 occluded交给预测去撑反而比硬匹配一个错的强。配套的配置全部外置调参不用改代码# configs/default.yaml observer: search_scale: 2.0 # 搜索窗是预测框的几倍重叠严重时降到 1.5 template_update: 0.02 # 模板慢更新学习率0 表示冻结 kalman: q_scale: 0.01 r_scale: 0.05 p_scale: 10.0 gate_chi2: 13.28 # 4 自由度、99% 置信 occlusion: score_th: 0.45 psr_th: 6.0 lost_after: 8 max_lost: 40 inflate: 1.25 # 遮挡期间过程噪声放大系数主循环里occluded状态下要做两件事跳过update()只保留predict()同时把过程噪声膨胀一次Q[4:, 4:] * inflate。原理是目标被挡住时它的运动方向完全未知速度的不确定度必须放大否则等它重新出现时滤波器还固执地认为它按原速度走新息距离直接超门控观测又被拒掉形成死锁。这个膨胀要在回到tracking时复位不然协方差会一直涨框越来越飘。5. 排查与避坑五条从框漂移到帧率崩掉的血泪记录5.1 运行期问题框和帧率先出问题现象一跟踪框越跑越小最后缩成一个点。原因在宽高的处理上每次 update 都无条件接受观测的宽高而模板匹配给出的框尺寸是固定的等于首帧模板尺寸一旦目标走远变小框却不跟着缩滤波器为了拟合这两个矛盾的量会在宽高维度上产生震荡并逐渐发散。解决办法是给宽高加下限钳制同时对观测尺寸做指数平滑w_obs 0.8 * w_pred 0.2 * w_obs让尺寸变化有个缓冲别一步到位。现象二目标被挡住又出来框停在遮挡物上不动。这是最典型的一类翻车。原因是 occluded 状态下依然调用了update()把遮挡物的匹配结果喂进了滤波器位置和速度同时被拉偏等目标真的出现时新息距离已经大到过不了门控。修法很直接状态机返回occluded/lost时主循环只调predict()一行 update 都不许走同时按上一节说的膨胀Q。现象三CPU 占用飙到 300%帧率掉到 10 FPS。十有八九是全图matchTemplate。搜索窗的scale一旦开到 4 以上模板匹配的计算量是平方级增长的。检查两个地方search_scale是否被误改成大值以及是否每帧都在做整帧的cvtColor。灰度图应该每帧只转一次然后复用locate()内部再转一次就是白白多算一遍。5.2 精度类问题换了数据就打回原形现象四在 demo 视频上很稳换一路摄像头就完全失效。原因是所有阈值都是绝对量。psr_th: 6.0在纹理丰富的场景里随便就能达到到了低对比度、逆光或者雾天的画面里正常跟踪时 PSR 也只有 4 左右阈值一卡状态机全程在 occluded 里打转表现出来就是“框不动”。正确做法是在首帧初始化时做一次自适应标定对首帧做一次自匹配记录此时的 PSR 和 score 作为基准阈值取基准的 60%~70%而不是写死。现象五视频丢帧或变速时预测框突然飞到画面外。根因在dt。很多实现图省事predict()里硬写dt1帧率稳定时看不出问题一旦遇到编码丢帧或者解码卡顿实际间隔变成 300 ms速度项按一帧积分就会超调三倍。修法是把时间戳一路传到predict(dt)并且给速度项加限幅vx clip(vx, -0.5*w, 0.5*w)即单帧位移不超过目标宽度的一半超过就说明状态已经不可信了。这五条里前三条属于“跑不起来”后两条属于“跑起来但不准”排查顺序也建议按这个来——先保证帧率正常、框不崩再去谈精度。日志里把state / score / psr / d2四个量每帧打出来绝大多数问题看一眼曲线就能定位到具体是哪个阈值在作怪。6. 二次开发换观测器、加维度、接业务的三条改造路径这个项目最容易改的地方在于观测器和滤波器是解耦的只要遵守同一个返回约定任何观测源都能塞进来。约定就一行输入当前帧和预测框输出(观测框 xywh, 外观分 0~1, PSR)任一项给不出就返回None让状态机接管。改造点改哪个文件工作量适用场景换观测器接检测器新增detector_observer.py半天目标类别明确、算力充足加状态维度长宽比、旋转kalman.py的 F/H/Q一天车辆、俯视角度大的场景换外观模型颜色/深度特征appearance.py半天灰度模板失效的低对比场景输出接入RTSP、串口、消息队列tools/run_video.py两小时落地上线接自己的检测器时把locate()实现成一个包装层就行注意保留 PSR 这个量——检测器一般不给响应图可以用检测分数和 IoU 预测框的加权组合替代但状态机里的阈值需要重新标一遍from sot.observer import TemplateObserver class DetectorObserver(TemplateObserver): 把任意检测器包成观测器detector.predict(img) - [[x1,y1,x2,y2,score], ...] def __init__(self, detector, frame, box): super().__init__(frame, box) # 仍然保留模板检测器失效时兜底 self.detector detector def locate(self, frame, pred_box, scale2.0, distractorsNone): dets self.detector.predict(frame) if not dets: return None, 0.0, 0.0 best, best_iou None, 0.0 for x1, y1, x2, y2, conf in dets: box (x1, y1, x2 - x1, y2 - y1) iou self._iou(box, pred_box) if iou best_iou: best, best_iou box, iou if best is None or best_iou 0.2: # 检测结果和预测对不上交给模板兜底 return super().locate(frame, pred_box, scale, distractors) score 0.5 * best_iou 0.5 * conf return best, float(score), float(conf * 10.0) # 用置信度折算一个伪 PSR改造完必须验证别凭肉眼看。tools/eval_seq.py会逐帧算 IoU 并输出一条曲线我习惯把IoU 0.5的连续帧区间抽出来和状态机日志对齐着看如果掉分区间正好落在occluded上说明是遮挡处理不够如果落在tracking上那是观测本身出了问题跟滤波没关系。这个对齐动作能省掉大量瞎猜。最后说一个我踩过的教训。早期我为了“稳”把所有阈值都往保守调结果跟踪器变得极度迟钝目标明明还在画面里它却一直判 occluded 靠外推走最后漂到背景上。从那以后我每次改完参数都强制走一遍“先跑干净序列看基准分再跑遮挡序列看恢复帧数”的流程两个数都达标才允许合并。跟踪这行没有银弹参数只是把错误从一个场景挪到另一个场景能做的就是把每次挪动的方向记录下来。希望帮到你。本文还有配套的精品资源点击获取
简介面向计算机视觉初学者与目标跟踪方向的学习者这份项目围绕遮挡与重叠场景下的单目标跟踪展开将卡尔曼滤波的预测—更新机制与最大IOU匹配结合用于缓解目标被部分遮挡或相互重叠时跟丢的问题属于机器学习在视觉任务中的进阶实践素材。压缩包共338个文件、约25.87MB主体为327个txt标签文件配套4个xml配置、2个Python脚本及少量pyc缓存与1段mp4测试视频标签与视频可直接用于跑通跟踪流程并评估效果。已有514人学习下载。读者可从中获得卡尔曼滤波器初始化与参数设置的实现思路理解预测与更新步骤如何平滑跟踪噪声并借助辅助工具模块中的图像处理、目标检测与IOU计算等通用函数掌握跟踪评估环节再通过测试视频观察遮挡后重新找回目标的表现目录按算法实现、辅助工具、标签数据与测试素材划分便于逐模块拆解与二次调试。1. 遮挡下的单目标跟踪为什么“预测”比“检测”更靠谱监控画面里两个人擦肩而过跟踪框“唰”地跳到另一个人身上这是目标跟踪在遮挡与重叠场景下最典型的失败情形。做计算机视觉的同学大多遇过这种情况检测器每帧都能输出一个框可目标被挡住三五帧后检测结果立刻归零整条轨迹就断在那里再出现时已经认不出来了。这个项目做的事很朴素用卡尔曼滤波维护目标运动的连续状态用灰度模板匹配提供一个成本很低的观测再叠一层状态机判断“这次的观测到底可不可信”当目标被遮挡、或被重叠目标干扰时让跟踪器依然保持对目标的关联。它不依赖 GPU也不加载预训练权重核心逻辑两百来行 PythonCPU 上跑 640×480 的视频能到六十帧上下。适合两类人一是在边缘盒子或嵌入式板子上做跟踪、不想背负整套深度学习框架的开发者二是刚接触目标跟踪想沿着状态估计这条主线把 predict/update、新息门控、重检测一次串起来的人。整个项目最值钱的不是那个 8 维矩阵而是“观测不可信时该怎么办”的判断逻辑代码不长但要把它调稳还是有不少细节需要注意。2. 工程骨架拆解从读帧到出框的三段流水线与目录职责2.1 选型为什么是“模板匹配做观测 卡尔曼滤波做状态”很多刚上手的人会默认“跟踪 检测 ID 匹配”其实在单目标跟踪的经典解法里检测器只是可选项。遮挡发生时检测器给不出框两个目标重叠时检测器给出两个框且分数接近——这两个问题都不是“换个更强的检测器”能根治的缺的是对目标运动的连续建模。卡尔曼滤波的价值恰好在这里它不产生观测只维护一个“目标大概在哪、朝哪个方向走、走多快”的信念观测断了它还能靠匀速模型外推十几帧等目标重新露出来再接上。所以这个项目的流水线是三段第一段是观测器在预测框周围扩一圈搜索窗用首帧抠出来的灰度模板做归一化互相关匹配取响应峰值位置当观测第二段是卡尔曼滤波器把观测塞进 update或者判断这次观测不可信就只做 predict第三段是状态机与外观校验用峰值、峰值旁瓣比、新息马氏距离三个量决定当前处于 tracking、occluded 还是 lost。三段之间是单向数据流每段都能单独替换这也是后面二次开发最省事的地方。方案遮挡 5 帧后两目标重叠CPU 单帧耗时额外依赖检测器逐帧输出直接丢框框在两个目标间跳20~60 ms模型与权重相关滤波类方法框缓慢漂到遮挡物上易被邻近目标吸走5~15 ms需 FFT尺度固定孪生网络类方法依赖额外重检测模块相对较好15~40 msGPUGPU 与权重模板观测 卡尔曼 状态机靠外推维持重现后重捕靠峰值抑制与新息门控3~8 ms仅 numpy、opencv表格里最后一行就是这个项目的定位。它不追求在每帧都给出最准的框而是追求“不要错得离谱”这对于长时间无人值守的摄像头场景反而更重要——框偶尔大两个像素没人管框跳到隔壁人身上就是事故。2.2 目录结构与模块职责工程刻意做得很扁全部逻辑集中在一个包里方便直接拷进别的项目sot-kalman-occlusion/ ├── configs/ │ └── default.yaml # 阈值、噪声、搜索窗全部外置 ├── sot/ │ ├── __init__.py │ ├── kalman.py # 8 维状态量的预测/门控更新 │ ├── observer.py # 灰度模板匹配观测器 峰值抑制 │ ├── appearance.py # 灰度直方图做二次外观校验 │ ├── fsm.py # tracking/occluded/lost/dead 状态机 │ ├── tracker.py # 把上面四者串起来的主循环 │ └── viz.py # 画框、画状态、画响应热力图 ├── tools/ │ ├── run_video.py # 单视频推理入口 │ └── eval_seq.py # 逐帧 IoU 评测输出失败区间 ├── data/ │ └── demo.mp4 └── requirements.txtkalman.py只认 numpy 数组不碰图像可以单独拿去做别的状态估计observer.py只认图像和预测框不关心卡尔曼tracker.py是唯一的胶水层所有跨模块的判断都在这里发生。这种切法的好处是调参时你能明确知道该改哪个文件——框抖动改kalman.py的噪声匹配飘改observer.py的搜索窗状态乱跳改fsm.py的阈值。2.3 环境准备与第一次跑通依赖只有四个包版本不用卡太死opencv 用 4.x 任意小版本都行# requirements.txt numpy1.23 opencv-python4.7 PyYAML6.0 tqdm4.65装完直接跑 demo。--init给的是首帧的目标框格式x,y,w,h单位像素左上角为原点python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python tools/run_video.py \ --video data/demo.mp4 \ --init 322,186,94,132 \ --config configs/default.yaml \ --save out/demo_track.mp4 \ --show-state参数含义逐个说清--video支持本地文件和摄像头序号传0就走默认摄像头--init必须落在目标完整可见的帧上别拿被遮挡的第一帧初始化模板一旦抠错后面全是错的--config不传就走内置默认值--save不给就只弹窗不落盘--show-state会在框上方叠加当前状态和外观分调试时强烈建议打开很多时候你以为是滤波飘了其实是状态机一直在 occluded 里出不来。跑完终端会打印总帧数、平均耗时和丢失帧数三个数先用这三个数判断工程是否正常再去看画面。3. 卡尔曼滤波核心8 维状态量的预测、门控与 Joseph 更新3.1 状态量怎么定中心点加宽高各配一维速度状态向量定成[cx, cy, w, h, vx, vy, vw, vh]前四个是观测能直接量到的量后四个是滤波器自己推的。用中心点而不是左上角是因为匀速模型下中心点的运动更接近线性——左上角的位置同时受宽高变化影响目标一缩放左上角就带上了一个伪速度这是新手最容易忽略的问题。import numpy as np def xywh_to_cxcywh(box): x, y, w, h box return np.array([x w / 2.0, y h / 2.0, w, h], dtypenp.float64) def cxcywh_to_xywh(state): cx, cy, w, h state[:4] return np.array([cx - w / 2.0, cy - h / 2.0, w, h], dtypenp.float64) class KalmanBoxTracker: def __init__(self, box, q_scale1e-2, r_scale5e-2, p_scale10.0): self.x np.zeros(8, dtypenp.float64) self.x[:4] xywh_to_cxcywh(box) # 状态转移位置 上一帧位置 速度 * dt self.F np.eye(8) for i in range(4): self.F[i, i 4] 1.0 # 观测矩阵只能看到 cx, cy, w, h self.H np.zeros((4, 8)) self.H[:4, :4] np.eye(4) self.P np.eye(8) * p_scale # 速度项的过程噪声给大一个量级允许目标突然加速或急停 self.Q np.diag([q_scale] * 4 [q_scale * 10] * 4) self.R np.eye(4) * r_scale self.age 0三个噪声矩阵的物理含义要分清P是初始不确定度p_scale10表示“我一开始对目标位置没那么自信”给大一点能让前几帧快速收敛Q是过程噪声描述“运动模型有多不靠谱”速度项乘 10 是给机动留余量R是观测噪声描述“模板匹配给出的框有多不准”这个值越大滤波器越倾向于相信自己的预测抗遮挡能力越强但响应变慢。3.2 predict 与 update门控 Joseph 形式def predict(self, dt1.0): F self.F.copy() for i in range(4): F[i, i 4] dt # 丢帧时用真实时间间隔别硬写 1 self.x F self.x self.P F self.P F.T self.Q # 宽高不能塌缩成 0否则协方差矩阵会退化 self.x[2] max(self.x[2], 4.0) self.x[3] max(self.x[3], 4.0) self.age 1 return cxcywh_to_xywh(self.x) def innovation(self, box): z xywh_to_cxcywh(box) S self.H self.P self.H.T self.R # 新息协方差 y z - self.H self.x # 新息 d2 float(y np.linalg.solve(S, y)) # 马氏距离平方 return z, S, y, d2 def update(self, box, gate13.28): z, S, y, d2 self.innovation(box) if d2 gate: return False, d2 # 观测离预测太远判为不可信跳过这次更新 K self.P self.H.T np.linalg.inv(S) self.x self.x K y # Joseph 形式数值上保证 P 对称正定长序列不会崩 I_KH np.eye(8) - K self.H self.P I_KH self.P I_KH.T K self.R K.T return True, d2predict()里的dt不是摆设。摄像头掉帧、视频时间戳不均匀时固定dt1会让速度项积分超调表现为目标一停框反而往前冲出去一截。update()里那个gate是整个抗遮挡逻辑的第一道闸门新息马氏距离平方服从 4 自由度卡方分布超过阈值就说明这次观测和预测差得太离谱八成是匹配到了背景或者邻近目标。观测维度90% 分位95% 分位99% 分位47.789.4913.28610.6412.5916.81门控阈值建议先用 99% 分位对应的 13.28跑一段有遮挡的序列把每帧的d2打到日志里看分布。如果正常跟踪时d2就已经常在 10 以上说明R给小了观测被过度信任如果目标明明在动、d2却长期贴着 0那是Q太小滤波器变成了低通滤波跟不上机动。3.3 噪声参数怎么调三条经验规则调参这件事没什么玄学按现象对号入座就行。框在静止目标上高频抖动把r_scale往上调从 0.05 试到 0.2让滤波器多信自己目标急转弯时框甩出去半个身位再慢慢回来把q_scale调大给过程噪声更多空间目标被遮住几帧后重新出现框却回不到原位那就是P在遮挡期间被压得太小inflate系数不够这个问题放到下一章的状态机里解决。还有一个常被忽略的点模板更新。很多人以为模板越新越好其实遮挡期间更新模板等于把遮挡物学进去目标再出现时反而匹配不上。我的做法是只在tracking状态下以极低学习率更新template_update: 0.02即 2% 的混合比例并且在遮挡结束后的前 5 帧暂停更新等新息稳定了再恢复。4. 遮挡与重叠判定三重可信度、状态机迁移与峰值抑制4.1 三重可信度峰值、峰值旁瓣比、新息距离只看归一化互相关峰值是不够的。纹理丰富的背景也可能给出 0.6 的峰值而目标被半透明遮挡时峰值掉到 0.3 却仍然是对的。所以判断可信度要三个量一起看import cv2 import numpy as np class TemplateObserver: def __init__(self, frame, box): x, y, w, h [int(round(v)) for v in box] gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) self.template gray[y:y h, x:x w].copy() # 原尺寸保存不用缩放 self.tpl_hist self._hist(self.template) staticmethod def _hist(gray, bins32): h cv2.calcHist([gray], [0], None, [bins], [0, 256]) cv2.normalize(h, h, 1.0, 0.0, cv2.NORM_L1) return h.flatten().astype(np.float32) def locate(self, frame, pred_box, scale2.0, distractorsNone): gray cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) x, y, w, h pred_box cx, cy x w / 2.0, y h / 2.0 sw, sh w * scale, h * scale sx int(round(cx - sw / 2.0)) sy int(round(cy - sh / 2.0)) H, W gray.shape x0, y0 max(0, sx), max(0, sy) x1, y1 min(W, sx int(sw)), min(H, sy int(sh)) if x1 - x0 self.template.shape[1] or y1 - y0 self.template.shape[0]: return None, 0.0, 0.0 # 搜索窗比模板还小直接放弃 patch gray[y0:y1, x0:x1] resp cv2.matchTemplate(patch, self.template, cv2.TM_CCOEFF_NORMED) if distractors: # 重叠目标的位置在响应图上置负 for (dx, dy, dw, dh) in distractors: px, py int(dx - x0), int(dy - y0) m int(max(dw, dh) * 0.5) resp[max(0, py - m):max(0, py m), max(0, px - m):max(0, px m)] -1.0 _, peak, _, loc cv2.minMaxLoc(resp) psr float((peak - resp.mean()) / (resp.std() 1e-6)) # 峰值位置还原回整图坐标 box np.array([x0 loc[0], y0 loc[1], self.template.shape[1], self.template.shape[0]], dtypenp.float64) # 外观二次校验直方图距离抗形变但区分度低做加权用 crop gray[int(box[1]):int(box[1] box[3]), int(box[0]):int(box[0] box[2])] hist self._hist(crop) bh float(cv2.compareHist(self.tpl_hist, hist, cv2.HISTCMP_BHATTACHARYYA)) score 0.7 * max(0.0, peak) 0.3 * (1.0 - bh) return box, float(score), psrpeak是匹配相似度psr描述的是“峰值比周围的平均水平高出多少个标准差”——它比峰值本身更能说明问题。目标在干净背景上时 PSR 常在 8 以上一旦发生遮挡响应图会被抹平PSR 迅速掉到 3 以下而此时的峰值可能还有 0.4光看峰值根本发现不了。第三重是新息距离d2由卡尔曼那边给出三者一起进状态机。4.2 状态机tracking、occluded、lost、dead 的迁移class TrackFSM: STATES (tracking, occluded, lost, dead) def __init__(self, cfg): self.score_th cfg[score_th] # 外观分下限 self.psr_th cfg[psr_th] # 响应锐度下限 self.lost_after cfg[lost_after] # 连续不可信多少帧转 lost self.max_lost cfg[max_lost] # 连续多少帧后判死 self.state tracking self.miss 0 def step(self, score, psr, gate_ok): visible (score self.score_th) and (psr self.psr_th) and gate_ok if visible: self.miss 0 self.state tracking return self.state self.miss 1 if self.state tracking: self.state occluded # 先降级别急着判丢失 if self.miss self.lost_after: self.state lost if self.miss self.max_lost: self.state dead return self.state状态迁移的关键设计在于“降级而非跳级”。刚被挡住一两帧就直接判 lost会导致目标一露头就得做全图重检测误检率飙升先降到 occluded 只做预测等miss累计到lost_after默认 8 帧再进 lost这 8 帧足够扛过大部分行人擦肩、车辆会车。dead是硬止损max_lost默认 40 帧到了就彻底放弃并向外层抛事件避免在一个已经不存在目标上无限空转。4.3 重叠场景搜索窗缩放、干扰物抑制与配置项两个目标重叠时最典型的失败是匹配峰值跳到邻近目标身上。locate()里的distractors参数就是为这件事准备的把上一帧其他目标的框传进去在响应图的对应区域填 -1等于强制模板匹配“不许看那里”。代价是如果两个目标完全重合连正确位置也会被抹掉这时候score会掉下来状态机自然转入 occluded交给预测去撑反而比硬匹配一个错的强。配套的配置全部外置调参不用改代码# configs/default.yaml observer: search_scale: 2.0 # 搜索窗是预测框的几倍重叠严重时降到 1.5 template_update: 0.02 # 模板慢更新学习率0 表示冻结 kalman: q_scale: 0.01 r_scale: 0.05 p_scale: 10.0 gate_chi2: 13.28 # 4 自由度、99% 置信 occlusion: score_th: 0.45 psr_th: 6.0 lost_after: 8 max_lost: 40 inflate: 1.25 # 遮挡期间过程噪声放大系数主循环里occluded状态下要做两件事跳过update()只保留predict()同时把过程噪声膨胀一次Q[4:, 4:] * inflate。原理是目标被挡住时它的运动方向完全未知速度的不确定度必须放大否则等它重新出现时滤波器还固执地认为它按原速度走新息距离直接超门控观测又被拒掉形成死锁。这个膨胀要在回到tracking时复位不然协方差会一直涨框越来越飘。5. 排查与避坑五条从框漂移到帧率崩掉的血泪记录5.1 运行期问题框和帧率先出问题现象一跟踪框越跑越小最后缩成一个点。原因在宽高的处理上每次 update 都无条件接受观测的宽高而模板匹配给出的框尺寸是固定的等于首帧模板尺寸一旦目标走远变小框却不跟着缩滤波器为了拟合这两个矛盾的量会在宽高维度上产生震荡并逐渐发散。解决办法是给宽高加下限钳制同时对观测尺寸做指数平滑w_obs 0.8 * w_pred 0.2 * w_obs让尺寸变化有个缓冲别一步到位。现象二目标被挡住又出来框停在遮挡物上不动。这是最典型的一类翻车。原因是 occluded 状态下依然调用了update()把遮挡物的匹配结果喂进了滤波器位置和速度同时被拉偏等目标真的出现时新息距离已经大到过不了门控。修法很直接状态机返回occluded/lost时主循环只调predict()一行 update 都不许走同时按上一节说的膨胀Q。现象三CPU 占用飙到 300%帧率掉到 10 FPS。十有八九是全图matchTemplate。搜索窗的scale一旦开到 4 以上模板匹配的计算量是平方级增长的。检查两个地方search_scale是否被误改成大值以及是否每帧都在做整帧的cvtColor。灰度图应该每帧只转一次然后复用locate()内部再转一次就是白白多算一遍。5.2 精度类问题换了数据就打回原形现象四在 demo 视频上很稳换一路摄像头就完全失效。原因是所有阈值都是绝对量。psr_th: 6.0在纹理丰富的场景里随便就能达到到了低对比度、逆光或者雾天的画面里正常跟踪时 PSR 也只有 4 左右阈值一卡状态机全程在 occluded 里打转表现出来就是“框不动”。正确做法是在首帧初始化时做一次自适应标定对首帧做一次自匹配记录此时的 PSR 和 score 作为基准阈值取基准的 60%~70%而不是写死。现象五视频丢帧或变速时预测框突然飞到画面外。根因在dt。很多实现图省事predict()里硬写dt1帧率稳定时看不出问题一旦遇到编码丢帧或者解码卡顿实际间隔变成 300 ms速度项按一帧积分就会超调三倍。修法是把时间戳一路传到predict(dt)并且给速度项加限幅vx clip(vx, -0.5*w, 0.5*w)即单帧位移不超过目标宽度的一半超过就说明状态已经不可信了。这五条里前三条属于“跑不起来”后两条属于“跑起来但不准”排查顺序也建议按这个来——先保证帧率正常、框不崩再去谈精度。日志里把state / score / psr / d2四个量每帧打出来绝大多数问题看一眼曲线就能定位到具体是哪个阈值在作怪。6. 二次开发换观测器、加维度、接业务的三条改造路径这个项目最容易改的地方在于观测器和滤波器是解耦的只要遵守同一个返回约定任何观测源都能塞进来。约定就一行输入当前帧和预测框输出(观测框 xywh, 外观分 0~1, PSR)任一项给不出就返回None让状态机接管。改造点改哪个文件工作量适用场景换观测器接检测器新增detector_observer.py半天目标类别明确、算力充足加状态维度长宽比、旋转kalman.py的 F/H/Q一天车辆、俯视角度大的场景换外观模型颜色/深度特征appearance.py半天灰度模板失效的低对比场景输出接入RTSP、串口、消息队列tools/run_video.py两小时落地上线接自己的检测器时把locate()实现成一个包装层就行注意保留 PSR 这个量——检测器一般不给响应图可以用检测分数和 IoU 预测框的加权组合替代但状态机里的阈值需要重新标一遍from sot.observer import TemplateObserver class DetectorObserver(TemplateObserver): 把任意检测器包成观测器detector.predict(img) - [[x1,y1,x2,y2,score], ...] def __init__(self, detector, frame, box): super().__init__(frame, box) # 仍然保留模板检测器失效时兜底 self.detector detector def locate(self, frame, pred_box, scale2.0, distractorsNone): dets self.detector.predict(frame) if not dets: return None, 0.0, 0.0 best, best_iou None, 0.0 for x1, y1, x2, y2, conf in dets: box (x1, y1, x2 - x1, y2 - y1) iou self._iou(box, pred_box) if iou best_iou: best, best_iou box, iou if best is None or best_iou 0.2: # 检测结果和预测对不上交给模板兜底 return super().locate(frame, pred_box, scale, distractors) score 0.5 * best_iou 0.5 * conf return best, float(score), float(conf * 10.0) # 用置信度折算一个伪 PSR改造完必须验证别凭肉眼看。tools/eval_seq.py会逐帧算 IoU 并输出一条曲线我习惯把IoU 0.5的连续帧区间抽出来和状态机日志对齐着看如果掉分区间正好落在occluded上说明是遮挡处理不够如果落在tracking上那是观测本身出了问题跟滤波没关系。这个对齐动作能省掉大量瞎猜。最后说一个我踩过的教训。早期我为了“稳”把所有阈值都往保守调结果跟踪器变得极度迟钝目标明明还在画面里它却一直判 occluded 靠外推走最后漂到背景上。从那以后我每次改完参数都强制走一遍“先跑干净序列看基准分再跑遮挡序列看恢复帧数”的流程两个数都达标才允许合并。跟踪这行没有银弹参数只是把错误从一个场景挪到另一个场景能做的就是把每次挪动的方向记录下来。希望帮到你。本文还有配套的精品资源点击获取
/YOLO人头检测)
