[Feature] Add script converts yolo-style to coco format (open-mmlab#161)

* the script converts yolo-style to coco format draft 1

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* typo fixed and update

* encaped and modified yolo2coco

* more usage instructions of yolo2coco

* Update docs/zh_cn/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update docs/zh_cn/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update docs/zh_cn/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* final draft of yolo2coco

* final draft of yolo2coco

* final draft of yolo2coco

* revise the script and remove -split indicator

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* update the structural example of the root path

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* fix typo on check_existence

* Update docs/zh_cn/user_guides/useful_tools.md

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>

* update the commits

* rewrite split_by_files part and add copy_image part

* add instruction on using absolute image paths

* add instruction on using absolute image paths

* Update docs/en/user_guides/useful_tools.md

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Range King <RangeKingHZ@gmail.com>

* add basic statistic func

* add basic statistic func

* revise the script

* remove copy&move image func

* Update docs/zh_cn/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update docs/en/user_guides/useful_tools.md

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* Update tools/dataset_converters/yolo2coco.py

Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

* revise image_dir

Co-authored-by: HinGwenWoong <peterhuang0323@qq.com>
Co-authored-by: Range King <RangeKingHZ@gmail.com>
Co-authored-by: Haian Huang(深度眸) <1286304229@qq.com>

docs/en/user_guides/useful_tools.md

@@ -108,17 +108,65 @@ python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncb
                                                --not-show
 ```
 
-## Dataset Conversion
+## Convert Dataset
 
-the `tools/` directory also contains script to convert the `balloon` dataset (A small dataset is only for beginner use) into COCO format.
+The folder `tools/data_converters` currently contains `ballon2coco.py` and `yolo2coco.py` two dataset conversion tools.
 
-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).
+- `ballon2coco.py` converts the `balloon` dataset (this small dataset is for starters only) to COCO format.
+
+For a detailed description of this script, please see the `Dataset Preparation` section in [From getting started to deployment with YOLOv5](./yolov5_tutorial.md).
 
 ```shell
 python tools/dataset_converters/balloon2coco.py
 ```
 
-## Dataset Download
+- `yolo2coco.py` converts a dataset from `yolo-style` **.txt** format to COCO format, please use it as follows:
+
+```shell
+python tools/dataset_converters/yolo2coco.py /path/to/the/root/dir/of/your_dataset
+```
+
+Instructions:
+
+1. `image_dir` is the root directory of the yolo-style dataset you need to pass to the script, which should contain `images`, `labels`, and `classes.txt`. `classes.txt` is the class declaration corresponding to the current dataset. One class a line. The structure of the root directory should be formatted as this example shows:
+
+```bash
+.
+└── $ROOT_PATH
+    ├── classes.txt
+    ├── labels
+    │    ├── a.txt
+    │    ├── b.txt
+    │    └── ...
+    ├── images
+    │    ├── a.jpg
+    │    ├── b.png
+    │    └── ...
+    └── ...
+```
+
+2. The script will automatically check if `train.txt`, `val.txt`, and `test.txt` have already existed under `image_dir`. If these files are located, the script will organize the dataset accordingly. Otherwise, the script will convert the dataset into one file. The image paths in these files must be **ABSOLUTE** paths.
+3. By default, the script will create a folder called `annotations` in the `image_dir` directory which stores the converted JSON file. If `train.txt`, `val.txt`, and `test.txt` are not found, the output file is `result.json`. Otherwise, the corresponding JSON file will be generated, named as `train.json`, `val.json`, and `test.json`. The `annotations` folder may look similar to this:
+
+```bash
+.
+└── $ROOT_PATH
+    ├── annotations
+    │    ├── result.json
+    │    └── ...
+    ├── classes.txt
+    ├── labels
+    │    ├── a.txt
+    │    ├── b.txt
+    │    └── ...
+    ├── images
+    │    ├── a.jpg
+    │    ├── b.png
+    │    └── ...
+    └── ...
+```
+
+## Download Dataset
 
 `tools/misc/download_dataset.py` supports downloading datasets such as `COCO`, `VOC`, `LVIS` and `Balloon`.
 
@@ -129,9 +177,9 @@ 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
+## Convert Model
 
-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.
+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
 

docs/zh_cn/overview.md

@@ -35,18 +35,18 @@ MMYOLO 文件结构和 MMDetection 完全一致。为了能够充分复用 MMDet
 
 2. MMYOLO 的基本使用方法请参考以下教程：
 
-   - [训练和测试](https://mmyolo.readthedocs.io/zh_cn/latest/user_guides/index.html#训练-测试)
-   - [从入门到部署全流程](https://mmyolo.readthedocs.io/zh_cn/latest/user_guides/index.html#从入门到部署全流程)
-   - [实用工具](https://mmyolo.readthedocs.io/zh_cn/latest/user_guides/index.html#实用工具)
+   - [训练和测试](https://mmyolo.readthedocs.io/zh_CN/latest/user_guides/index.html#id1)
+   - [从入门到部署全流程](https://mmyolo.readthedocs.io/zh_CN/latest/user_guides/index.html#id2)
+   - [实用工具](https://mmyolo.readthedocs.io/zh_CN/latest/user_guides/index.html#id3)
 
 3. YOLO 系列算法实现和全解析教程：
 
-   - [必备基础](https://mmyolo.readthedocs.io/zh_CN/latest/algorithm_descriptions/index.html#必备基础)
-   - [原理和实现全解析](https://mmyolo.readthedocs.io/zh_cn/latest/algorithm_descriptions/index.html#原理和实现全解析)
+   - [必备基础](https://mmyolo.readthedocs.io/zh_CN/latest/algorithm_descriptions/index.html#id1)
+   - [原理和实现全解析](https://mmyolo.readthedocs.io/zh_CN/latest/algorithm_descriptions/index.html#id2)
 
 4. 参考以下教程深入了解：
 
-   - [数据流](https://mmyolo.readthedocs.io/zh_cn/latest/advanced_guides/index.html#数据流)
-   - [How to](https://mmyolo.readthedocs.io/zh_cn/latest/advanced_guides/index.html#how-to)
+   - [数据流](https://mmyolo.readthedocs.io/zh_CN/latest/advanced_guides/index.html#id1)
+   - [How to](https://mmyolo.readthedocs.io/zh_CN/latest/advanced_guides/index.html#how-to)
 
 5. [解读文章和资源汇总](article.md)

docs/zh_cn/user_guides/useful_tools.md

@@ -110,14 +110,63 @@ python tools/analysis_tools/browse_dataset.py 'configs/yolov5/yolov5_s-v61_syncb
 
 ## 数据集转换
 
-文件夹 `tools/data_converters/` 包含工具将 `balloon` 数据集（该小型数据集仅作为入门使用）转换成 COCO 的格式。
+文件夹 `tools/data_converters/` 目前包含 `ballon2coco.py` 和 `yolo2coco.py` 两个数据集转换工具。
+
+- `ballon2coco.py` 将 `balloon` 数据集（该小型数据集仅作为入门使用）转换成 COCO 的格式。
 
 关于该脚本的详细说明，请看 [YOLOv5 从入门到部署全流程](./yolov5_tutorial.md) 中 `数据集准备` 小节。
 
 ```shell
 python tools/dataset_converters/balloon2coco.py
 ```
 
+- `yolo2coco.py` 将 `yolo-style` **.txt** 格式的数据集转换成 COCO 的格式，请按如下方式使用：
+
+```shell
+python tools/dataset_converters/yolo2coco.py /path/to/the/root/dir/of/your_dataset
+```
+
+使用说明：
+
+1. `image_dir` 是需要你传入的待转换的 yolo 格式数据集的根目录，内应包含 `images` 、 `labels` 和 `classes.txt` 文件， `classes.txt` 是当前 dataset 对应的类的声明，一行一个类别。
+   `image_dir` 结构如下例所示：
+
+```bash
+.
+└── $ROOT_PATH
+    ├── classes.txt
+    ├── labels
+    │    ├── a.txt
+    │    ├── b.txt
+    │    └── ...
+    ├── images
+    │    ├── a.jpg
+    │    ├── b.png
+    │    └── ...
+    └── ...
+```
+
+2. 脚本会检测 `image_dir` 下是否已有的 `train.txt` 、 `val.txt` 和 `test.txt` 。若检测到文件，则会按照类别进行整理， 否则默认不需要分类。故请确保对应的 `train.txt` 、 `val.txt` 和 `test.txt` 要在 `image_dir` 内。文件内的图片路径必须是**绝对路径**。
+3. 脚本会默认在 `image_dir` 目录下创建 `annotations` 文件夹并将转换结果存在这里。如果在 `image_dir` 下没找到分类文件，输出文件即为一个 `result.json`，反之则会生成需要的 `train.json` 、 `val.json`、 `test.json`，脚本完成后 `annotations` 结构可如下例所示：
+
+```bash
+.
+└── $ROOT_PATH
+    ├── annotations
+    │    ├── result.json
+    │    └── ...
+    ├── classes.txt
+    ├── labels
+    │    ├── a.txt
+    │    ├── b.txt
+    │    └── ...
+    ├── images
+    │    ├── a.jpg
+    │    ├── b.png
+    │    └── ...
+    └── ...
+```
+
 ## 数据集下载
 
 脚本 `tools/misc/download_dataset.py` 支持下载数据集，例如 `COCO`、`VOC`、`LVIS` 和 `Balloon`.