mirrors
/
mmyolo
mirror of https://github.com/open-mmlab/mmyolo.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[DOC] Add en `useful_tools` (#52) 

* [Doc] Fix docker doc

* [Doc] Fix doc

* [Doc] Add en `usefule_tools.md`
pull/41/head^2
HinGwenWoong 2022-09-21 15:45:26 +08:00 committed by GitHub
parent 7b7c807eb5
commit 45f61c38f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 214 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/get_started.md
View File

@ -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
```

6
docs/en/overview.md
View File

@ -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)
<div align=center>
<img src="https://user-images.githubusercontent.com/12907710/137271636-56ba1cd2-b110-4812-8221-b4c120320aa9.png" alt="image">
</div>
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:

184
docs/en/user_guides/useful_tools.md
View File

@ -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.

2
docs/zh_cn/get_started.md
View File

@ -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
```

37
docs/zh_cn/user_guides/useful_tools.md
View File

@ -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