introduction_cn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. PP-Vehicle简介\n",
    "PaddleDetection深入探索核心行业的高频场景，提供了车辆场景的开箱即用分析工具，支持图片/单镜头视频/多镜头视频/在线视频流多种输入方式，广泛应用于智慧交通、智慧城市、工业巡检等领域。支持服务器端部署及TensorRT加速，T4服务器上可达到实时！\n",
    "PP-Vehicle囊括四大交通场景核心功能：车牌识别、属性识别、车流量统计、违章检测。\n",
    "\n",
    "PP-Vehicle由飞桨官方出品，是基于PaddleDetection的车辆分析pipeline。\n",
    "更多关于PaddleDetection可以点击https://github.com/PaddlePaddle/PaddleDetection/tree/release/2.5/deploy/pipeline 进行了解。\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 模型效果及应用场景\n",
    "### 2.1 PP-Vehicle 模型效果：\n",
    "\n",
    "| 任务            | 端到端速度（ms）|  模型方案  |  模型体积 |\n",
    "| :---------:     | :-------:  |  :------: |:------: |\n",
    "|  车辆检测（高精度）  | 25.7ms  |  [多目标跟踪](https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_ppvehicle.zip) | 182M |  \n",
    "|  车辆检测（轻量级）  | 13.2ms  |  [多目标跟踪](https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_s_36e_ppvehicle.zip) | 27M |\n",
    "|  车辆跟踪（高精度）  | 40ms  |  [多目标跟踪](https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_ppvehicle.zip) | 182M |\n",
    "|  车辆跟踪（轻量级）  | 25ms  |  [多目标跟踪](https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_s_36e_ppvehicle.zip) | 27M |\n",
    "|  车牌识别  |   4.68ms |  [车牌检测](https://bj.bcebos.com/v1/paddledet/models/pipeline/ch_PP-OCRv3_det_infer.tar.gz) <br> [车牌字符识别](https://bj.bcebos.com/v1/paddledet/models/pipeline/ch_PP-OCRv3_rec_infer.tar.gz) | 车牌检测：3.9M  <br> 车牌字符识别： 12M |\n",
    "|  车辆属性  |   7.31ms | [车辆属性](https://bj.bcebos.com/v1/paddledet/models/pipeline/vehicle_attribute_model.zip) | 7.2M |\n",
    "\n",
    "\n",
    "### 2.2 应用场景：\n",
    "| 功能       | 方案优势                                                                                    | 示例图                                                                                                                                         |\n",
    "| ---------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |\n",
    "| **车牌识别**   | 支持传统车牌和新能源绿色车牌 <br/><br/> 车牌识别采用长间隔采样识别与多次结果统计投票方式，算力消耗少，识别精度高，结果稳定性好。 检测模型 hmean: 0.979; 识别模型 acc: 0.773          | <img title=\"\" src=\"https://user-images.githubusercontent.com/48054808/185027987-6144cafd-0286-4c32-8425-7ab9515d1ec3.png\" alt=\"\" width=\"191\"> |\n",
    "| **车辆属性分析** | 支持多种车型、颜色类别识别 <br/><br/> 使用更强力的Backbone模型PP-HGNet、PP-LCNet,精度高、速度快。识别精度: 90.81 | <img title=\"\" src=\"https://user-images.githubusercontent.com/48054808/185044490-00edd930-1885-4e79-b3d4-3a39a77dea93.gif\" alt=\"\" width=\"207\"> |\n",
    "| **违章检测**   | 简单易用：一行命令即可实现违停检测，自定义设置区域 <br/><br/> 检测、跟踪效果好，可实现违停车辆车牌识别    | <img title=\"\" src=\"https://user-images.githubusercontent.com/48054808/185028419-58ae0af8-a035-42e7-9583-25f5e4ce0169.png\" alt=\"\" width=\"209\"> |\n",
    "| **车流量计数**  | 简单易用：一行命令即可开启功能，自定义出入位置 <br/><br/> 可提供目标跟踪轨迹显示，统计准确度高        | <img title=\"\" src=\"https://user-images.githubusercontent.com/48054808/185028798-9e07379f-7486-4266-9d27-3aec943593e0.gif\" alt=\"\" width=\"200\"> |\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. 模型如何使用\n",
    "\n",
    "（在Jupyter Notebook上运行时需要加\"！\"，若是cd命令则需加\"%\"）"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": [
    "## 环境准备\n",
    "\n",
    "环境要求： PaddleDetection版本 >= release/2.5 或 develop版本\n",
    "\n",
    "PaddlePaddle和PaddleDetection安装\n",
    "\n",
    "```\n",
    "# PaddlePaddle CUDA10.1\n",
    "python -m pip install paddlepaddle-gpu==2.2.2.post101 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html\n",
    "\n",
    "# PaddlePaddle CPU\n",
    "python -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple\n",
    "\n",
    "# 克隆PaddleDetection仓库\n",
    "cd <path/to/clone/PaddleDetection>\n",
    "git clone https://github.com/PaddlePaddle/PaddleDetection.git\n",
    "\n",
    "# 安装其他依赖\n",
    "cd PaddleDetection\n",
    "pip install -r requirements.txt\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "### 3.1 配置文件说明\n",
    "\n",
    "PP-Vehicle相关配置位于```deploy/pipeline/config/infer_cfg_ppvehicle.yml```中，存放模型路径，完成不同功能需要设置不同的任务类型\n",
    "\n",
    "功能及任务类型对应表单如下：\n",
    "\n",
    "| 输入类型 | 功能 | 任务类型 | 配置项 |\n",
    "|-------|-------|----------|-----|\n",
    "| 图片 | 属性识别 | 目标检测 属性识别 | DET ATTR |\n",
    "| 单镜头视频 | 属性识别 | 多目标跟踪 属性识别 | MOT ATTR |\n",
    "| 单镜头视频 | 车牌识别 | 多目标跟踪 车牌识别 | MOT VEHICLEPLATE |\n",
    "\n",
    "\n",
    "例如基于视频输入的属性识别，任务类型包含多目标跟踪和属性识别，具体配置如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": [
    "\n",
    "```\n",
    "crop_thresh: 0.5\n",
    "visual: True\n",
    "warmup_frame: 50\n",
    "\n",
    "MOT:\n",
    "  model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_l_36e_ppvehicle.zip\n",
    "  tracker_config: deploy/pipeline/config/tracker_config.yml\n",
    "  batch_size: 1\n",
    "  enable: True\n",
    "\n",
    "VEHICLE_ATTR:\n",
    "  model_dir: https://bj.bcebos.com/v1/paddledet/models/pipeline/vehicle_attribute_model.zip\n",
    "  batch_size: 8\n",
    "  color_threshold: 0.5\n",
    "  type_threshold: 0.5\n",
    "  enable: True\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**注意：**\n",
    "\n",
    "- 如果用户需要实现不同任务，可以在配置文件对应enable选项设置为True。\n",
    "- 如果用户仅需要修改模型文件路径，可以在命令行中--config后面紧跟着 `-o MOT.model_dir=ppyoloe/` 进行修改即可，也可以手动修改配置文件中的相应模型路径，详细说明参考下方参数说明文档。\n",
    "\n",
    "### 3.2 预测部署"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": [
    "# 1. 直接使用默认配置或者examples中配置文件，或者直接在`infer_cfg_ppvehicle.yml`中修改配置：\n",
    "```\n",
    "# 例：车辆检测，指定配置文件路径和测试图片\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/infer_cfg_ppvehicle.yml --image_file=test_image.jpg --device=gpu\n",
    "\n",
    "# 例：车辆车牌识别，指定配置文件路径和测试视频\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/examples/infer_cfg_vehicle_plate.yml --video_file=test_video.mp4 --device=gpu\n",
    "```\n",
    "\n",
    "#2. 使用命令行进行功能开启，或者模型路径修改：\n",
    "```\n",
    "# 例：车辆跟踪，指定配置文件路径和测试视频，命令行中开启MOT模型并修改模型路径，命令行中指定的模型路径优先级高于配置文件\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/infer_cfg_ppvehicle.yml -o MOT.enable=True MOT.model_dir=ppyoloe_infer/ --video_file=test_video.mp4 --device=gpu\n",
    "\n",
    "# 例：车辆违章分析，指定配置文件和测试视频，命令行中指定违停区域设置、违停时间判断。\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/examples/infer_cfg_illegal_parking.yml \\\n",
    "                                                   --video_file=../car_test.mov \\\n",
    "                                                   --device=gpu \\\n",
    "                                                   --draw_center_traj \\\n",
    "                                                   --illegal_parking_time=3 \\\n",
    "                                                   --region_type=custom \\\n",
    "                                                   --region_polygon 600 300 1300 300 1300 800 600 800\n",
    "\n",
    "```\n",
    "\n",
    "#3. rtsp推拉流\n",
    "- rtsp拉流预测\n",
    "\n",
    "对rtsp拉流的支持，使用--rtsp RTSP [RTSP ...]参数指定一路或者多路rtsp视频流，如果是多路地址中间用空格隔开。(或者video_file后面的视频地址直接更换为rtsp流地址)，示例如下：\n",
    "```\n",
    "# 例：车辆属性识别，单路视频流\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/examples/infer_cfg_vehicle_attr.yml -o visual=False --rtsp rtsp://[YOUR_RTSP_SITE]  --device=gpu\n",
    "\n",
    "# 例：车辆属性识别，多路视频流\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/examples/infer_cfg_vehicle_attr.yml -o visual=False --rtsp rtsp://[YOUR_RTSP_SITE1]  rtsp://[YOUR_RTSP_SITE2] --device=gpu\n",
    "```\n",
    "\n",
    "#视频结果推流rtsp\n",
    "#预测结果进行rtsp推流，使用--pushurl rtsp:[IP] 推流到IP地址端，PC端可以使用[VLC播放器](https://vlc.onl/)打开网络流进行播放，播放地址为 `rtsp:[IP]/videoname`。其中`videoname`是预测的视频文件名，如果视频来源是本地摄像头则`videoname`默认为`output`.\n",
    "```\n",
    "# 例：车辆属性识别，单路视频流，该示例播放地址为 rtsp://[YOUR_SERVER_IP]:8554/test_video\n",
    "python deploy/pipeline/pipeline.py --config deploy/pipeline/config/examples/infer_cfg_vehicle_attr.yml -o visual=False --video_file=test_video.mp4  --device=gpu --pushurl rtsp://[YOUR_SERVER_IP]:8554\n",
    "```\n",
    "#注：\n",
    "#1. rtsp推流服务基于 [rtsp-simple-server](https://github.com/aler9/rtsp-simple-server), 如使用推流功能请先开启该服务.\n",
    "#2. rtsp推流如果模型处理速度跟不上会出现很明显的卡顿现象，建议跟踪模型使用ppyoloe_s版本，即修改配置中跟踪模型mot_ppyoloe_l_36e_pipeline.zip替换为mot_ppyoloe_s_36e_pipeline.zip。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### 3.3 Jetson部署说明\n",
    "\n",
    "由于Jetson平台算力相比服务器有较大差距，有如下使用建议：\n",
    "\n",
    "1. 模型选择轻量级版本，特别是跟踪模型，推荐使用`ppyoloe_s: https://bj.bcebos.com/v1/paddledet/models/pipeline/mot_ppyoloe_s_36e_pipeline.zip`\n",
    "2. 开启跟踪跳帧功能，推荐使用2或者3: `skip_frame_num: 3`\n",
    "\n",
    "使用该推荐配置，在TX2平台上可以达到较高速率，经测试属性案例达到20fps。\n",
    "\n",
    "可以直接修改配置文件（推荐），也可以在命令行中修改（字段较长，不推荐）。\n",
    "\n",
    "### 参数说明\n",
    "\n",
    "| 参数 | 是否必须|含义 |\n",
    "|-------|-------|----------|\n",
    "| --config | Yes | 配置文件路径 |\n",
    "| -o | Option | 覆盖配置文件中对应的配置  |\n",
    "| --image_file | Option | 需要预测的图片 |\n",
    "| --image_dir  | Option |  要预测的图片文件夹路径   |\n",
    "| --video_file | Option | 需要预测的视频，或者rtsp流地址（推荐使用rtsp参数） |\n",
    "| --rtsp | Option | rtsp视频流地址，支持一路或者多路同时输入 |\n",
    "| --camera_id | Option | 用来预测的摄像头ID，默认为-1(表示不使用摄像头预测，可设置为：0 - (摄像头数目-1) )，预测过程中在可视化界面按`q`退出输出预测结果到：output/output.mp4|\n",
    "| --device | Option | 运行时的设备，可选择`CPU/GPU/XPU`，默认为`CPU`|\n",
    "| --pushurl | Option| 对预测结果视频进行推流的地址，以rtsp://开头，该选项优先级高于视频结果本地存储，打开时不再另外存储本地预测结果视频|\n",
    "| --output_dir | Option|可视化结果保存的根目录，默认为output/|\n",
    "| --run_mode | Option |使用GPU时，默认为paddle, 可选（paddle/trt_fp32/trt_fp16/trt_int8）|\n",
    "| --enable_mkldnn | Option | CPU预测中是否开启MKLDNN加速，默认为False |\n",
    "| --cpu_threads | Option| 设置cpu线程数，默认为1 |\n",
    "| --trt_calib_mode | Option| TensorRT是否使用校准功能，默认为False。使用TensorRT的int8功能时，需设置为True，使用PaddleSlim量化后的模型时需要设置为False |\n",
    "| --do_entrance_counting | Option | 是否统计出入口流量，默认为False |\n",
    "| --draw_center_traj | Option | 是否绘制跟踪轨迹，默认为False |\n",
    "| --region_type | Option | 'horizontal'（默认值）、'vertical'：表示流量统计方向选择；'custom'：表示设置闯入区域 |\n",
    "| --region_polygon | Option | 设置闯入区域多边形多点的坐标，无默认值 |\n",
    "| --do_break_in_counting | Option | 此项表示做区域闯入检查 |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. 方案介绍\n",
    "PP-Vehicle 整体方案如下图所示:\n",
    "\n",
    "<div width=\"1000\" align=\"center\">\n",
    "  <img src=\"ppvehicle.png\"/>\n",
    "</div>\n",
    "\n",
    "\n",
    "### 车辆检测\n",
    "- 采用PP-YOLOE L 作为目标检测模型\n",
    "- 详细文档参考[PP-YOLOE](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/configs/ppyoloe)和[检测跟踪文档](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/pipeline/docs/tutorials/ppvehicle_mot.md)\n",
    "\n",
    "### 车辆跟踪\n",
    "- 采用SDE方案完成车辆跟踪\n",
    "- 检测模型使用PP-YOLOE L(高精度)和S(轻量级)\n",
    "- 跟踪模块采用OC-SORT方案\n",
    "- 详细文档参考[OC-SORT](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/configs/mot/ocsort)和[检测跟踪文档](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/pipeline/docs/tutorials/ppvehicle_mot.md)\n",
    "\n",
    "### 属性识别\n",
    "- 使用PaddleClas提供的特色模型PP-LCNet，实现对车辆颜色及车型属性的识别。\n",
    "- 详细文档参考[属性识别](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/pipeline/docs/tutorials/ppvehicle_attribute.md)\n",
    "\n",
    "### 车牌识别\n",
    "- 使用PaddleOCR特色模型ch_PP-OCRv3_det+ch_PP-OCRv3_rec模型，识别车牌号码\n",
    "- 详细文档参考[车牌识别](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/pipeline/docs/tutorials/ppvehicle_plate.md)\n",
    "\n",
    "### 违章停车识别\n",
    "- 车辆跟踪模型使用高精度模型PP-YOLOE L，根据车辆的跟踪轨迹以及指定的违停区域判断是否违章停车，如果存在则展示违章停车车牌号。\n",
    "- 详细文档参考[违章停车识别](https://github.com/PaddlePaddle/PaddleDetection/blob/release/2.5/deploy/pipeline/docs/tutorials/ppvehicle_illegal_parking.md)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}