# property and similiarity search #

使用VideoPipe做车辆检索（结构化属性过滤）。

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

### 主要文件 ###
1. `vehicle_encoding_classify_pipeline.cpp` 运行VideoPipe管道，读取视频文件，并提取车辆特征、对车辆进行颜色/车型分类，最后将特征、分类结果以Socket/UDP的方式发送给后台服务。
2. `property_encoding_receiver.py` 用于接收车辆特征、分类结果脚本，将其写入 `pandas.dataframe` 结构，然后以 `.csv` 的文件格式序列化到磁盘（每接收100个记录，会写入一次磁盘）。
3. `vehicle_search_server.py` 加载 `.csv` 文件中的特征、分类结果数据，并创建 `faiss` 索引对象。该脚本同时会提供一个基于 `flask` 的Web UI界面，用户可以上传图片和过滤条件，检索与之匹配的相似车辆。
4. `clean.sh` 帮助清空当前workspace下面的所有缓存数据。

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


### 如何使用 ###
1. CMake编译 `vehicle_encoding_classify_pipeline.cpp` 生成二进制可执行文件并运行, 它会提取车辆特征，并对其进行颜色/车型二级分类。(编译之前请先修改代码中 `des_ip` 的值)
2. 运行 `python3 property_encoding_receiver.py` 脚本接收车辆特征和分类结果，并**周期性**地存成 `.csv` 格式文件。(运行前，请先修改 `bind_ip` 的值)
3. 运行 `vehicle_search_server.py` 脚本，然后打开浏览器访问 `http://server-ip:9898` ，即可开始测试车辆检索、属性过滤的功能。

### 数据流向 ###
1. [pipeline -> embedding data and classification labels -> send via socket]
2. [receive embedding data and labels -> serialize to disk]
3. [deserialize from disk -> create Index Object of faiss -> search images from web]

```
please run `sh clean.sh` if you want to regenerate embeddings and classification labels, for example restart sample from scratch.
```

### VideoPipe管道介绍 ###

![](./vp_analysis_board.png)

1. `layer_1` 模拟获取车辆图片数据，实际可以换成file、application。
2. `layer_2` 完成车辆检测，从大图中定位车辆位置，创建 `vp_frame_target` 对象。
3. `layer_3` 完成车牌检测，基于前面检测到的车辆目标，抠图去检测车牌，创建 `vp_sub_target` 对象。注意这里是基于抠图再去检测车牌（与`车牌识别相机`实战有区别），属于`二级推理`。
4. `layer_4` 完成车辆颜色分类，基于前面检测到的车辆目标去做颜色分类，更新 `vp_frame_target` 的 `secondary_labels`/`secondary_class_ids`/`secondary_scores`。
5. `layer_5` 完成车辆车型分类，基于前面检测到的车辆目标去做车型分类，更新 `vp_frame_target` 的 `secondary_labels`/`secondary_class_ids`/`secondary_scores`。
6. `layer_6` 完成车辆特征编码，基于前面检测到的车辆目标去提取车辆特征，更新 `vp_frame_target` 的 `embeddings`。
7. `layer_7` 完成数据代理，将管道中的`车牌号码+车牌颜色`、`车辆颜色`、`车型`、`车辆特征`按自定义格式，以Socket/UDP的方式发送给Python后台服务。
8. `layer_8` 完成结果绘制，将检测、分类的结果绘制到帧上，方便调试查看。
9. `layer_9` 负责GUI输出显示，显示基本无延时。注意管道没有rtmp输出。


### 重要知识点 ###

1. `vp_sub_target` 类型。
2. `向量数据库（faiss）`和`业务数据库（pandas/mysql）`联合使用。
3. `向量检索`和`标量过滤`。

# 什么是 faiss #
FaceBook开源的一款`相似度检索`工具，可用于图片、文本相似性检索场景, 全名是`Facebook AI Similiarity Search`.

# 如何安装 faiss #
```
pip3 install faiss-cpu 
# pip3 install faiss-gpu
```

# Sample运行截图 #
**选择查询图片，和过滤条件**

![](../../doc/p46.png)

**车辆查询结果**

![](../../doc/p47.png)