# 人流量统计设备
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
本项目是基于Quectel Pi H1智能主控板开发的轻量级人流量统计解决方案，集成了目标检测、目标跟踪和行人重识别（ReID）等技术，具备以下核心功能：
- **实时人体检测**：在视频流中实时识别人体目标
- **稳定目标跟踪**：采用ByteTrack算法实现高精度目标跟踪
- **智能去重统计**：基于ReID特征进行人员身份去重
- **多源视频支持**：兼容USB摄像头、IP摄像头及本地视频文件
- **多维度统计**：提供实时人数、累计去重人数及进出方向统计
```{image} images/image_TZmeboCAyo31idxVhEBcOEwcn7f.webp
:width: 1070px
:height: 587px
```
# 开发资源汇总
## 开发配件清单
> **说明**：以下配件清单仅供参考，实际开发环境可根据需求调整。例如，通过SSH远程连接开发时可省略显示器和USB扩展坞, 摄像头根据实际需要选择即可。
|
配件名称
|
数量
|
规格参数
|
| --- | --- | --- |
| Quectel Pi H1智能主控板 |
1块
| [Quectel Pi H1智能主控板]() |
| 电源适配器 |
1个
| [27W USB Type-C接口充电器，1.2米线长，PD快充，适用于树莓派5代]() |
| HDMI线 |
1根
| HDMI 2.0标准，线长1m，HDMI-A（公头）转HDMI-D（公头） |
| 网线 |
1根
| 千兆网线，线长1m |
| CPU散热风扇（可选） |
1个
| [树莓派5代官方原装主动散热器（含导热贴）]() |
| USB扩展坞(可选) |
1个
| [绿联USB 3.0多功能扩展坞]() |
| 网络摄像头 |
1个
| [Tenda腾达室内家用监控摄像头]() |
| USB摄像头 |
1个
| [OV5693 USB摄像头模块]() |
| 显示屏 |
1个
| 24英寸HDMI显示器 |
## 配件实物参考
```{image} images/image_NRLubIKkroYGJTxksRYcXkN0nEf.webp
:width: 1113px
:height: 707px
```
# 快速上手
## 开发准备
Quectel Pi H1智能主控板出厂预装 **Debian 13** 系统镜像，无需重新烧录系统，按照以下步骤即可开始开发。
## 硬件连接
完成以下所有硬件连接操作：
```{image} images/image_URI3bSgDKopfUAxHrvYcrBNjnmg.webp
:width: 1022px
:height: 587px
```
1. **显示连接**：将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。
2. **网络连接**：将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。
3. **输入设备连接**：将USB键盘、鼠标、usb摄像头接入扩展坞的USB接口，再将扩展坞接入智能主控板的USB接口；若用无线输入设备，将接收器插入扩展坞的USB口即可。
4. **供电连接**：将USB-A电源线的USB-A端接入电源适配器，USB-C端接入智能主控板的电源口（通常标注 **POWER IN**）。
5. **散热风扇连接**：先将散热风扇的排线插入智能主控板的FAN插槽中，再将散热器两端固定在主控板预留插孔中。
6. **网络摄像头连接:** 使用网络摄像头的自带电源线接通电源，并确保其与主控板处于同一局域网内。
### 完整连接示意图
```{image} images/image_OlJxbOzwMoCqJixe9g2cFqAinbd.webp
:width: 1000px
:height: 484px
```
## 模型准备
### 目标检测模型
项目支持YOLOv8n模型（位于 *src/* 目录）：
> **注意**：所有模型文件已包含在项目中，位于 *src/* 目录下，无需额外下载。
### 行人重识别模型
- **ReID模型**：*osnet_x0_25_market1501.onnx*（位于 *src/* 目录）
- **输入尺寸**：256×128（宽×高）
- **特征维度**：512维归一化特征向量
> **注意**：ReID模型需要从Market1501等ReID数据集微调后的版本，不能直接使用ImageNet预训练模型。
## 统计逻辑说明
### 计数类型
1. **实时计数（Current Count）**：当前视频帧中检测到的活跃目标数量
2. **累计计数（Total Count）**：基于唯一track_id的历史累计去重人数
3. **进出计数（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视频流。
### 获取项目代码
1. 打开终端输入以下命令安装Git并克隆项目代码：
```shell
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo-people-counting-device.git
```
2. 设置目录权限：
```shell
sudo chmod -R 755 ~/demo-people-counting-device
```
3. 安装项目依赖
```shell
pip install --upgrade pip
cd demo-people-counting-device
pip install -r requirements.txt
```
### 摄像头参数配置（可选）
> 网络摄像头的IP地址可通过腾达APP的设备信息页面获取。
在主控板系统中打开Firefox浏览器，输入摄像头IP地址，使用默认凭据登录：
- **用户名**：*admin*
- **密码**：*admin123456*
登录后配置音视频参数并保存设置。
```{image} images/image_IVVIbJs68omy9LxBKJScf2cJnge.webp
:width: 939px
:height: 504px
```
```{image} images/image_CH2YbnpYDoYVdhx9U66c07i4n43.webp
:width: 1119px
:height: 561px
```
### 启动应用程序
进入项目源码目录并运行对应脚本：
```shell
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`）
```
# 应用演示
people-counting-device
# 常见问题排查
## 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贡献代码改进！