人流量统计设备¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
本项目是基于Quectel Pi H1智能主控板开发的轻量级人流量统计解决方案，集成了目标检测、目标跟踪和行人重识别（ReID）等技术，具备以下核心功能：
实时人体检测：在视频流中实时识别人体目标
稳定目标跟踪：采用ByteTrack算法实现高精度目标跟踪
智能去重统计：基于ReID特征进行人员身份去重
多源视频支持：兼容USB摄像头、IP摄像头及本地视频文件
多维度统计：提供实时人数、累计去重人数及进出方向统计
开发资源汇总¶
开发配件清单¶
说明：以下配件清单仅供参考，实际开发环境可根据需求调整。例如，通过SSH远程连接开发时可省略显示器和USB扩展坞, 摄像头根据实际需要选择即可。
配件名称 |
数量 |
规格参数 |
|---|---|---|
Quectel Pi H1智能主控板 |
1块 |
|
电源适配器 |
1个 |
|
HDMI线 |
1根 |
HDMI 2.0标准，线长1m，HDMI-A（公头）转HDMI-D（公头） |
网线 |
1根 |
千兆网线，线长1m |
CPU散热风扇（可选） |
1个 |
|
USB扩展坞(可选) |
1个 |
|
网络摄像头 |
1个 |
|
USB摄像头 |
1个 |
|
显示屏 |
1个 |
24英寸HDMI显示器 |
配件实物参考¶
快速上手¶
开发准备¶
Quectel Pi H1智能主控板出厂预装 Debian 13 系统镜像，无需重新烧录系统，按照以下步骤即可开始开发。
硬件连接¶
完成以下所有硬件连接操作：
显示连接：将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。
网络连接：将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。
输入设备连接：将USB键盘、鼠标、usb摄像头接入扩展坞的USB接口，再将扩展坞接入智能主控板的USB接口；若用无线输入设备，将接收器插入扩展坞的USB口即可。
供电连接：将USB-A电源线的USB-A端接入电源适配器，USB-C端接入智能主控板的电源口（通常标注 POWER IN）。
散热风扇连接：先将散热风扇的排线插入智能主控板的FAN插槽中，再将散热器两端固定在主控板预留插孔中。
网络摄像头连接: 使用网络摄像头的自带电源线接通电源，并确保其与主控板处于同一局域网内。
完整连接示意图¶
模型准备¶
目标检测模型¶
项目支持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摄像头：受网络带宽、编码格式、传输丢包和画面压缩影响较大；若分辨率过低、码率过低或帧率不稳定，检测和跟踪效果会下降。
本地视频文件：适合算法验证和离线测试，但与真实现场部署相比，视频文件的编码、帧率和播放方式可能会影响结果表现，不能完全等同于实时摄像头场景。
项目部署¶
网络摄像头配置¶
首次使用网络摄像头时，需先通过手机连接同一WiFi网络，然后使用腾达APP添加摄像头设备完成网络配置。
重要提示：确保Quectel Pi H1智能主控板与网络摄像头位于同一局域网，否则无法获取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 ../asset/street.mp4
`--video`: 指定视频文件路径（必填）
`--model`: 指定YOLO模型路径（可选，默认使用 `yolov8n.pt`）
应用演示¶
常见问题排查¶
Q1: 摄像头无法打开¶
解决方案：
将当前用户添加到video用户组：sudo usermod -aG video $USER
重启系统使用户组权限生效
检查摄像头是否被其他进程占用
Q2: 模型文件加载失败¶
解决方案：
确保在 src/ 目录下运行脚本（所有模型文件均位于此目录）
不要更改工作目录，直接在 src/ 目录执行启动命令
Q3: IP摄像头连接失败¶
解决方案：
测试网络连通性：ping <摄像头IP地址>
确认摄像头ONVIF服务已启用
Q4: 系统性能卡顿¶
解决方案：
关闭ReID功能（在代码中设置 use_reid=False）
降低显示窗口分辨率
技术支持与贡献¶
如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。
项目开源地址：https://github.com/Quectel-Pi/demo-people-counting-device
欢迎提交Issue反馈问题或Pull Request贡献代码改进！