人流量统计设备¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
本项目基于Quectel Pi M2智能主控板开发，是一套轻量级人流量统计解决方案，集成了目标检测、目标跟踪和行人重识别（ReID）等技术，具备以下核心功能：
实时人体检测：在视频流中实时识别人体目标；
稳定目标跟踪：采用ByteTrack算法实现高精度目标跟踪；
智能去重统计：基于ReID特征进行人员身份去重；
多源视频支持：兼容USB摄像头、IP摄像头及本地视频文件；
多维度统计：提供实时人数、累计去重人数及进出方向统计。
开发资源汇总¶
开发配件清单¶
备注
以下配件清单仅供参考，实际开发环境可根据需求调整。例如，通过SSH远程连接开发时，可省略显示器和USB扩展坞；摄像头根据实际需要选择即可。
配件名称 |
数量 |
规格参数 |
|---|---|---|
Quectel Pi M2智能主控板 |
1块 |
- |
电源适配器 |
1个 |
27W USB Type-C接口充电器；1.2米线长；PD快充； |
HDMI A 型对公线 |
1根 |
HDMI 2.0；线长1 m；接口：HDMI-A（公头）-HDMI-A（公头） |
网线 |
1根 |
线长：1 m；传输速率：千兆 |
CPU散热风扇（可选） |
1个 |
|
网络摄像头 |
1个 |
|
USB摄像头模块 |
1个 |
|
显示屏 |
1个 |
24英寸HDMI显示器 |
配件实物参考¶
快速上手¶
开发准备¶
Quectel Pi M2智能主控板出厂预装 Debian 13 系统镜像，无需重新烧录系统，按照以下步骤即可开始开发。
硬件连接¶
按照以下步骤完成所有硬件连接，步骤编号与接口示意图中的标注一致：
显示连接： 将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。
网络连接： 确保路由器已接入互联网。将网线的一端连接到智能主控板的千兆以太网端口，另一端连接到路由器的以太网端口。
输入设备连接： 将USB键盘、鼠标和USB摄像头模块连接到智能主控板的USB接口；若使用无线输入设备，将无线接收器连接到智能主控板的USB接口即可。
供电连接： 将USB-A电源线的USB-A端连接到电源适配器的输出端，将USB-C端连接到智能主控板的电源输入接口（通常标注为 POWER IN）。
网络摄像头连接： 使用网络摄像头的自带电源线接通电源，并确保其与主控板处于同一局域网内。
模型准备¶
目标检测模型¶
项目支持YOLOv8n模型（位于 src/ 目录）。
备注
所有模型文件已包含在项目中，位于 src/ 目录下，无需额外下载。
行人重识别模型¶
ReID模型：osnet_x0_25_market1501.onnx（位于 src/ 目录）
输入尺寸：256 × 128（宽×高）
特征维度：512维归一化特征向量
备注
ReID模型需要从Market1501等ReID数据集微调后的版本，不能直接使用ImageNet预训练模型。
统计逻辑说明¶
计数类型¶
实时计数（Current Count）：当前视频帧中检测到的活跃目标数量；
累计计数（Total Count）：基于唯一track_id的历史累计去重人数；
进出计数（In/Out Count）：基于虚拟检测线的人员进出方向统计。
计数原理¶
实时计数：直接统计当前帧中活跃跟踪目标的数量；
累计计数：每个新生成的track_id对应一个唯一人员标识，确保累计统计的准确性；
进出计数：通过虚拟检测线（默认为画面中央水平线）判断目标移动方向：
进入（In）：目标向下移动（Y坐标增大）
离开（Out）：目标向上移动（Y坐标减小）
基于目标中心点的历史轨迹判断穿越方向
每个track_id仅在首次穿越虚拟线时计数，避免重复统计
虚拟线自定义¶
当前版本支持自定义虚拟检测线的位置和方向：
水平检测线：direction=‘horizontal’，line_position=指定Y坐标
垂直检测线：direction=‘vertical’，line_position=指定X坐标
部署建议¶
摄像头安装位置¶
建议安装在通道正上方或侧方，镜头尽量覆盖整个目标经过区域，保证同一人进入或离开统计区域时在视野中持续可见。
推荐安装高度为2.2~3.5 m（若为天花板安装，镜头尽量垂直向下）；安装过低时，容易出现遮挡和人体下半身被截断。
需避开玻璃、反光幕墙、强逆光背景，避免镜头前出现大面积反光或被遮挡。
统计线附近不要放置大型柱子、货架或植物，避免目标短时间被挡住。
朝向与角度建议¶
优先采用“正前方略向下”的视角，建议俯仰角约15°~45°；过于平视会增加遮挡，过于俯冲则容易把人体压缩成小目标。
若采用侧装，尽量让人体移动方向与镜头光轴形成较小夹角，避免“侧身贴边”导致目标轮廓不完整。
统计线应尽量位于视野中部，且与摄像头画面保持较稳定的视角，避免频繁抖动或旋转。
光照条件建议¶
推荐均匀、柔和的前向照明；光照强度以可清晰识别人形、避免明显阴影为目标。
避免背光、强侧光和直射日光，需避免太阳光直接照进镜头，否则会影响检测和跟踪。
夜间使用时，建议增加补光灯或红外灯，并保持照明稳定，避免频闪和明显亮度波动。
当画面过暗、反差过大或出现大面积高光时，算法的漏检与误判概率会上升。
不同部署方式对算法效果的影响¶
USB摄像头：部署在设备本地，延迟低、画面稳定，通常更适合实时统计和现场调试。
IP摄像头：受网络带宽、编码格式、传输丢包和画面压缩影响较大；若分辨率过低、码率过低或帧率不稳定，检测和跟踪效果会下降。
本地视频文件：适合算法验证和离线测试，但与真实现场部署相比，视频文件的编码、帧率和播放方式可能会影响结果表现，不能完全等同于实时摄像头场景。
项目部署¶
网络摄像头配置¶
首次使用网络摄像头时，需先通过手机连接同一Wi-Fi网络，然后使用腾达App添加摄像头设备完成网络配置。
备注
确保Quectel Pi M2智能主控板与网络摄像头位于同一局域网，否则无法获取RTSP视频流。
获取项目代码¶
打开终端输入以下命令安装Git并克隆项目代码
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo-people-counting-device.git
设置目录权限
sudo chmod -R 755 ~/demo-people-counting-device
安装项目依赖
pip install --upgrade pip
cd demo-people-counting-device
pip install -r requirements.txt
摄像头参数配置（可选）¶
备注
网络摄像头的IP地址可通过腾达App的设备信息页面获取。
在智能主控板系统中打开Firefox浏览器，输入摄像头IP地址，使用默认凭据登录：
用户名：admin
密码：admin123456
登录后配置音视频参数并保存设置。
启动应用程序¶
进入项目源码目录并运行对应脚本：
cd demo-people-counting-device/src
#运行IP摄像头版本
python3 ip_camera_main.py
#或运行USB摄像头版本
python3 usb_camera_main.py
#或运行本地视频测试版本
python3 local_video_main.py --video ../assets/street.mp4
`--video`: 指定视频文件路径（必填）
`--model`: 指定YOLO模型路径（可选，默认使用 `yolov8n.pt`）
应用演示¶
常见问题排查¶
Q1：摄像头无法打开¶
解决方案：
将当前用户添加到video用户组：sudo usermod -aG video $USER；
重启系统使用户组权限生效；
检查摄像头是否被其他进程占用。
Q2：模型文件加载失败¶
解决方案：
确保在 src/ 目录下运行脚本（所有模型文件均位于此目录）；
请勿更改工作目录，直接在 src/ 目录执行启动命令。
Q3：IP摄像头连接失败¶
解决方案：
测试网络连通性：Ping <摄像头IP地址>；
确认摄像头ONVIF服务已启用。
Q4：系统性能卡顿¶
解决方案：
启动前关闭 ReID 功能：
export BYTETRACK_USE_REID=0（或BYTETRACK_USE_REID=0 python3 ...）；降低显示窗口分辨率。
技术支持与贡献¶
如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。
项目开源地址：https://github.com/Quectel-Pi/demo-people-counting-device
欢迎提交Issue反馈问题，或提交Pull Request改进代码。