# 人流量统计设备
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
本项目基于Quectel Pi M2智能主控板开发，是一套轻量级人流量统计解决方案，集成了目标检测、目标跟踪和行人重识别（ReID）等技术，具备以下核心功能：
- **实时人体检测**：在视频流中实时识别人体目标；
- **稳定目标跟踪**：采用ByteTrack算法实现高精度目标跟踪；
- **智能去重统计**：基于ReID特征进行人员身份去重；
- **多源视频支持**：兼容USB摄像头、IP摄像头及本地视频文件；
- **多维度统计**：提供实时人数、累计去重人数及进出方向统计。
```{image} images/image_NDSqbcbSzoeMHnxif51cm6ZynZd.webp
:width: 1070px
:height: 587px
```
# 开发资源汇总
## 开发配件清单
```{note}
以下配件清单仅供参考，实际开发环境可根据需求调整。例如，通过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个
| [树莓派5代官方原装主动散热器（含导热贴）]() |
| 网络摄像头 |
1个
| [腾达室内家用监控摄像头]() |
| USB摄像头模块 |
1个
| [绿联高清USB摄像头带麦克风(2K 400万高清自动对焦）]() |
| 显示屏 |
1个
| 24英寸HDMI显示器 |
## 配件实物参考
```{image} images/image_T6f4btiHDoe3mcxuPBeckeOln32.webp
:width: 984px
:height: 625px
:align: center
```
# 快速上手
## 开发准备
Quectel Pi M2智能主控板出厂预装 **Debian 13** 系统镜像，无需重新烧录系统，按照以下步骤即可开始开发。
## 硬件连接
按照以下步骤完成所有硬件连接，步骤编号与接口示意图中的标注一致：
```{image} images/image_NnumbqoYBoG6qMxpo06c5xtcnAc.webp
:width: 627px
:height: 463px
:align: center
```
1. **显示连接：** 将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。
2. **网络连接：** 确保路由器已接入互联网。将网线的一端连接到智能主控板的千兆以太网端口，另一端连接到路由器的以太网端口。
3. **输入设备连接：** 将USB键盘、鼠标和USB摄像头模块连接到智能主控板的USB接口；若使用无线输入设备，将无线接收器连接到智能主控板的USB接口即可。
4. **供电连接：** 将USB-A电源线的USB-A端连接到电源适配器的输出端，将USB-C端连接到智能主控板的电源输入接口（通常标注为 **POWER IN**）。
5. **网络摄像头连接：** 使用网络摄像头的自带电源线接通电源，并确保其与主控板处于同一局域网内。
## 模型准备
### 目标检测模型
项目支持YOLOv8n模型（位于 *src/* 目录）。
```{note}
所有模型文件已包含在项目中，位于 *src/* 目录下，无需额外下载。
```
### 行人重识别模型
- **ReID模型**：osnet_x0_25_market1501.onnx（位于 *src/* 目录）
- **输入尺寸**：256 × 128（宽×高）
- **特征维度**：512维归一化特征向量
```{note}
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摄像头：受网络带宽、编码格式、传输丢包和画面压缩影响较大；若分辨率过低、码率过低或帧率不稳定，检测和跟踪效果会下降。
- 本地视频文件：适合算法验证和离线测试，但与真实现场部署相比，视频文件的编码、帧率和播放方式可能会影响结果表现，不能完全等同于实时摄像头场景。
## 项目部署
### 网络摄像头配置
首次使用网络摄像头时，需先通过手机连接同一Wi-Fi网络，然后使用腾达App添加摄像头设备完成网络配置。
```{note}
确保Quectel Pi M2智能主控板与网络摄像头位于同一局域网，否则无法获取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
```
### 摄像头参数配置（可选）
```{note}
网络摄像头的IP地址可通过腾达App的设备信息页面获取。
```
在智能主控板系统中打开Firefox浏览器，输入摄像头IP地址，使用默认凭据登录：
- **用户名**：admin
- **密码**：admin123456
登录后配置音视频参数并保存设置。
```{image} images/image_CHGgbCGK1oV84nxSgf5cHsFLnxh.webp
:width: 939px
:height: 504px
```
```{image} images/image_KzD5bJ80vo9mTBx0LR4ckDfPn8f.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 ../assets/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 功能：`export BYTETRACK_USE_REID=0`（或 `BYTETRACK_USE_REID=0 python3 ...`）；
- 降低显示窗口分辨率。
# 技术支持与贡献
如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。
项目开源地址：[https://github.com/Quectel-Pi/demo-people-counting-device]()
欢迎提交Issue反馈问题，或提交Pull Request改进代码。