摄像头怎么数人：实时区域人数统计入门，以及数字为什么会跳

先划区域：一个鼠标点选的小工具

区域坐标手填很不现实。花 40 行写个点选工具，一劳永逸：

# pick_zones.py —— 在视频首帧上用鼠标划出区域，存成 JSON
import json

import cv2
import numpy as np


def pick_zones(video_path, out_path="zones.json"):
    """左键加点，右键撤销，回车闭合一个区域，q 保存退出。"""
    cap = cv2.VideoCapture(video_path)
    ok, frame = cap.read()
    cap.release()
    if not ok:
        raise SystemExit("读不到视频首帧")

    points, zones = [], []
    window = "pick zones"

    def on_mouse(event, x, y, _flags, _param):
        if event == cv2.EVENT_LBUTTONDOWN:
            points.append((x, y))
        elif event == cv2.EVENT_RBUTTONDOWN and points:
            points.pop()

    cv2.namedWindow(window)
    cv2.setMouseCallback(window, on_mouse)

    while True:
        canvas = frame.copy()
        if len(points) > 1:
            cv2.polylines(canvas, [np.array(points)], False, (0, 255, 0), 2)
        for p in points:
            cv2.circle(canvas, p, 5, (0, 0, 255), -1)
        cv2.putText(canvas,
                    f"points={len(points)}  ENTER=close zone  q=save&quit",
                    (20, 40), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (255, 255, 255), 2)
        cv2.imshow(window, canvas)

        key = cv2.waitKey(20) & 0xFF
        if key == 13 and len(points) >= 3:          # 回车：闭合当前区域
            zones.append({"name": f"Zone{len(zones) + 1}", "polygon": points})
            points = []
        elif key == ord("q"):
            break

    cv2.destroyAllWindows()
    with open(out_path, "w", encoding="utf-8") as f:
        json.dump({"zones": zones}, f, ensure_ascii=False, indent=2)
    print(f"已保存 {len(zones)} 个区域到 {out_path}")


if __name__ == "__main__":
    pick_zones("meeting_room.mp4")

产出长这样：

{
  "zones": [
    { "name": "Zone1", "polygon": [[120, 300], [900, 300], [900, 700], [120, 700]] }
  ]
}

💡 划区域时，请把顶点对着人物的脚部落点位置来画，而不是对着桌子的视觉边缘。因为判定用的是脚点，两者视角不同。

去抖逻辑

# debounce.py
from dataclasses import dataclass

import numpy as np
import supervision as sv


@dataclass
class TrackState:
    """单个跟踪目标相对某个区域的状态。"""
    inside_streak: int = 0      # 连续在区内的帧数
    outside_streak: int = 0     # 连续在区外的帧数
    confirmed: bool = False     # 去抖后的最终判定：算不算 "在区域里"
    last_frame: int = 0         # 最后一次出现是第几帧


class DebouncedZone:
    """带滞回去抖的区域计数器。

    enter_frames: 连续多少帧在区内，才确认"进入"
    exit_frames:  连续多少帧在区外，才确认"离开"
    ttl:          目标消失多少帧后清理它的状态
    """

    def __init__(self, polygon, enter_frames=5, exit_frames=5, ttl=30):
        self.zone = sv.PolygonZone(polygon=np.asarray(polygon, dtype=np.int32))
        self.enter_frames = enter_frames
        self.exit_frames = exit_frames
        self.ttl = ttl
        self.states: dict[int, TrackState] = {}

    def update(self, detections, frame_idx: int) -> int:
        # 只要原始布尔判定；zone.current_count 是未去抖的，不能用
        raw_mask = self.zone.trigger(detections)

        if detections.tracker_id is None:
            return self._count()          # 还没接跟踪器，直接返回当前计数

        for track_id, is_in in zip(detections.tracker_id, raw_mask):
            state = self.states.setdefault(int(track_id), TrackState())
            state.last_frame = frame_idx

            if is_in:
                state.inside_streak += 1
                state.outside_streak = 0
            else:
                state.outside_streak += 1
                state.inside_streak = 0

            if not state.confirmed and state.inside_streak >= self.enter_frames:
                state.confirmed = True
            elif state.confirmed and state.outside_streak >= self.exit_frames:
                state.confirmed = False

        self._evict(frame_idx)
        return self._count()

    def _count(self) -> int:
        return sum(s.confirmed for s in self.states.values())

    def _evict(self, frame_idx: int) -> None:
        """清理长时间没出现的目标。

        不做这一步，人数会只增不减 —— 见下面「`_evict` 为什么不能省」。
        """
        expired = [tid for tid, s in self.states.items()
                   if frame_idx - s.last_frame > self.ttl]
        for tid in expired:
            del self.states[tid]

_evict 为什么不能省

这是最容易漏掉的一段，漏了会出一个很难查的 bug。

问题：一个原本被确认为”在区内”的人走出了画面。跟踪器找不到他，就不再返回他的 tracker_id 了。

但我们的 states 里，那条 {track_id: confirmed=True} 的记录还在。没人来把它改成 False——因为没人再触发它了。

结果就是：这个人走了，数字不减。 下一个人进来，数字继续加。跑一下午，人数能涨到几百。

回到第五节那个类比：这就是会话没有超时。 你维护了一个 Map<sessionId, Session>，客户端断开了、不再发心跳，但你的 Map 里那条记录永远留着。内存泄漏和统计虚高是同一个根因。

ttl 就是 session timeout。

主循环

# count_people.py
import json

import cv2
import numpy as np
import supervision as sv
from ultralytics import YOLO

from pick_zones import pick_zones          # 上面那个工具
from debounce import DebouncedZone         # 上面的 DebouncedZone

VIDEO = "meeting_room.mp4"      # 填 0 则用本机摄像头
ZONES = "zones.json"
PERSON_CLASS_ID = 0             # 数据集里「人」是第 0 类


def detect(frame, model):
    """检测这一步。封装成一个函数，方便日后换模型。"""
    result = model(frame, imgsz=640, conf=0.35, classes=[PERSON_CLASS_ID],
                   verbose=False)[0]
    return sv.Detections.from_ultralytics(result)


def main():
    if not __import__("os").path.exists(ZONES):
        pick_zones(VIDEO, ZONES)

    with open(ZONES, encoding="utf-8") as f:
        zone_cfgs = json.load(f)["zones"]

    zones = [DebouncedZone(z["polygon"], enter_frames=5, exit_frames=5, ttl=30)
             for z in zone_cfgs]

    model = YOLO("yolo11n.pt")
    tracker = sv.ByteTrack()
    box_annotator = sv.BoxAnnotator()
    zone_annotators = [
        sv.PolygonZoneAnnotator(zone=z.zone, color=sv.Color.GREEN,
                                display_in_zone_count=True)
        for z in zones
    ]

    cap = cv2.VideoCapture(VIDEO)
    frame_idx = 0

    while True:
        ok, frame = cap.read()
        if not ok:
            break

        detections = detect(frame, model)
        detections = tracker.update_with_detections(detections)   # 必须先于区域判定

        counts = [z.update(detections, frame_idx) for z in zones]

        for annotator in zone_annotators:
            frame = annotator.annotate(frame)

        labels = [f"#{int(tid)} {conf:.2f}"
                  for tid, conf in zip(detections.tracker_id, detections.confidence)]
        frame = box_annotator.annotate(frame, detections, labels)

        for i, count in enumerate(counts):
            cv2.putText(frame, f"{zone_cfgs[i]['name']}: {count}",
                        (20, 90 + i * 45), cv2.FONT_HERSHEY_SIMPLEX,
                        1.3, (0, 255, 0), 3)

        cv2.imshow("vision-pe", frame)
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
        frame_idx += 1

    cap.release()
    cv2.destroyAllWindows()


if __name__ == "__main__":
    main()

跑起来你会看到：人身上有框和 ID、区域是多边形（上面画着未去抖的原始计数）、左上角是去抖后的计数。

📌 顺序不能颠倒：tracker.update_with_detections() 必须在 zone.update() 之前。区域判定依赖 tracker_id，没跟踪就没有 ID。

🐌 如果帧率不够，按这个顺序试：① imgsz 从 640 降到 480 ② 换 ONNX / OpenVINO 推理 ③ 不必每帧都推理——隔 N 帧跑一次检测，中间帧复用上次结果。

# test_debounce.py
import numpy as np
import pytest
import supervision as sv

from debounce import DebouncedZone

# 一个正方形区域：x 从 100 到 300，y 从 100 到 300
ZONE = np.array([[100, 100], [300, 100], [300, 300], [100, 300]])


def make_dets(track_ids, foot_y):
    """构造一批脚点在 (200, foot_y) 的检测框。

    框的底边中点 = ((x1+x2)/2, y2)，这里固定 x1=180, x2=220, y2=foot_y。
    """
    boxes = [[180, y - 100, 220, y] for y in foot_y]
    return sv.Detections(
        xyxy=np.array(boxes, dtype=float),
        confidence=np.ones(len(track_ids)),
        class_id=np.zeros(len(track_ids), dtype=int),
        tracker_id=np.array(track_ids, dtype=int),
    )


def test_边界抖动不改变计数():
    """人在边界线上反复进出 —— 这是最常见的抖动场景。"""
    zone = DebouncedZone(ZONE, enter_frames=5, exit_frames=5)

    # 先稳稳地在区内确认下来（y=200 在区域内）
    for i in range(10):
        assert zone.update(make_dets([1], [200]), i) == 1

    # 现在让脚点在边界 y=100 附近来回横跳
    for i in range(10, 60):
        y = 97 if i % 2 else 103        # 97 在区外，103 在区内
        count = zone.update(make_dets([1], [y]), i)
        assert count == 1, f"第 {i} 帧计数跳成了 {count}"


def test_快速穿过不计入():
    """只在区内待了 2 帧（< enter_frames）的人，不该被计数。"""
    zone = DebouncedZone(ZONE, enter_frames=5, exit_frames=5)
    for i in range(10):                              # 一直在区外
        assert zone.update(make_dets([1], [50]), i) == 0
    for i in range(10, 12):                          # 快速穿过，只有 2 帧
        assert zone.update(make_dets([1], [200]), i) == 0
    for i in range(12, 30):                          # 又出去了
        assert zone.update(make_dets([1], [50]), i) == 0


def test_目标消失后状态被清理():
    """不做 _evict 就会挂在这个测试上 —— 人数只增不减。"""
    zone = DebouncedZone(ZONE, enter_frames=5, exit_frames=5, ttl=30)
    for i in range(10):
        assert zone.update(make_dets([1], [200]), i) == 1

    # 人走了：跟踪器不再返回这个 ID，传空检测
    empty = sv.Detections.empty()
    empty.tracker_id = np.array([], dtype=int)
    for i in range(10, 50):
        count = zone.update(empty, i)
    assert count == 0, "目标消失后没有清理，出现了幽灵计数"

跑 pytest，三个全绿，去抖逻辑就是对的。

这三个测试里，第三个最容易在真实项目里被漏掉——因为它的症状（数字缓慢虚高）要在跑很久之后才明显。