From 45f61c38f041271aac27d3105ee041cc95b3e4f9 Mon Sep 17 00:00:00 2001 From: HinGwenWoong Date: Wed, 21 Sep 2022 15:45:26 +0800 Subject: [PATCH] [DOC] Add en `useful_tools` (#52) * [Doc] Fix docker doc * [Doc] Fix doc * [Doc] Add en `usefule_tools.md` --- docs/en/get_started.md | 2 +- docs/en/overview.md | 6 +- docs/en/user_guides/useful_tools.md | 184 +++++++++++++++++++++++++ docs/zh_cn/get_started.md | 2 +- docs/zh_cn/user_guides/useful_tools.md | 37 +++-- 5 files changed, 214 insertions(+), 17 deletions(-) diff --git a/docs/en/get_started.md b/docs/en/get_started.md index e2ac7bdc..20000894 100644 --- a/docs/en/get_started.md +++ b/docs/en/get_started.md @@ -223,7 +223,7 @@ docker build -t mmyolo docker/ Run it with ```shell -DATA_DIR=/path/to/your/dataset +export DATA_DIR=/path/to/your/dataset docker run --gpus all --shm-size=8g -it -v ${DATA_DIR}:/mmyolo/data mmyolo ``` diff --git a/docs/en/overview.md b/docs/en/overview.md index 8c427b76..69e81c0e 100644 --- a/docs/en/overview.md +++ b/docs/en/overview.md @@ -4,7 +4,9 @@ This chapter introduces you to the overall framework of MMYOLO and provides link ## What is MMYOLO -![pic](https://user-images.githubusercontent.com/12907710/137271636-56ba1cd2-b110-4812-8221-b4c120320aa9.png) +
+image +
MMYOLO is a YOLO series algorithm toolbox, which currently implements only the target detection task and will subsequently support various tasks such as instance segmentation, panoramic segmentation and key point detection. It includes a rich set of target detection algorithms and related components and modules, and the following is its overall framework. @@ -29,7 +31,7 @@ MMYOLO file structure is identical to the MMDetection. To allow full reuse of th The detailed instruction of MMYOLO is as following -1. Look up install instruction through [start your first step](get_started.md) +1. Look up install instruction through [start your first step](get_started.md). 2. Basic method of how to use MMYOLO can be found here: diff --git a/docs/en/user_guides/useful_tools.md b/docs/en/user_guides/useful_tools.md index ac2f92f6..9cf8d80a 100644 --- a/docs/en/user_guides/useful_tools.md +++ b/docs/en/user_guides/useful_tools.md @@ -1 +1,185 @@ # Useful tools + +We provide lots of useful tools under the `tools/` directory. In addition, you can also quickly run other open source libraries of OpenMMLab through MIM. + +Take MMDetection as an example. If you want to use [print_config.py](https://github.com/open-mmlab/mmdetection/blob/3.x/tools/misc/print_config.py), you can directly use the following commands without copying the source code to the MMYOLO library. + +```shell +mim run mmdet print_config [CONFIG] +``` + +**Note**: The MMDetection library must be installed through the MIM before the above command can succeed. + +## Visualization + +### Visualize COCO labels + +`tools/analysis_tools/browse_coco_json.py` is a script that can visualization to display the COCO label in the picture. + +```shell +python tools/analysis_tools/browse_coco_json.py ${DATA_ROOT} \ + [--ann_file ${ANN_FILE}] \ + [--img_dir ${IMG_DIR}] \ + [--wait-time ${WAIT_TIME}] \ + [--disp-all] [--category-names CATEGORY_NAMES [CATEGORY_NAMES ...]] \ + [--shuffle] +``` + +E.g: + +1. Visualize all categories of `COCO` and display all types of annotations such as `bbox` and `mask`: + +```shell +python tools/analysis_tools/browse_coco_json.py './data/coco/' \ + --ann_file 'annotations/instances_train2017.json' \ + --img_dir 'train2017' \ + --disp-all +``` + +2. Visualize all categories of `COCO`, and display only the `bbox` type labels, and shuffle the image to show: + +```shell +python tools/analysis_tools/browse_coco_json.py './data/coco/' \ + --ann_file 'annotations/instances_train2017.json' \ + --img_dir 'train2017' \ + --shuffle +``` + +3. Only visualize the `bicycle` and `person` categories of `COCO` and only the `bbox` type labels are displayed: + +```shell +python tools/analysis_tools/browse_coco_json.py './data/coco/' \ + --ann_file 'annotations/instances_train2017.json' \ + --img_dir 'train2017' \ + --category-names 'bicycle' 'person' +``` + +4. Visualize all categories of `COCO`, and display all types of label such as `bbox`, `mask`, and shuffle the image to show: + +```shell +python tools/analysis_tools/browse_coco_json.py './data/coco/' \ + --ann_file 'annotations/instances_train2017.json' \ + --img_dir 'train2017' \ + --disp-all \ + --shuffle +``` + +### Visualize Datasets + +`tools/analysis_tools/browse_dataset.py` helps the user to browse a detection dataset (both images and bounding box annotations) visually, or save the image to a designated directory. + +```shell +python tools/analysis_tools/browse_dataset.py ${CONFIG} \ + [-h] \ + [--output-dir ${OUTPUT_DIR}] \ + [--not-show] \ + [--show-interval ${SHOW_INTERVAL}] +``` + +E,g： + +1. Use `config` file `configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py` to visualize the picture. The picture will pop up directly and be saved to the directory `work dir/browse_ dataset` at the same time: + +```shell +python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py' \ + --output-dir 'work-dir/browse_dataset' +``` + +2. Use `config` file `configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py` to visualize the picture. The picture will pop up and display directly. Each picture lasts for `10` seconds. At the same time, it will be saved to the directory `work dir/browse_ dataset`: + +```shell +python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py' \ + --output-dir 'work-dir/browse_dataset' \ + --show-interval 10 +``` + +3. Use `config` file `configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py` to visualize the picture. The picture will pop up and display directly. Each picture lasts for `10` seconds and the picture will not be saved: + +```shell +python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py' \ + --show-interval 10 +``` + +4. Use `config` file `configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py` to visualize the picture. The picture will not pop up directly, but only saved to the directory `work dir/browse_ dataset`: + +```shell +python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncbn_8xb16-300e_coco.py' \ + --output-dir 'work-dir/browse_dataset' \ + --not-show +``` + +## Dataset Conversion + +the `tools/` directory also contains script to convert the `balloon` dataset (A small dataset is only for beginner use) into COCO format. + +For a detailed description of this script, please refer to the "Dataset Preparation" section in [From getting started to deployment with YOLOv5](./yolov5_tutorial.md). + +```shell +python tools/dataset_converters/balloon2coco.py +``` + +## Dataset Download + +`tools/misc/download_dataset.py` supports downloading datasets such as `COCO`, `VOC`, `LVIS` and `Balloon`. + +```shell +python tools/misc/download_dataset.py --dataset-name coco2017 +python tools/misc/download_dataset.py --dataset-name voc2007 +python tools/misc/download_dataset.py --dataset-name lvis +python tools/misc/download_dataset.py --dataset-name balloon [--save-dir ${SAVE_DIR}] [--unzip] +``` + +## Model Conversion + +The three scripts under the `tools/` directory can help users convert the keys in the official pre-trained model of YOLO to the format of MMYOLO, and use MMYOLO to fine tune the model. + +### YOLOv5 + +Take conversion `yolov5s.pt` as an example: + +1. Clone the official YOLOv5 code to the local (currently the maximum supported version is `v6.1`): + +```shell +git clone -b v6.1 https://github.com/ultralytics/yolov5.git +cd yolov5 +``` + +2. Download official weight file: + +```shell +wget https://github.com/ultralytics/yolov5/releases/download/v6.1/yolov5s.pt +``` + +3. Copy file `tools/model_converters/yolov5_to_mmyolo.py` to the path of YOLOv5 official code clone: + +```shell +cp ${MMDET_YOLO_PATH}/tools/model_converters/yolov5_to_mmyolo.py yolov5_to_mmyolo.py +``` + +4. Conversion + +```shell +python yolov5_to_mmyolo.py --src ${WEIGHT_FILE_PATH} --dst mmyolov5.pt +``` + +The converted `mmyolov5.pt` can be used by MMYOLO. The official weight conversion of YOLOv6 is also used in the same way. + +### YOLOX + +The conversion of YOLOX model **does not need** to download the official YOLOX code, just download the weight. + +Take conversion `yolox_s.pth` as an example: + +1. Download official weight file: + +```shell +wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.pth +``` + +2. Conversion + +```shell +python tools/model_converters/yolox_to_mmyolo.py --src yolox_s.pth --dst mmyolox.pt +``` + +The converted `mmyolox.pt` can be used by MMYOLO. diff --git a/docs/zh_cn/get_started.md b/docs/zh_cn/get_started.md index 3ef5785c..27d89d07 100644 --- a/docs/zh_cn/get_started.md +++ b/docs/zh_cn/get_started.md @@ -228,7 +228,7 @@ docker build -t mmyolo docker/ 用以下命令运行 Docker 镜像： ```shell -DATA_DIR=/path/to/your/dataset +export DATA_DIR=/path/to/your/dataset docker run --gpus all --shm-size=8g -it -v ${DATA_DIR}:/mmyolo/data mmyolo ``` diff --git a/docs/zh_cn/user_guides/useful_tools.md b/docs/zh_cn/user_guides/useful_tools.md index 067af65d..f802239f 100644 --- a/docs/zh_cn/user_guides/useful_tools.md +++ b/docs/zh_cn/user_guides/useful_tools.md @@ -1,12 +1,14 @@ # 实用工具 -我们在 `tools/` 文件夹下提供很多实用工具。 除此之外，你也可以通过 MIM 来快速运行 OpenMMLab 的其他开源库。以 MMDetection 为例，如果想利用 [print_config.py](https://github.com/open-mmlab/mmdetection/blob/3.x/tools/misc/print_config.py)，你可以直接采用如下命令，而无需复制源码到 MMYOLO 库中。 +我们在 `tools/` 文件夹下提供很多实用工具。 除此之外，你也可以通过 MIM 来快速运行 OpenMMLab 的其他开源库。 + +以 MMDetection 为例，如果想利用 [print_config.py](https://github.com/open-mmlab/mmdetection/blob/3.x/tools/misc/print_config.py)，你可以直接采用如下命令，而无需复制源码到 MMYOLO 库中。 ```shell mim run mmdet print_config [CONFIG] ``` -需要特别注意的是：上述命令能够成功的前提是 MMDetection 库必须通过 MIM 来安装。 +**注意**：上述命令能够成功的前提是 MMDetection 库必须通过 MIM 来安装。 ## 可视化 @@ -15,12 +17,17 @@ mim run mmdet print_config [CONFIG] 脚本 `tools/analysis_tools/browse_coco_json.py` 能够使用可视化显示 COCO 标签在图片的情况 ```shell -python tools/analysis_tools/browse_coco_json.py ${DATA_ROOT} [--ann_file ${ANN_FILE}] [--img_dir ${IMG_DIR}] [--wait-time ${WAIT_TIME}] [--disp-all] [--category-names CATEGORY_NAMES [CATEGORY_NAMES ...]] [--shuffle] +python tools/analysis_tools/browse_coco_json.py ${DATA_ROOT} \ + [--ann_file ${ANN_FILE}] \ + [--img_dir ${IMG_DIR}] \ + [--wait-time ${WAIT_TIME}] \ + [--disp-all] [--category-names CATEGORY_NAMES [CATEGORY_NAMES ...]] \ + [--shuffle] ``` 例子： -1. 查看 `COCO` 全部类别，同时展示 `bbox`、`mask` 等所有类型的标注 +1. 查看 `COCO` 全部类别，同时展示 `bbox`、`mask` 等所有类型的标注： ```shell python tools/analysis_tools/browse_coco_json.py './data/coco/' \ @@ -29,7 +36,7 @@ python tools/analysis_tools/browse_coco_json.py './data/coco/' \ --disp-all ``` -2. 查看 `COCO` 全部类别，同时仅展示 `bbox` 类型的标注，并打乱显示 +2. 查看 `COCO` 全部类别，同时仅展示 `bbox` 类型的标注，并打乱显示： ```shell python tools/analysis_tools/browse_coco_json.py './data/coco/' \ @@ -38,7 +45,7 @@ python tools/analysis_tools/browse_coco_json.py './data/coco/' \ --shuffle ``` -3. 只查看 `bicycle` 和 `person` 类别，同时仅展示 `bbox` 类型的标注 +3. 只查看 `bicycle` 和 `person` 类别，同时仅展示 `bbox` 类型的标注： ```shell python tools/analysis_tools/browse_coco_json.py './data/coco/' \ @@ -47,7 +54,7 @@ python tools/analysis_tools/browse_coco_json.py './data/coco/' \ --category-names 'bicycle' 'person' ``` -4. 查看 `COCO` 全部类别，同时展示 `bbox`、`mask` 等所有类型的标注，并打乱显示 +4. 查看 `COCO` 全部类别，同时展示 `bbox`、`mask` 等所有类型的标注，并打乱显示： ```shell python tools/analysis_tools/browse_coco_json.py './data/coco/' \ @@ -62,7 +69,11 @@ python tools/analysis_tools/browse_coco_json.py './data/coco/' \ 脚本 `tools/analysis_tools/browse_dataset.py` 能够帮助用户去直接窗口可视化数据集的原始图片+展示标签的图片，或者保存可视化图片到指定文件夹内。 ```shell -python tools/analysis_tools/browse_dataset.py ${CONFIG} [-h] [--output-dir ${OUTPUT_DIR}] [--not-show] [--show-interval ${SHOW_INTERVAL}] +python tools/analysis_tools/browse_dataset.py ${CONFIG} \ + [-h] \ + [--output-dir ${OUTPUT_DIR}] \ + [--not-show] \ + [--show-interval ${SHOW_INTERVAL}] ``` 例子： @@ -126,26 +137,26 @@ python tools/misc/download_dataset.py --dataset-name balloon [--save-dir ${SAVE_ 下面以转换 `yolov5s.pt` 为例： -1. 将 YOLOv5 官方代码克隆到本地（目前支持的最高版本为 `v6.1` ） +1. 将 YOLOv5 官方代码克隆到本地（目前支持的最高版本为 `v6.1` ）： ```shell git clone -b v6.1 https://github.com/ultralytics/yolov5.git cd yolov5 ``` -2. 下载官方权重 +2. 下载官方权重： ```shell wget https://github.com/ultralytics/yolov5/releases/download/v6.1/yolov5s.pt ``` -3. 将 `tools/model_converters/yolov5_to_mmyolo.py` 文件复制到 YOLOv5 官方代码克隆的路径 +3. 将 `tools/model_converters/yolov5_to_mmyolo.py` 文件复制到 YOLOv5 官方代码克隆的路径： ```shell cp ${MMDET_YOLO_PATH}/tools/model_converters/yolov5_to_mmyolo.py yolov5_to_mmyolo.py ``` -4. 执行转换 +4. 执行转换： ```shell python yolov5_to_mmyolo.py --src ${WEIGHT_FILE_PATH} --dst mmyolov5.pt @@ -163,7 +174,7 @@ YOLOX 模型的转换不需要下载 YOLOX 官方代码，只需要下载权重 wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.1rc0/yolox_s.pth ``` -2. 执行转换 +2. 执行转换： ```shell python tools/model_converters/yolox_to_mmyolo.py --src yolox_s.pth --dst mmyolox.pt