# face recognize #

使用VideoPipe做人脸识别。

### 提前准备 ###
1. 已准备好 `VideoPipe` 编译/运行环境（参见视频教程）
2. 已准备好本案例所需的测试模型和测试数据（即 `vp_data`，具体参见视频教程）
3. 已安装好本案例中 `Python3` 所需的依赖库（主要是`numpy`,`pandas`,`opencv`,`flask`,`faiss`等，其余按需安装即可）

### 主要文件 ###
1. `face_recognize_pipeline.cpp` 运行VideoPipe管道读取人脸视频，提取人脸特征，并将特征通过Socket/UDP发送给人脸识别后台服务。
2. `face_recognize_server.py` 后台服务接收人脸特征数据，并基于 `faiss` 框架完成人脸识别任务，将识别结果存入数据库，并提供一个基于 `flask` 的Web UI界面供数据查询。
3. `clean.sh` 帮助清空当前workspace下面的所有缓存数据。

![](./docs/1.png)

### 如何使用 ###
1. CMake编译 `face_recognize_pipeline.cpp` 生成二进制可执行程序并运行，它会实时提取人脸特征。(编译之前请先修改代码中 `des_ip` 和 `rtmp推流地址`)
2. 运行 `python3 face_recognize_server.py` 脚本，完成人脸识别任务, 然后打开浏览器访问 `http://server-ip:5656` 查看识别记录。 (运行前，先修改脚本中 `bind_ip` 和 `live_stream_0` 的值)


### 数据流向 ###
1. [load registered users -> create faiss Index]
2. [pipeline -> face embeddings -> send via socket]
3. [receive face embeddings -> recognize -> display results from web]

```
please run `sh clean.sh` if you want to restart sample from scratch.
```

### VideoPipe管道介绍 ###
![](./vp_analysis_board.png)

1. `layer_1` 模拟获取人脸视频数据，实际可以换成rtsp/udp/或者直接从摄像机Sensor抓图。
2. `layer_2` 完成人脸检测，从大图中定位人脸位置及其5个关键点，创建 `vp_frame_face_target` 对象。
3. `layer_3` 完成人脸特征提取，基于前面检测到的人脸，提取特征，更新 `vp_frame_face_target` 的 `embeddings`。
4. `layer_4` 完成人脸跟踪(SORT)，更新 `vp_frame_face_target` 的 `track_id` 和 `tracks`, 避免`重复提交`的问题。
5. `layer_5` 完成人脸数据转发，将管道中的`人脸特征（embeddings）`、`人脸抠图路径`按自定义格式，使用Socket/UDP的方式发送给后台Python服务。
6. `layer_6` 完成结果绘制，主要将当前画面中检测到的人脸（`vp_frame_face_target`）显示出来。
7. `layer_7`
    - `screen_des_0` 负责GUI输出显示，显示基本无延时。
    - `rtmp_des_0` 负责rtmp编码推流，Web UI通过rtmp地址可以实时播放，有若干秒延时。

### 重要知识点 ###
1. `vp_analysis_board` 类型，管道可视化原理。
2. `VideoPipe` 管道`自动拆分`的原理。
3. `vp_rtmp_des_node` 工作的原理。
4. `vp_frame_face_target` 类型。
5. `faiss` 相似度检索库的使用。
6. 如何避免人脸数据重复提交？
7. 如何减少人脸特征提取的次数，提高管道运行性能？

# Sample运行截图 #
![](../../doc/p51.png)