# FaceRecognition — 实时网络视频流人脸检测

基于 CNN 的人脸检测与特征提取应用：从 HTTP 网络视频流实时抓帧，经运动粗筛后检测人脸与关键点，完成对齐、SFace 特征提取和 IoU 跟踪。

- 作者：Liu zhenyu
- 语言标准：C++11
- 构建系统：CMake ≥ 3.10
- 人脸检测核心：[libfacedetection](https://github.com/ShiqiYu/libfacedetection)（BSD 3-Clause，原作者 Shiqi Yu）

---

## 目录结构

```
FaceRecognition/
├── CMakeLists.txt                  # 顶层 CMake：SIMD 选项 + 依赖查找 + 子模块
├── app/                            # 主可执行程序
│   ├── CMakeLists.txt
│   └── src/main.cpp                # 编排：收帧 -> 检测 -> 显示
├── libfacedetection/               # 人脸检测动态库 (SHARED)
│   ├── CMakeLists.txt
│   ├── include/
│   │   ├── facedetectcnn.h
│   │   └── facedetection_export.h
│   └── src/                        # CNN 模型与推理实现
├── network_camera_receiver/        # 网络抓帧静态库 (STATIC)
│   ├── CMakeLists.txt
│   ├── include/network_camera_receiver.h
│   └── src/network_camera_receiver.cpp
├── face_pipeline/                  # 运动检测、跟踪、对齐、特征与消息接口
├── models/                         # 固定版本 SFace ONNX、许可证与校验信息
├── tests/                          # CTest 离线单元/模型测试
└── resources/                      # 测试资源
```

### 主要模块

| 模块 | 类型 | 职责 |
|------|------|------|
| `libfacedetection` | SHARED 动态库 | CNN 人脸检测（含 5 个关键点），仅导出 `facedetect_cnn` |
| `network_camera_receiver` | STATIC 静态库 | 后台线程从 HTTP 视频流持续抓取最新帧，不包含检测逻辑 |
| `face_pipeline` | STATIC 静态库 | 运动粗筛、检测、IoU 跟踪、对齐、SFace 特征和结果接口 |
| `app` | 可执行程序 `face_detection_app` | 拉帧、提交任务并显示最新跟踪结果 |

---

## 功能特性

- **低延迟流水线**：采集与检测分线程，容量为 1 的 latest-wins mailbox 不积压旧帧。
- **运动粗筛**：有运动时触发检测；有人脸时每秒保活，无 track 时每 5 秒兜底扫描。
- **CNN 人脸检测**：输出人脸框 + 置信度 + 5 个面部关键点（双眼、鼻尖、嘴角）。
- **特征提取**：五点相似变换对齐后，由 OpenCV SFace 输出 L2 归一化的 128 维向量。
- **简单跟踪**：IoU 分配 `track_id`，每个 track 仅首次通过 `ResultSink` 发布。
- **SIMD 加速**：支持 AVX2 / AVX512 / NEON，CMake 选项一键开关并自动配置编译标志。
- **OpenMP 加速**：卷积运算可选多线程并行。
- **置信度过滤**：仅显示置信度 > 60 的人脸，降低误检。

---

## 依赖

- **OpenCV**（必需，视频采集与图像显示）
- **CMake ≥ 3.10**
- **C++11** 兼容编译器（GCC / Clang / MSVC）
- **OpenMP**（可选，加速检测）
- **Threads**（必需，后台抓帧线程）

Ubuntu / Debian 安装示例：

```bash
sudo apt-get install build-essential cmake libopencv-dev
# 可选 OpenMP 通常随 gcc 自带
```

---

## 构建

### 1. 默认构建（启用 AVX2）

```bash
cd FaceRecognition
cmake -S . -B build -DENABLE_AVX2=ON
cmake --build build -j
ctest --test-dir build --output-on-failure
```

生成的可执行文件：`build/app/face_detection_app`。配置阶段会校验 `models/face_recognition_sface_2021dec.onnx` 的 SHA-256。

### 2. SIMD 加速选项

`ENABLE_AVX2` / `ENABLE_AVX512` / `ENABLE_NEON` 三者**互斥**，最多开启一个。

| 选项 | 适用平台 | 默认 |
|------|----------|------|
| `ENABLE_AVX2` | X86/X64 CPU | ON |
| `ENABLE_AVX512` | 较新 X64 CPU | OFF |
| `ENABLE_NEON` | ARM CPU | OFF |

```bash
# AVX512（切换前先把默认的 AVX2 关掉）
cmake -S . -B build -DENABLE_AVX2=OFF -DENABLE_AVX512=ON

# ARM NEON
cmake -S . -B build -DENABLE_AVX2=OFF -DENABLE_NEON=ON
```

> ⚠️ 开启 CPU 不支持的指令集（如在不支持 AVX512 的机器上开 `ENABLE_AVX512`）能编译通过，但运行时会 `SIGILL` 崩溃。开启前先查询：
> ```bash
> grep -oE 'avx512[a-z]*|avx2|fma' /proc/cpuinfo | sort -u
> ```

### 3. 运行时依赖

`libfacedetection` 是动态库，运行时需能找到 `libfacedetection.so`。若未安装到系统路径，可：

```bash
export LD_LIBRARY_PATH=/home/hongshaorou/lzy_demo/FaceRecognition/build/libfacedetection:$LD_LIBRARY_PATH
```

---

## 使用方法

### 1. 准备视频流

程序默认连接 `http://127.0.0.1:5000/video`（HTTP MJPEG 流）。可使用任意能产出该接口的工具，例如 Python Flask + 摄像头：

```python
# send.py —— 简易 MJPEG 推流端（示例）
from flask import Flask, Response
import cv2

app = Flask(__name__)
cap = cv2.VideoCapture(0)  # 本机摄像头

def gen():
    while True:
        ok, frame = cap.read()
        if not ok: continue
        _, jpg = cv2.imencode('.jpg', frame)
        yield (b'--frame\r\n'
               b'Content-Type: image/jpeg\r\n\r\n' + jpg.tobytes() + b'\r\n')

@app.route('/video')
def video():
    return Response(gen(), mimetype='multipart/x-mixed-replace; boundary=frame')

app.run(host='0.0.0.0', port=5000)
```

推流端也可换成树莓派、IP 摄像头等任何能提供 `/video` MJPEG 接口的设备。

### 2. 修改目标 IP（可选）

如需连接远端主机，编辑 `app/src/main.cpp`：

```cpp
std::string host_ip = "127.0.0.1";  // 改为推流主机 IP
```

### 3. 运行

```bash
./build/app/face_detection_app
```

也可把兼容的 SFace 模型路径作为第一个参数传入。窗口显示人脸框、关键点和 `track_id`，按 **ESC** 退出。新 track 首次提取成功时输出一行 `face_feature` 日志，只记录元数据和特征维度，不打印完整向量。

---

## 检测结果解析

`facedetect_cnn` 返回的缓冲区布局（关键，写错会导致"只能检测一张脸"）：

- `buffer[0..3]`：人脸数量（`int`）
- `buffer[4..]` 起：每张人脸占 `FACEDETECTION_RESULT_STRIDE_SHORTS = 16` 个 `short`（32 字节）

每个人脸 16 个 short 字段：

| 索引 | 含义 |
|------|------|
| `p[0]` | 置信度（score × 100） |
| `p[1..4]` | 人脸框 x, y, w, h |
| `p[5..14]` | 5 个关键点（x, y 交替） |
| `p[15]` | 对齐填充 |

正确遍历写法（见 `app/src/main.cpp`）：

```cpp
short* p = ((short*)(pResults + 1)) + FACEDETECTION_RESULT_STRIDE_SHORTS * i;
```

> ⚠️ 经典版 libfacedetection（uint8 模型）每个结果占 142 字节，网上示例常写 `+ 142 * i`；在本重构版（float 模型）上会导致第 1 张起全部错位读到垃圾数据。务必使用 `FACEDETECTION_RESULT_STRIDE_SHORTS`。

---

## 项目架构流程

```
HTTP MJPEG → 抓帧线程 → 主线程运动粗筛 → latest-wins mailbox
                                      ↓
                         检测 worker：人脸检测 → IoU 跟踪
                                      ↓（仅未发布 track）
                              五点对齐 → SFace → ResultSink
```

---

## 常见问题

**Q: 编译报 `target specific option mismatch`？**
A: 开了 `_ENABLE_AVX*` 宏但没加对应 `-m` 编译标志。本项目已通过 CMake 选项自动同步两者，使用 `-DENABLE_AVX2=ON` 即可，不要手动改头文件宏。

**Q: 运行时 `SIGILL` 崩溃？**
A: 开了 CPU 不支持的指令集（如 AVX512）。用 `grep avx /proc/cpuinfo` 确认后重新 cmake。

**Q: 只能检测到一张脸？**
A: 结果 buffer stride 写错，必须用 `FACEDETECTION_RESULT_STRIDE_SHORTS`，不要用旧版的 142。

**Q: 连接视频流失败？**
A: 确认推流端已启动并监听对应端口；检查 `host_ip` 与端口是否正确；确认 `/video` 路由返回 `multipart/x-mixed-replace` 流。

---

## 许可证

- 本项目业务代码（`app/`、`network_camera_receiver/`）版权归 Liu zhenyu 所有。
- `libfacedetection` 遵循 BSD 3-Clause 许可证，版权归原作者 Shiqi Yu 所有，详见 `libfacedetection/include/facedetectcnn.h` 头部。