From 3e198e63e81d09693db4f3659f0bf7d137369a54 Mon Sep 17 00:00:00 2001 From: Ma Zerun Date: Wed, 1 Jun 2022 18:31:57 +0800 Subject: [PATCH] [Docs] Update install tutorials. (#854) * [Docs] Update install tutorials. * [Docs] Improve dataset docs * Add option to show the results in demo. * fix typo --- demo/image_demo.py | 10 +- docs/en/faq.md | 82 ++++++++ docs/en/index.rst | 4 +- docs/en/install.md | 282 ++++++++++++++++------------ docs/en/tutorials/new_dataset.md | 182 +++++++++++++----- docs/zh_CN/compatibility.md | 7 + docs/zh_CN/faq.md | 72 +++++++ docs/zh_CN/index.rst | 4 +- docs/zh_CN/install.md | 262 +++++++++++++++----------- docs/zh_CN/tutorials/new_dataset.md | 158 ++++++++++++---- mmcls/models/backbones/densenet.py | 2 +- mmcls/models/backbones/van.py | 2 +- 12 files changed, 760 insertions(+), 307 deletions(-) create mode 100644 docs/en/faq.md create mode 100644 docs/zh_CN/compatibility.md create mode 100644 docs/zh_CN/faq.md diff --git a/demo/image_demo.py b/demo/image_demo.py index 23de6673f07..8539ef48fe1 100644 --- a/demo/image_demo.py +++ b/demo/image_demo.py @@ -1,6 +1,8 @@ # Copyright (c) OpenMMLab. All rights reserved. from argparse import ArgumentParser +import mmcv + from mmcls.apis import inference_model, init_model, show_result_pyplot @@ -9,6 +11,10 @@ def main(): parser.add_argument('img', help='Image file') parser.add_argument('config', help='Config file') parser.add_argument('checkpoint', help='Checkpoint file') + parser.add_argument( + '--show', + action='store_true', + help='Whether to show the predict results by matplotlib.') parser.add_argument( '--device', default='cuda:0', help='Device used for inference') args = parser.parse_args() @@ -18,7 +24,9 @@ def main(): # test a single image result = inference_model(model, args.img) # show the results - show_result_pyplot(model, args.img, result) + print(mmcv.dump(result, file_format='json', indent=4)) + if args.show: + show_result_pyplot(model, args.img, result) if __name__ == '__main__': diff --git a/docs/en/faq.md b/docs/en/faq.md new file mode 100644 index 00000000000..a2e0f7bf6c1 --- /dev/null +++ b/docs/en/faq.md @@ -0,0 +1,82 @@ +# Frequently Asked Questions + +We list some common troubles faced by many users and their corresponding +solutions here. Feel free to enrich the list if you find any frequent issues +and have ways to help others to solve them. If the contents here do not cover +your issue, please create an issue using the +[provided templates](https://github.com/open-mmlab/mmclassification/issues/new/choose) +and make sure you fill in all required information in the template. + +## Installation + +- Compatibility issue between MMCV and MMClassification; "AssertionError: + MMCV==xxx is used but incompatible. Please install mmcv>=xxx, <=xxx." + + Compatible MMClassification and MMCV versions are shown as below. Please + choose the correct version of MMCV to avoid installation issues. + + | MMClassification version | MMCV version | + |:------------------------:|:---------------------:| + | dev | mmcv>=1.5.0, <1.6.0 | + | 0.23.0 (master) | mmcv>=1.4.2, <1.6.0 | + | 0.22.1 | mmcv>=1.4.2, <1.6.0 | + | 0.21.0 | mmcv>=1.4.2, <=1.5.0 | + | 0.20.1 | mmcv>=1.4.2, <=1.5.0 | + | 0.19.0 | mmcv>=1.3.16, <=1.5.0 | + | 0.18.0 | mmcv>=1.3.16, <=1.5.0 | + | 0.17.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.16.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.15.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.15.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.14.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.13.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.12.0 | mmcv>=1.3.1, <=1.5.0 | + | 0.11.1 | mmcv>=1.3.1, <=1.5.0 | + | 0.11.0 | mmcv>=1.3.0 | + | 0.10.0 | mmcv>=1.3.0 | + | 0.9.0 | mmcv>=1.1.4 | + | 0.8.0 | mmcv>=1.1.4 | + | 0.7.0 | mmcv>=1.1.4 | + | 0.6.0 | mmcv>=1.1.4 | + + ```{note} + Since the `dev` branch is under frequent development, the MMCV + version dependency may be inaccurate. If you encounter problems when using + the `dev` branch, please try to update MMCV to the latest version. + ``` + +- Using Albumentations + + If you would like to use `albumentations`, we suggest using `pip install -r requirements/albu.txt` or + `pip install -U albumentations --no-binary qudida,albumentations`. + + If you simply use `pip install albumentations>=0.3.2`, it will install `opencv-python-headless` simultaneously + (even though you have already installed `opencv-python`). Please refer to the + [official documentation](https://albumentations.ai/docs/getting_started/installation/#note-on-opencv-dependencies) + for details. + +## Coding + +- Do I need to reinstall mmcls after some code modifications? + + If you follow [the best practice](install.md) and install mmcls from source, + any local modifications made to the code will take effect without + reinstallation. + +- How to develop with multiple MMClassification versions? + + Generally speaking, we recommend to use different virtual environments to + manage MMClassification in different working directories. However, you + can also use the same environment to develop MMClassification in different + folders, like mmcls-0.21, mmcls-0.23. When you run the train or test shell script, + it will adopt the mmcls package in the current folder. And when you run other Python + script, you can also add ``PYTHONPATH=`pwd` `` at the beginning of your command + to use the package in the current folder. + + Conversely, to use the default MMClassification installed in the environment + rather than the one you are working with, you can remove the following line + in those shell scripts: + + ```shell + PYTHONPATH="$(dirname $0)/..":$PYTHONPATH + ``` diff --git a/docs/en/index.rst b/docs/en/index.rst index 615bb24ae2e..5fb3a774c5e 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -72,9 +72,11 @@ You can switch between Chinese and English documentation in the lower-left corne .. toctree:: :maxdepth: 1 - :caption: Changelog + :caption: Notes changelog.md + compatibility.md + faq.md .. toctree:: :caption: Language Switch diff --git a/docs/en/install.md b/docs/en/install.md index df130111050..034556d2798 100644 --- a/docs/en/install.md +++ b/docs/en/install.md @@ -1,173 +1,219 @@ -# Installation +# Prerequisites + +In this section we demonstrate how to prepare an environment with PyTorch. -## Requirements - -- Python 3.6+ -- PyTorch 1.5+ -- [MMCV](https://github.com/open-mmlab/mmcv) - -The compatible MMClassification and MMCV versions are as below. Please install the correct version of MMCV to avoid installation issues. - -| MMClassification version | MMCV version | -|:------------------------:|:---------------------:| -| dev | mmcv>=1.5.0, <1.6.0 | -| 0.23.0 (master) | mmcv>=1.4.2, <1.6.0 | -| 0.22.1 | mmcv>=1.4.2, <1.6.0 | -| 0.21.0 | mmcv>=1.4.2, <=1.5.0 | -| 0.20.1 | mmcv>=1.4.2, <=1.5.0 | -| 0.19.0 | mmcv>=1.3.16, <=1.5.0 | -| 0.18.0 | mmcv>=1.3.16, <=1.5.0 | -| 0.17.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.16.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.15.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.15.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.14.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.13.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.12.0 | mmcv>=1.3.1, <=1.5.0 | -| 0.11.1 | mmcv>=1.3.1, <=1.5.0 | -| 0.11.0 | mmcv>=1.3.0 | -| 0.10.0 | mmcv>=1.3.0 | -| 0.9.0 | mmcv>=1.1.4 | -| 0.8.0 | mmcv>=1.1.4 | -| 0.7.0 | mmcv>=1.1.4 | -| 0.6.0 | mmcv>=1.1.4 | +MMClassification works on Linux, Windows and macOS. It requires Python 3.6+, CUDA 9.2+ and PyTorch 1.5+. ```{note} -Since the `dev` branch is under frequent development, the `mmcv` -version dependency may be inaccurate. If you encounter problems when using -the `dev` branch, please try to update `mmcv` to the latest version. +If you are experienced with PyTorch and have already installed it, just skip this part and jump to the [next section](#installation). Otherwise, you can follow these steps for the preparation. +``` + +**Step 1.** Download and install Miniconda from the [official website](https://docs.conda.io/en/latest/miniconda.html). + +**Step 2.** Create a conda environment and activate it. + +```shell +conda create --name openmmlab python=3.8 -y +conda activate openmmlab ``` -## Install Dependencies +**Step 3.** Install PyTorch following [official instructions](https://pytorch.org/get-started/locally/), e.g. -1. Create a conda virtual environment and activate it. +On GPU platforms: - ```shell - conda create -n open-mmlab python=3.8 -y - conda activate open-mmlab - ``` +```shell +conda install pytorch torchvision -c pytorch +``` -2. Install PyTorch and torchvision following the [official instructions](https://pytorch.org/), e.g., +```{warning} +This command will automatically install the latest version PyTorch and cudatoolkit, please check whether they matches your environment. +``` - ```shell - conda install pytorch torchvision -c pytorch - ``` +On CPU platforms: - ```{note} - Make sure that your compilation CUDA version and runtime CUDA version match. - You can check the supported CUDA version for precompiled packages on the - [PyTorch website](https://pytorch.org/). - ``` +```shell +conda install pytorch torchvision cpuonly -c pytorch +``` - *E.g.1* If you have CUDA 10.1 installed under `/usr/local/cuda` and would like to install - PyTorch 1.5.1, you need to install the prebuilt PyTorch with CUDA 10.1. +# Installation - ```shell - conda install pytorch==1.5.1 torchvision==0.6.1 cudatoolkit=10.1 -c pytorch - ``` +We recommend that users follow our best practices to install MMClassification. However, the whole process is highly customizable. See [Customize Installation](#customize-installation) section for more information. - *E.g.2* If you have CUDA 11.3 installed under `/usr/local/cuda` and would like to install - PyTorch 1.10.1, you need to install the prebuilt PyTorch with CUDA 11.3. +## Best Practices - ```shell - conda install pytorch==1.10.1 torchvision==0.11.2 cudatoolkit=11.3 -c pytorch - ``` +**Step 0.** Install [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim). - If you build PyTorch from source instead of installing the prebuilt package, - you can use more CUDA versions such as 9.0. +```shell +pip install -U openmim +mim install mmcv-full +``` + +**Step 1.** Install MMClassification. + +According to your needs, we support two install modes: + +- [Install from source (Recommended)](#install-from-source): You want to develop your own image classification task or new features based on MMClassification framework. For example, you want to add new dataset or new models. And you can use all tools we provided. +- [Install as a Python package](#install-as-a-python-package): You just want to call MMClassification's APIs or import MMClassification's modules in your project. + +### Install from source + +In this case, install mmcls from source: + +```shell +git clone https://github.com/open-mmlab/mmclassification.git +cd mmclassification +pip install -v -e . +# "-v" means verbose, or more output +# "-e" means installing a project in editable mode, +# thus any local modifications made to the code will take effect without reinstallation. +``` + +Optionally, if you want to contribute to MMClassification or experience experimental functions, please checkout to the dev branch: + +```shell +git checkout dev +``` -3. Install MMCV +### Install as a Python package - MMCV is a foundational library for MMClassification. And there are two versions of MMCV. +Just install with pip. - - **mmcv**: lite, without CUDA ops but all other features, similar to mmcv<1.0.0. It is useful when you do not need those CUDA ops. - - **mmcv-full**: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build. +```shell +pip install mmcls +``` - If you want to install mmcv-full, you can install/compile it according to the [instructions](https://mmcv.readthedocs.io/en/latest/get_started/installation.html). +## Verify the installation - A better choice is to use [MIM](https://github.com/open-mmlab/mim) to automatically select the mmcv-full version. MIM will automatically install mmcv-full when you use it to install MMClassification in the next section. +To verify whether MMClassification is installed correctly, we provide some sample codes to run an inference demo. - ```shell - pip install openmim - ``` +**Step 1.** We need to download config and checkpoint files. -## Install MMClassification repository +```shell +mim download mmcls --config resnet50_8xb32_in1k --dest . +``` -According to your needs, we support two install modes. +**Step 2.** Verify the inference demo. -- [Use as a Python package](#use-as-a-python-package): In this mode, you just want to call MMClassification's APIs or import MMClassification's modules in your project. -- [Develop based on MMClassification (Recommended)](#develop-based-on-mmclassification): In this mode, you want to develop your own image classification task or new features based on MMClassification framework. For example, you want to add new dataset or new models. And you can use all tools we provided. +Option (a). If you install mmcls from source, just run the following command: -### Use as a Python package +```shell +python demo/image_demo.py demo/demo.JPEG resnet50_8xb32_in1k.py resnet50_8xb32_in1k_20210831-ea4938fc.pth --device cpu +``` -If you have installed MIM, simply use `mim install mmcls` to install -MMClassification. MIM will automatically install the mmcv-full which fits your -environment. In addition, MIM also has some other functions to help to do -training, parameter searching and model filtering, etc. +You will see the output result dict including `pred_label`, `pred_score` and `pred_class` in your terminal. +And if you have graphical interface (instead of remote terminal etc.), you can enable `--show` option to show +the demo image with these predictions in a window. -Or, you can use pip to install MMClassification with `pip install mmcls`. In -this situation, if you want to use mmcv-full, please install it manually in -advance. +Option (b). If you install mmcls as a python package, open you python interpreter and copy&paste the following codes. -### Develop based on MMClassification +```python +from mmcls.apis import init_model, inference_model -In this mode, any local modifications made to the code will take effect without -the need to reinstall it (unless you submit some commits and want to update the -version number). +config_file = 'resnet50_8xb32_in1k.py' +checkpoint_file = 'resnet50_8xb32_in1k_20210831-ea4938fc.pth' +model = init_model(config_file, checkpoint_file, device='cpu') # or device='cuda:0' +inference_model(model, 'demo/demo.JPEG') +``` -1. Clone the MMClassification repository. +You will see a dict printed, including the predicted label, score and category name. - ```shell - git clone https://github.com/open-mmlab/mmclassification.git - cd mmclassification - ``` +## Customize Installation -2. [Optional] Checkout to the `dev` branch. +### CUDA versions - ```shell - git checkout dev - ``` +When installing PyTorch, you need to specify the version of CUDA. If you are +not clear on which to choose, follow our recommendations: - *Do I need to do this?* The `dev` branch is in development and includes some experimental functions. If you want these functions or want to contribute to MMClassification, do it. +- For Ampere-based NVIDIA GPUs, such as GeForce 30 series and NVIDIA A100, CUDA 11 is a must. +- For older NVIDIA GPUs, CUDA 11 is backward compatible, but CUDA 10.2 offers better compatibility and is more lightweight. -3. Install requirements and MMClassification. +Please make sure the GPU driver satisfies the minimum version requirements. See [this table](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions) for more information. - Use MIM, and MIM will automatically install the mmcv-full which fits your environment. - ```shell - mim install -e . - ``` +```{note} +Installing CUDA runtime libraries is enough if you follow our best practices, +because no CUDA code will be compiled locally. However if you hope to compile +MMCV from source or develop other CUDA operators, you need to install the +complete CUDA toolkit from NVIDIA's [website](https://developer.nvidia.com/cuda-downloads), +and its version should match the CUDA version of PyTorch. i.e., the specified +version of cudatoolkit in `conda install` command. +``` - Or use pip, and if you want to use mmcv-full, you need to install it manually in advance. +### Install MMCV without MIM - ```shell - pip install -e . - ``` +MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex +way. MIM solves such dependencies automatically and makes the installation +easier. However, it is not a must. -## Another option: Docker Image +To install MMCV with pip instead of MIM, please follow +[MMCV installation guides](https://mmcv.readthedocs.io/en/latest/get_started/installation.html). +This requires manually specifying a find-url based on PyTorch version and its CUDA version. -We provide a [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) to build an image. +For example, the following command install mmcv-full built for PyTorch 1.10.x and CUDA 11.3. ```shell -# build an image with PyTorch 1.8.1, CUDA 10.2, CUDNN 7 and MMCV-full latest version released. -docker build -f ./docker/Dockerfile --rm -t mmcls:latest . +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html ``` -```{important} -Make sure you've installed the [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker). +### Install on CPU-only platforms + +MMClassification can be built for CPU only environment. In CPU mode you can +train (requires MMCV version >= 1.4.4), test or inference a model. + +Some functionalities are gone in this mode, usually GPU-compiled ops. But don't +worry, almost all models in MMClassification don't depends on these ops. + +### Install on Google Colab + +[Google Colab](https://research.google.com/) usually has PyTorch installed, +thus we only need to install MMCV and MMClassification with the following +commands. + +**Step 1.** Install [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim). + +```shell +!pip3 install openmim +!mim install mmcv-full ``` -Run a container built from mmcls image with command: + **Step 2.** Install MMClassification from the source. ```shell -docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/workspace/mmclassification/data mmcls:latest /bin/bash +!git clone https://github.com/open-mmlab/mmclassification.git +%cd mmclassification +!pip install -e . ``` -## Using multiple MMClassification versions + **Step 3.** Verification. + +```python +import mmcls +print(mmcls.__version__) +# Example output: 0.23.0 or newer +``` + +```{note} +Within Jupyter, the exclamation mark `!` is used to call external executables and `%cd` is a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) to change the current working directory of Python. +``` -The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMClassification in the current directory. + ### Using MMClassification with Docker -To use the default MMClassification installed in the environment rather than that you are working with, you can remove the following line in those scripts +We provide a [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) +to build an image. Ensure that your [docker version](https://docs.docker.com/engine/install/) >=19.03. ```shell -PYTHONPATH="$(dirname $0)/..":$PYTHONPATH +# build an image with PyTorch 1.8.1, CUDA 10.2 +# If you prefer other versions, just modified the Dockerfile +docker build -t mmclassification docker/ ``` + +Run it with + +```shell +docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmclassification/data mmclassification +``` + +## Trouble shooting + +If you have some issues during the installation, please first view the [FAQ](faq.md) page. +You may [open an issue](https://github.com/open-mmlab/mmclassification/issues/new/choose) +on GitHub if no solution is found. diff --git a/docs/en/tutorials/new_dataset.md b/docs/en/tutorials/new_dataset.md index a5068cedc70..25fe3bff19e 100644 --- a/docs/en/tutorials/new_dataset.md +++ b/docs/en/tutorials/new_dataset.md @@ -1,47 +1,139 @@ -# Tutorial 3: Adding New Dataset +# Tutorial 3: Customize Dataset -## Customize datasets by reorganizing data +We support many common public datasets for image classification task, you can find them in +[this page](https://mmclassification.readthedocs.io/en/master/api/datasets.html). -### Reorganize dataset to existing format +In this section, we demonstrate how to [use your own dataset](#use-your-own-dataset) +and [use dataset wrapper](#use-dataset-wrapper). + +## Use your own dataset -The simplest way is to convert your dataset to existing dataset formats (ImageNet). +### Reorganize dataset to existing format -For training, it differentiates classes by folders. The directory of training data is as follows: +The simplest way to use your own dataset is to convert it to existing dataset formats. + +For multi-class classification task, we recommend to use the format of +[`CustomDataset`](https://mmclassification.readthedocs.io/en/master/api/datasets.html#mmcls.datasets.CustomDataset). + +The `CustomDataset` supports two kinds of format: + +1. An annotation file is provided, and each line indicates a sample image. + + The sample images can be organized in any structure, like: + + ``` + train/ + ├── folder_1 + │ ├── xxx.png + │ ├── xxy.png + │ └── ... + ├── 123.png + ├── nsdf3.png + └── ... + ``` + + And an annotation file records all paths of samples and corresponding + category index. The first column is the image path relative to the folder + (in this example, `train`) and the second column is the index of category: + + ``` + folder_1/xxx.png 0 + folder_1/xxy.png 1 + 123.png 1 + nsdf3.png 2 + ... + ``` + + ```{note} + The value of the category indices should fall in range `[0, num_classes - 1]`. + ``` + +2. The sample images are arranged in the special structure: + + ``` + train/ + ├── cat + │ ├── xxx.png + │ ├── xxy.png + │ └── ... + │ └── xxz.png + ├── bird + │ ├── bird1.png + │ ├── bird2.png + │ └── ... + └── dog + ├── 123.png + ├── nsdf3.png + ├── ... + └── asd932_.png + ``` + + In this case, you don't need provide annotation file, and all images in the directory `cat` will be + recognized as samples of `cat`. + +Usually, we will split the whole dataset to three sub datasets: `train`, `val` +and `test` for training, validation and test. And **every** sub dataset should +be organized as one of the above structures. + +For example, the whole dataset is as below (using the first structure): ``` -imagenet -├── ... -├── train -│ ├── n01440764 -│ │ ├── n01440764_10026.JPEG -│ │ ├── n01440764_10027.JPEG -│ │ ├── ... -│ ├── ... -│ ├── n15075141 -│ │ ├── n15075141_999.JPEG -│ │ ├── n15075141_9993.JPEG -│ │ ├── ... +mmclassification +└── data + └── my_dataset + ├── meta + │ ├── train.txt + │ ├── val.txt + │ └── test.txt + ├── train + ├── val + └── test ``` -For validation, we provide a annotation list. Each line of the list contrains a filename and its corresponding ground-truth labels. The format is as follows: +And in your config file, you can modify the `data` field as below: -``` -ILSVRC2012_val_00000001.JPEG 65 -ILSVRC2012_val_00000002.JPEG 970 -ILSVRC2012_val_00000003.JPEG 230 -ILSVRC2012_val_00000004.JPEG 809 -ILSVRC2012_val_00000005.JPEG 516 +```python +... +dataset_type = 'CustomDataset' +classes = ['cat', 'bird', 'dog'] # The category names of your dataset + +data = dict( + train=dict( + type=dataset_type, + data_prefix='data/my_dataset/train', + ann_file='data/my_dataset/meta/train.txt', + classes=classes, + pipeline=train_pipeline + ), + val=dict( + type=dataset_type, + data_prefix='data/my_dataset/val', + ann_file='data/my_dataset/meta/val.txt', + classes=classes, + pipeline=test_pipeline + ), + test=dict( + type=dataset_type, + data_prefix='data/my_dataset/test', + ann_file='data/my_dataset/meta/test.txt', + classes=classes, + pipeline=test_pipeline + ) +) +... ``` -Note: The value of ground-truth labels should fall in range `[0, num_classes - 1]`. +### Create a new dataset class -### An example of customized dataset +You can write a new dataset class inherited from `BaseDataset`, and overwrite `load_annotations(self)`, +like [CIFAR10](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/cifar.py) and +[CustomDataset](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/custom.py). -You can write a new Dataset class inherited from `BaseDataset`, and overwrite `load_annotations(self)`, -like [CIFAR10](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/cifar.py) and [ImageNet](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/imagenet.py). -Typically, this function returns a list, where each sample is a dict, containing necessary data information, e.g., `img` and `gt_label`. +Typically, this function returns a list, where each sample is a dict, containing necessary data information, +e.g., `img` and `gt_label`. -Assume we are going to implement a `Filelist` dataset, which takes filelists for both training and testing. The format of annotation list is as follows: +Assume we are going to implement a `Filelist` dataset, which takes filelists for both training and testing. +The format of annotation list is as follows: ``` 000001.jpg 0 @@ -93,22 +185,24 @@ Then in the config, to use `Filelist` you can modify the config as the following ```python train = dict( type='Filelist', - ann_file = 'image_list.txt', + ann_file='image_list.txt', pipeline=train_pipeline ) ``` -## Customize datasets by mixing dataset +## Use dataset wrapper -MMClassification also supports to mix dataset for training. -Currently it supports to concat and repeat datasets. +The dataset wrapper is a kind of class to change the behavior of dataset class, such as repeat the dataset or +re-balance the samples of different categories. ### Repeat dataset -We use `RepeatDataset` as wrapper to repeat the dataset. For example, suppose the original dataset is `Dataset_A`, to repeat it, the config looks like the following +We use `RepeatDataset` as wrapper to repeat the dataset. For example, suppose the original dataset is +`Dataset_A`, to repeat it, the config looks like the following ```python -dataset_A_train = dict( +data = dict( + train = dict( type='RepeatDataset', times=N, dataset=dict( # This is the original config of Dataset_A @@ -117,17 +211,19 @@ dataset_A_train = dict( pipeline=train_pipeline ) ) + ... +) ``` ### Class balanced dataset -We use `ClassBalancedDataset` as wrapper to repeat the dataset based on category -frequency. The dataset to repeat needs to instantiate function `self.get_cat_ids(idx)` -to support `ClassBalancedDataset`. -For example, to repeat `Dataset_A` with `oversample_thr=1e-3`, the config looks like the following +We use `ClassBalancedDataset` as wrapper to repeat the dataset based on category frequency. The dataset to +repeat needs to implement method `get_cat_ids(idx)` to support `ClassBalancedDataset`. For example, to repeat +`Dataset_A` with `oversample_thr=1e-3`, the config looks like the following ```python -dataset_A_train = dict( +data = dict( + train = dict( type='ClassBalancedDataset', oversample_thr=1e-3, dataset=dict( # This is the original config of Dataset_A @@ -136,6 +232,8 @@ dataset_A_train = dict( pipeline=train_pipeline ) ) + ... +) ``` -You may refer to [source code](https://github.com/open-mmlab/mmclassification/tree/master/mmcls/datasets/dataset_wrappers.py) for details. +You may refer to [API reference](https://mmclassification.readthedocs.io/en/master/api/datasets.html#mmcls.datasets.ClassBalancedDataset) for details. diff --git a/docs/zh_CN/compatibility.md b/docs/zh_CN/compatibility.md new file mode 100644 index 00000000000..178e555b6df --- /dev/null +++ b/docs/zh_CN/compatibility.md @@ -0,0 +1,7 @@ +# 0.x 相关兼容性问题 + +## MMClassification 0.20.1 + +### MMCV 兼容性 + +在 Twins 骨干网络中，我们使用了 MMCV 提供的 `PatchEmbed` 模块，该模块是在 MMCV 1.4.2 版本加入的，因此我们需要将 MMCV 依赖版本升至 1.4.2。 diff --git a/docs/zh_CN/faq.md b/docs/zh_CN/faq.md new file mode 100644 index 00000000000..82af2f51aa9 --- /dev/null +++ b/docs/zh_CN/faq.md @@ -0,0 +1,72 @@ +# 常见问题 + +我们在这里列出了一些常见问题及其相应的解决方案。如果您发现任何常见问题并有方法 +帮助解决，欢迎随时丰富列表。如果这里的内容没有涵盖您的问题，请按照 +[提问模板](https://github.com/open-mmlab/mmclassification/issues/new/choose) +在 GitHub 上提出问题，并补充模板中需要的信息。 + +## 安装 + +- MMCV 与 MMClassification 的兼容问题。如遇到 + "AssertionError: MMCV==xxx is used but incompatible. Please install mmcv>=xxx, <=xxx." + + 这里我们列举了各版本 MMClassification 对 MMCV 版本的依赖，请选择合适的 MMCV + 版本来避免安装和使用中的问题。 + + | MMClassification version | MMCV version | + |:------------------------:|:---------------------:| + | dev | mmcv>=1.5.0, <1.6.0 | + | 0.23.0 (master) | mmcv>=1.4.2, <1.6.0 | + | 0.22.1 | mmcv>=1.4.2, <1.6.0 | + | 0.21.0 | mmcv>=1.4.2, <=1.5.0 | + | 0.20.1 | mmcv>=1.4.2, <=1.5.0 | + | 0.19.0 | mmcv>=1.3.16, <=1.5.0 | + | 0.18.0 | mmcv>=1.3.16, <=1.5.0 | + | 0.17.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.16.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.15.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.15.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.14.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.13.0 | mmcv>=1.3.8, <=1.5.0 | + | 0.12.0 | mmcv>=1.3.1, <=1.5.0 | + | 0.11.1 | mmcv>=1.3.1, <=1.5.0 | + | 0.11.0 | mmcv>=1.3.0 | + | 0.10.0 | mmcv>=1.3.0 | + | 0.9.0 | mmcv>=1.1.4 | + | 0.8.0 | mmcv>=1.1.4 | + | 0.7.0 | mmcv>=1.1.4 | + | 0.6.0 | mmcv>=1.1.4 | + + ```{note} + 由于 `dev` 分支处于频繁开发中，MMCV 版本依赖可能不准确。如果您在使用 + `dev` 分支时遇到问题，请尝试更新 MMCV 到最新版。 + ``` + +- 使用 Albumentations + + 如果你希望使用 `albumentations` 相关的功能，我们建议使用 `pip install -r requirements/optional.txt` 或者 + `pip install -U albumentations>=0.3.2 --no-binary qudida,albumentations` 命令进行安装。 + + 如果你直接使用 `pip install albumentations>=0.3.2` 来安装，它会同时安装 `opencv-python-headless` + （即使你已经安装了 `opencv-python`）。具体细节可参阅 + [官方文档](https://albumentations.ai/docs/getting_started/installation/#note-on-opencv-dependencies)。 + +## 开发 + +- 如果我对源码进行了改动，需要重新安装以使改动生效吗？ + + 如果你遵照[最佳实践](install.md)的指引，从源码安装 mmcls，那么任何本地修改都不需要重新安装即可生效。 + +- 如何在多个 MMClassification 版本下进行开发？ + + 通常来说，我们推荐通过不同虚拟环境来管理多个开发目录下的 MMClassification。 + 但如果你希望在不同目录（如 mmcls-0.21, mmcls-0.23 等）使用同一个环境进行开发， + 我们提供的训练和测试 shell 脚本会自动使用当前目录的 mmcls，其他 Python 脚本 + 则可以在命令前添加 ``PYTHONPATH=`pwd` `` 来使用当前目录的代码。 + + 反过来，如果你希望 shell 脚本使用环境中安装的 MMClassification，而不是当前目录的， + 则可以去掉 shell 脚本中如下一行代码： + + ```shell + PYTHONPATH="$(dirname $0)/..":$PYTHONPATH + ``` diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index 11120da80e5..83634b031aa 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -71,9 +71,11 @@ You can switch between Chinese and English documentation in the lower-left corne .. toctree:: :maxdepth: 1 - :caption: 更新日志 + :caption: 其他说明 changelog.md + compatibility.md + faq.md .. toctree:: diff --git a/docs/zh_CN/install.md b/docs/zh_CN/install.md index c6630300b54..e88158660e3 100644 --- a/docs/zh_CN/install.md +++ b/docs/zh_CN/install.md @@ -1,164 +1,210 @@ -# 安装 +# 依赖环境 + +在本节中，我们将演示如何准备 PyTorch 相关的依赖环境。 -## 安装依赖包 - -- Python 3.6+ -- PyTorch 1.5+ -- [MMCV](https://github.com/open-mmlab/mmcv) - -MMClassification 和 MMCV 的适配关系如下，请安装正确版本的 MMCV 以避免安装问题 - -| MMClassification 版本 | MMCV 版本 | -|:------------------------:|:---------------------:| -| dev | mmcv>=1.4.8, <1.6.0 | -| 0.23.0 (master) | mmcv>=1.4.2, <1.6.0 | -| 0.22.1 | mmcv>=1.4.2, <1.6.0 | -| 0.21.0 | mmcv>=1.4.2, <=1.5.0 | -| 0.20.1 | mmcv>=1.4.2, <=1.5.0 | -| 0.19.0 | mmcv>=1.3.16, <=1.5.0 | -| 0.18.0 | mmcv>=1.3.16, <=1.5.0 | -| 0.17.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.16.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.15.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.15.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.14.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.13.0 | mmcv>=1.3.8, <=1.5.0 | -| 0.12.0 | mmcv>=1.3.1, <=1.5.0 | -| 0.11.1 | mmcv>=1.3.1, <=1.5.0 | -| 0.11.0 | mmcv>=1.3.0 | -| 0.10.0 | mmcv>=1.3.0 | -| 0.9.0 | mmcv>=1.1.4 | -| 0.8.0 | mmcv>=1.1.4 | -| 0.7.0 | mmcv>=1.1.4 | -| 0.6.0 | mmcv>=1.1.4 | +MMClassification 适用于 Linux、Windows 和 macOS。它需要 Python 3.6+、CUDA 9.2+ 和 PyTorch 1.5+。 ```{note} -由于 `dev` 分支处于频繁开发中，`mmcv` 版本依赖可能不准确。如果您在使用 -`dev` 分支时遇到问题，请尝试更新 `mmcv` 到最新版。 +如果你对配置 PyTorch 环境已经很熟悉，并且已经完成了配置，可以直接进入[下一节](#安装)。 +否则的话，请依照以下步骤完成配置。 ``` -## 安装依赖环境 +**第 1 步** 从[官网](https://docs.conda.io/en/latest/miniconda.html)下载并安装 Miniconda。 -1. 创建 conda 虚拟环境，并激活 +**第 2 步** 创建一个 conda 虚拟环境并激活它。 - ```shell - conda create -n open-mmlab python=3.8 -y - conda activate open-mmlab - ``` +```shell +conda create --name openmmlab python=3.8 -y +conda activate openmmlab +``` -2. 按照 [官方指南](https://pytorch.org/) 安装 PyTorch 和 TorchVision，如： +**第 3 步** 按照[官方指南](https://pytorch.org/get-started/locally/)安装 PyTorch。例如： - ```shell - conda install pytorch torchvision -c pytorch - ``` +在 GPU 平台： - ```{note} - 请确保 CUDA 编译版本和运行版本相匹配。 - 可以参照 [PyTorch 官网](https://pytorch.org/) 对预编译包所支持的 CUDA 版本进行核对。 - ``` +```shell +conda install pytorch torchvision -c pytorch +``` - *例 1*：如果你已经安装了 CUDA 10.1 版本，并且想要安装 PyTorch 1.5.1 版本， - 则需要安装 CUDA 10.1 下预编译的 PyTorch。 +```{warning} +以上命令会自动安装最新版的 PyTorch 与对应的 cudatoolkit，请检查它们是否与你的环境匹配。 +``` - ```shell - conda install pytorch==1.5.1 torchvision==0.6.1 cudatoolkit=10.1 -c pytorch - ``` +在 CPU 平台： - *例 2*：如果你已经安装了 CUDA 11.3 版本，并且想要安装 PyTorch 1.10.1 版本， - 则需要安装 CUDA 11.3 下预编译的 PyTorch。 +```shell +conda install pytorch torchvision cpuonly -c pytorch +``` - ```shell - conda install pytorch==1.10.1 torchvision==0.11.2 cudatoolkit=11.3 -c pytorch - ``` +# 安装 - 如果 PyTorch 是由源码进行编译安装（而非直接下载预编译好的安装包），则可以使用更多的 CUDA 版本（如 9.0 版本）。 +我们推荐用户按照我们的最佳实践来安装 MMClassification。但除此之外，如果你想根据 +你的习惯完成安装流程，也可以参见[自定义安装](#自定义安装)一节来获取更多信息。 -3. 安装 MMCV +## 最佳实践 - MMCV 是 MMClassification 的基础库。它有两个版本： +**第 1 步** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMCV](https://github.com/open-mmlab/mmcv) - - **mmcv**：精简版，不包含 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用 CUDA 算子的话，精简版可以作为一个考虑选项。 - - **mmcv-full**：完整版，包含所有的特性以及丰富的开箱即用的 CUDA 算子。注意完整版本可能需要更长时间来编译。 +```shell +pip install -U openmim +mim install mmcv-full +``` - 如果你希望安装 mmcv-full，你可以根据 [该教程](https://mmcv.readthedocs.io/en/latest/get_started/installation.html) 完成安装或编译。 +**第 2 步** 安装 MMClassification - 一个更好的选择是使用 [MIM](https://github.com/open-mmlab/mim) 来自动选择适合你的 mmcv-full 版本。在使用 MIM 安装 MMClassification 的时候，它就会自动完成 mmcv-full 的安装。 +根据具体需求，我们支持两种安装模式： - ```shell - pip install openmim - ``` +- [从源码安装（推荐）](#从源码安装)：希望基于 MMClassification 框架开发自己的图像分类任务，需要添加新的功能，比如新的模型或是数据集，或者使用我们提供的各种工具。 +- [作为 Python 包安装](#作为-python-包安装)：只是希望调用 MMClassification 的 API 接口，或者在自己的项目中导入 MMClassification 中的模块。 -## 安装 MMClassification 库 +### 从源码安装 -根据你的需求，我们支持两种安装模式。 +这种情况下，从源码按如下方式安装 mmcls： -- [仅作为 Python 包使用](#仅作为-python-包使用)：该模式下，你只希望在你的项目中调用 MMClassification 的 API，或者导入 MMClassification 中的模块 -- [基于 MMClassification 进行开发（推荐）](#基于-mmclassification-进行开发)：该模式下，你希望基于 MMClassification 框架开发你自己的图像分类任务，需要添加新的功能，比如新的模型或是数据集。并且你可以使用我们提供的所有工具。 +```shell +git clone https://github.com/open-mmlab/mmclassification.git +cd mmclassification +pip install -v -e . +# "-v" 表示输出更多安装相关的信息 +# "-e" 表示以可编辑形式安装，这样可以在不重新安装的情况下，让本地修改直接生效 +``` -### 仅作为 Python 包使用 +另外，如果你希望向 MMClassification 贡献代码，或者使用试验中的功能，请签出到 `dev` 分支。 -如果你已经安装了 MIM，那么只需要使用 `mim install mmcls` 命令来安装 MMClassification。MIM 将会根据你的环境选择安装合适的 mmcv-full 版本。另外，MIM 还提供了一系列其他功能来协助进行训练、参数搜索及模型筛选等。 +```shell +git checkout dev +``` -或者，你可以直接通过 pip 来安装，使用 `pip install mmcls` 命令。这种情况下，如果你希望使用 mmcv-full，那么需要提前手动安装 mmcv-full。 +### 作为 Python 包安装 -### 基于 MMClassification 进行开发 +直接使用 pip 安装即可。 -在该模式下，任何本地修改都会直接生效，不需要重新安装（除非提交了一些 commit，并且希望提升版本号）。 +```shell +pip install mmcls +``` -1. 克隆最新的 MMClassification 仓库 +## 验证安装 - ```shell - git clone https://github.com/open-mmlab/mmclassification.git - cd mmclassification - ``` +为了验证 MMClassification 的安装是否正确，我们提供了一些示例代码来执行模型推理。 -2. 【可选】 签出到 `dev` 分支 +**第 1 步** 我们需要下载配置文件和模型权重文件 - ```shell - git checkout dev - ``` +```shell +mim download mmcls --config resnet50_8xb32_in1k --dest . +``` - *我需要做这一步吗？* `dev` 分支是开发中的分支，包含了一些试验性的功能。如果你需要这些功能，或者准备参与 MMClassification 开发，那么需要做这一步。 +**第 2 步** 验证示例的推理流程 -2. 安装依赖包和 MMClassification +如果你是**从源码安装**的 mmcls，那么直接运行以下命令进行验证： - 使用 MIM，MIM 会自动安装适合你环境的 mmcv-full。 +```shell +python demo/image_demo.py demo/demo.JPEG resnet50_8xb32_in1k.py resnet50_8xb32_in1k_20210831-ea4938fc.pth --device cpu +``` + +你可以看到命令行中输出了结果字典，包括 `pred_label`，`pred_score` 和 `pred_class` 三个字段。另外如果你拥有图形 +界面（而不是使用远程终端），那么可以启用 `--show` 选项，将示例图像和对应的预测结果在窗口中进行显示。 + +如果你是**作为 PyThon 包安装**，那么可以打开你的 Python 解释器，并粘贴如下代码： + +```python +from mmcls.apis import init_model, inference_model + +config_file = 'resnet50_8xb32_in1k.py' +checkpoint_file = 'resnet50_8xb32_in1k_20210831-ea4938fc.pth' +model = init_model(config_file, checkpoint_file, device='cpu') # 或者 device='cuda:0' +inference_model(model, 'demo/demo.JPEG') +``` - ```shell - mim install -e . - ``` +你会看到输出一个字典，包含预测的标签、得分及类别名。 - 或者使用 pip，如果你希望使用 mmcv-full，你需要提前手动安装。 +## 自定义安装 - ```shell - pip install -e . - ``` +### CUDA 版本 -## 利用 Docker 镜像安装 MMClassification +安装 PyTorch 时，需要指定 CUDA 版本。如果您不清楚选择哪个，请遵循我们的建议： -MMClassification 提供 [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) ，可以通过以下命令创建 docker 镜像。 +- 对于 Ampere 架构的 NVIDIA GPU，例如 GeForce 30 series 以及 NVIDIA A100，CUDA 11 是必需的。 +- 对于更早的 NVIDIA GPU，CUDA 11 是向前兼容的，但 CUDA 10.2 能够提供更好的兼容性，也更加轻量。 + +请确保你的 GPU 驱动版本满足最低的版本需求，参阅[这张表](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions)。 + +```{note} +如果按照我们的最佳实践进行安装，CUDA 运行时库就足够了，因为我们提供相关 CUDA 代码的预编译，你不需要进行本地编译。 +但如果你希望从源码进行 MMCV 的编译，或是进行其他 CUDA 算子的开发，那么就必须安装完整的 CUDA 工具链，参见 +[NVIDIA 官网](https://developer.nvidia.com/cuda-downloads)，另外还需要确保该 CUDA 工具链的版本与 PyTorch 安装时 +的配置相匹配（如用 `conda install` 安装 PyTorch 时指定的 cudatoolkit 版本）。 +``` + +### 不使用 MIM 安装 MMCV + +MMCV 包含 C++ 和 CUDA 扩展，因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些 +依赖，选择合适的 MMCV 预编译包，使安装更简单，但它并不是必需的。 + +要使用 pip 而不是 MIM 来安装 MMCV，请遵照 [MMCV 安装指南](https://mmcv.readthedocs.io/zh_CN/latest/get_started/installation.html)。 +它需要你用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。 + +举个例子，如下命令将会安装基于 PyTorch 1.10.x 和 CUDA 11.3 编译的 mmcv-full。 ```shell -# 创建基于 PyTorch 1.8.1, CUDA 10.2, CUDNN 7 以及最近版本的 MMCV-full 的镜像 。 -docker build -f ./docker/Dockerfile --rm -t mmcls:latest . +pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html ``` -```{important} -请确保已经安装了 [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker). +### 在 CPU 环境中安装 + +MMClassification 可以仅在 CPU 环境中安装，在 CPU 模式下，你可以完成训练（需要 MMCV 版本 >= 1.4.4）、测试和模型推理等所有操作。 + +在 CPU 模式下，MMCV 的部分功能将不可用，通常是一些 GPU 编译的算子。不过不用担心， +MMClassification 中几乎所有的模型都不会依赖这些算子。 + +### 在 Google Colab 中安装 + +[Google Colab](https://research.google.com/) 通常已经包含了 PyTorch 环境，因此我们只需要安装 MMCV 和 MMClassification 即可，命令如下： + +**第 1 步** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMCV](https://github.com/open-mmlab/mmcv) + +```shell +!pip3 install openmim +!mim install mmcv-full ``` -运行一个基于上述镜像的容器： +**第 2 步** 从源码安装 MMClassification ```shell -docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/workspace/mmclassification/data mmcls:latest /bin/bash +!git clone https://github.com/open-mmlab/mmclassification.git +%cd mmclassification +!pip install -e . ``` -## 在多个 MMClassification 版本下进行开发 +**第 3 步** 验证 + +```python +import mmcls +print(mmcls.__version__) +# 预期输出： 0.23.0 或更新的版本号 +``` + +```{note} +在 Jupyter 中，感叹号 `!` 用于执行外部命令，而 `%cd` 是一个[魔术命令](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd)，用于切换 Python 的工作路径。 +``` -MMClassification 的训练和测试脚本已经修改了 `PYTHONPATH` 变量，以确保其能够运行当前目录下的 MMClassification。 +### 通过 Docker 使用 MMClassification -如果想要运行环境下默认的 MMClassification，用户需要在训练和测试脚本中去除这一行： +MMClassification 提供 [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) +用于构建镜像。请确保你的 [Docker 版本](https://docs.docker.com/engine/install/) >=19.03。 ```shell -PYTHONPATH="$(dirname $0)/..":$PYTHONPATH +# 构建默认的 PyTorch 1.8.1，CUDA 10.2 版本镜像 +# 如果你希望使用其他版本，请修改 Dockerfile +docker build -t mmclassification docker/ ``` + +用以下命令运行 Docker 镜像： + +```shell +docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmclassification/data mmclassification +``` + +## 故障解决 + +如果你在安装过程中遇到了什么问题，请先查阅[常见问题](faq.md)。如果没有找到解决方法，可以在 GitHub +上[提出 issue](https://github.com/open-mmlab/mmclassification/issues/new/choose)。 diff --git a/docs/zh_CN/tutorials/new_dataset.md b/docs/zh_CN/tutorials/new_dataset.md index 52123240b9f..8d5a6ef0e55 100644 --- a/docs/zh_CN/tutorials/new_dataset.md +++ b/docs/zh_CN/tutorials/new_dataset.md @@ -1,44 +1,128 @@ -# 教程 3：如何添加新数据集 +# 教程 3：如何自定义数据集 -## 通过重新组织数据来自定义数据集 +我们支持许多常用的图像分类领域公开数据集，你可以在 +[此页面](https://mmclassification.readthedocs.io/zh_CN/master/api/datasets.html)中找到它们。 -### 将数据集重新组织为已有格式 - -最简单的方法是将数据集转换为现有的数据集格式 (ImageNet)。 +在本节中，我们将介绍如何[使用自己的数据集](#使用自己的数据集)以及如何[使用数据集包装](#使用数据集包装)。 -为了训练，根据图片的类别，存放至不同子目录下。训练数据文件夹结构如下所示： +## 使用自己的数据集 -``` -imagenet -├── ... -├── train -│ ├── n01440764 -│ │ ├── n01440764_10026.JPEG -│ │ ├── n01440764_10027.JPEG -│ │ ├── ... -│ ├── ... -│ ├── n15075141 -│ │ ├── n15075141_999.JPEG -│ │ ├── n15075141_9993.JPEG -│ │ ├── ... -``` +### 将数据集重新组织为已有格式 -为了验证，我们提供了一个注释列表。列表的每一行都包含一个文件名及其相应的真实标签。格式如下： +想要使用自己的数据集，最简单的方法就是将数据集转换为现有的数据集格式。 + +对于多分类任务，我们推荐使用 [`CustomDataset`](https://mmclassification.readthedocs.io/zh_CN/master/api/datasets.html#mmcls.datasets.CustomDataset) 格式。 + +`CustomDataset` 支持两种类型的数据格式： + +1. 提供一个标注文件，其中每一行表示一张样本图片。 + + 样本图片可以以任意的结构进行组织，比如： + + ``` + train/ + ├── folder_1 + │ ├── xxx.png + │ ├── xxy.png + │ └── ... + ├── 123.png + ├── nsdf3.png + └── ... + ``` + + 而标注文件则记录了所有样本图片的文件路径以及相应的类别序号。其中第一列表示图像 + 相对于主目录（本例中为 `train` 目录）的路径，第二列表示类别序号： + + ``` + folder_1/xxx.png 0 + folder_1/xxy.png 1 + 123.png 1 + nsdf3.png 2 + ... + ``` + + ```{note} + 类别序号的值应当属于 `[0, num_classes - 1]` 范围。 + ``` + +2. 将所有样本文件按如下结构进行组织： + + ``` + train/ + ├── cat + │ ├── xxx.png + │ ├── xxy.png + │ └── ... + │ └── xxz.png + ├── bird + │ ├── bird1.png + │ ├── bird2.png + │ └── ... + └── dog + ├── 123.png + ├── nsdf3.png + ├── ... + └── asd932_.png + ``` + + 这种情况下，你不需要提供标注文件，所有位于 `cat` 目录下的图片文件都会被视为 `cat` 类别的样本。 + +通常而言，我们会将整个数据集分为三个子数据集：`train`，`val` 和 `test`，分别用于训练、验证和测试。**每一个**子 +数据集都需要被组织成如上的一种结构。 + +举个例子，完整的数据集结构如下所示（使用第一种组织结构）： ``` -ILSVRC2012_val_00000001.JPEG 65 -ILSVRC2012_val_00000002.JPEG 970 -ILSVRC2012_val_00000003.JPEG 230 -ILSVRC2012_val_00000004.JPEG 809 -ILSVRC2012_val_00000005.JPEG 516 +mmclassification +└── data + └── my_dataset + ├── meta + │ ├── train.txt + │ ├── val.txt + │ └── test.txt + ├── train + ├── val + └── test ``` -注：真实标签的值应该位于 `[0, 类别数目 - 1]` 之间 +之后在你的配置文件中，可以修改其中的 `data` 字段为如下格式： -### 自定义数据集的示例 +```python +... +dataset_type = 'CustomDataset' +classes = ['cat', 'bird', 'dog'] # 数据集中各类别的名称 + +data = dict( + train=dict( + type=dataset_type, + data_prefix='data/my_dataset/train', + ann_file='data/my_dataset/meta/train.txt', + classes=classes, + pipeline=train_pipeline + ), + val=dict( + type=dataset_type, + data_prefix='data/my_dataset/val', + ann_file='data/my_dataset/meta/val.txt', + classes=classes, + pipeline=test_pipeline + ), + test=dict( + type=dataset_type, + data_prefix='data/my_dataset/test', + ann_file='data/my_dataset/meta/test.txt', + classes=classes, + pipeline=test_pipeline + ) +) +... +``` -用户可以编写一个继承自 `BasesDataset` 的新数据集类，并重载 `load_annotations(self)` 方法，类似 [CIFAR10](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/cifar.py) 和 [ImageNet](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/imagenet.py)。 +### 创建一个新的数据集类 +用户可以编写一个继承自 `BasesDataset` 的新数据集类，并重载 `load_annotations(self)` 方法， +类似 [CIFAR10](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/cifar.py) +和 [ImageNet](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/datasets/imagenet.py)。 通常，此方法返回一个包含所有样本的列表，其中的每个样本都是一个字典。字典中包含了必要的数据信息，例如 `img` 和 `gt_label`。 @@ -99,16 +183,17 @@ train = dict( ) ``` -## 通过混合数据集来自定义数据集 +## 使用数据集包装 -MMClassification 还支持混合数据集以进行训练。目前支持合并和重复数据集。 +数据集包装是一种可以改变数据集类行为的类，比如将数据集中的样本进行重复，或是将不同类别的数据进行再平衡。 ### 重复数据集 我们使用 `RepeatDataset` 作为一个重复数据集的封装。举个例子，假设原始数据集是 `Dataset_A`，为了重复它，我们需要如下的配置文件： ```python -dataset_A_train = dict( +data = dict( + train=dict( type='RepeatDataset', times=N, dataset=dict( # 这里是 Dataset_A 的原始配置 @@ -117,6 +202,8 @@ dataset_A_train = dict( pipeline=train_pipeline ) ) + ... +) ``` ### 类别平衡数据集 @@ -126,7 +213,8 @@ dataset_A_train = dict( 举个例子，按照 `oversample_thr=1e-3` 对 `Dataset_A` 进行重复采样，需要如下的配置文件： ```python -dataset_A_train = dict( +data = dict( + train = dict( type='ClassBalancedDataset', oversample_thr=1e-3, dataset=dict( # 这里是 Dataset_A 的原始配置 @@ -135,6 +223,8 @@ dataset_A_train = dict( pipeline=train_pipeline ) ) + ... +) ``` -更加具体的细节，请参考 [源代码](https://github.com/open-mmlab/mmclassification/tree/master/mmcls/datasets/dataset_wrappers.py)。 +更加具体的细节，请参考 [API 文档](https://mmclassification.readthedocs.io/zh_CN/master/api/datasets.html#mmcls.datasets.ClassBalancedDataset)。 diff --git a/mmcls/models/backbones/densenet.py b/mmcls/models/backbones/densenet.py index cb2002e4bc2..9947fbf5d86 100644 --- a/mmcls/models/backbones/densenet.py +++ b/mmcls/models/backbones/densenet.py @@ -162,7 +162,7 @@ class DenseNet(BaseBackbone): should include the following two keys: - growth_rate (int): Each layer of DenseBlock produce `k` feature - maps. Here refers `k` as the growth rate of the network. + maps. Here refers `k` as the growth rate of the network. - depths (list[int]): Number of repeated layers in each DenseBlock. - init_channels (int): The output channels of stem layers. diff --git a/mmcls/models/backbones/van.py b/mmcls/models/backbones/van.py index 4022cc0d20b..1be52b68716 100644 --- a/mmcls/models/backbones/van.py +++ b/mmcls/models/backbones/van.py @@ -270,7 +270,7 @@ class VAN(BaseBackbone): - **embed_dims** (List[int]): The dimensions of embedding. - **depths** (List[int]): The number of blocks in each stage. - **ffn_ratios** (List[int]): The number of expansion ratio of - feedforward network hidden layer channels. + feedforward network hidden layer channels. Defaults to 'tiny'. patch_sizes (List[int | tuple]): The patch size in patch embeddings.