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

[Docs] Update install tutorials. (#854) 

* [Docs] Update install tutorials.

* [Docs] Improve dataset docs

* Add option to show the results in demo.

* fix typo
pull/863/head
Ma Zerun 2022-06-01 18:31:57 +08:00 committed by GitHub
parent 877ea3080a
commit 3e198e63e8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 829 additions and 376 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
demo/image_demo.py
View File

@ -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__':

82
docs/en/faq.md 100644
View File

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

4
docs/en/index.rst
View File

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

352
docs/en/install.md
View File

@ -1,173 +1,219 @@
# Installation
# Prerequisites
## Requirements
In this section we demonstrate how to prepare an environment with PyTorch.
- 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.
```
## Install Dependencies
**Step 1.** Download and install Miniconda from the [official website](https://docs.conda.io/en/latest/miniconda.html).
1. Create a conda virtual environment and activate it.
```shell
conda create -n open-mmlab python=3.8 -y
conda activate open-mmlab
```
2. Install PyTorch and torchvision following the [official instructions](https://pytorch.org/), e.g.,
```shell
conda install pytorch torchvision -c pytorch
```
```{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/).
```
*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.
```shell
conda install pytorch==1.5.1 torchvision==0.6.1 cudatoolkit=10.1 -c pytorch
```
*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.
```shell
conda install pytorch==1.10.1 torchvision==0.11.2 cudatoolkit=11.3 -c pytorch
```
If you build PyTorch from source instead of installing the prebuilt package,
you can use more CUDA versions such as 9.0.
3. Install MMCV
MMCV is a foundational library for MMClassification. And there are two versions of MMCV.
- **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.
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).
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.
```shell
pip install openmim
```
## Install MMClassification repository
According to your needs, we support two install modes.
- [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.
### Use as a Python package
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.
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.
### Develop based on MMClassification
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).
1. Clone the MMClassification repository.
```shell
git clone https://github.com/open-mmlab/mmclassification.git
cd mmclassification
```
2. [Optional] Checkout to the `dev` branch.
```shell
git checkout dev
```
*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.
3. Install requirements and MMClassification.
Use MIM, and MIM will automatically install the mmcv-full which fits your environment.
```shell
mim install -e .
```
Or use pip, and if you want to use mmcv-full, you need to install it manually in advance.
```shell
pip install -e .
```
## Another option: Docker Image
We provide a [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) to build an image.
**Step 2.** Create a conda environment and activate it.
```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 .
conda create --name openmmlab python=3.8 -y
conda activate openmmlab
```
```{important}
Make sure you've installed the [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker).
```
**Step 3.** Install PyTorch following [official instructions](https://pytorch.org/get-started/locally/), e.g.
Run a container built from mmcls image with command:
On GPU platforms:
```shell
docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/workspace/mmclassification/data mmcls:latest /bin/bash
conda install pytorch torchvision -c pytorch
```
## Using multiple MMClassification versions
```{warning}
This command will automatically install the latest version PyTorch and cudatoolkit, please check whether they matches your environment.
```
The train and test scripts already modify the `PYTHONPATH` to ensure the script use the MMClassification in the current directory.
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
On CPU platforms:
```shell
PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
conda install pytorch torchvision cpuonly -c pytorch
```
# Installation
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.
## Best Practices
**Step 0.** Install [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim).
```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
```
### Install as a Python package
Just install with pip.
```shell
pip install mmcls
```
## Verify the installation
To verify whether MMClassification is installed correctly, we provide some sample codes to run an inference demo.
**Step 1.** We need to download config and checkpoint files.
```shell
mim download mmcls --config resnet50_8xb32_in1k --dest .
```
**Step 2.** Verify the inference demo.
Option (a). If you install mmcls from source, just run the following command:
```shell
python demo/image_demo.py demo/demo.JPEG resnet50_8xb32_in1k.py resnet50_8xb32_in1k_20210831-ea4938fc.pth --device cpu
```
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.
Option (b). If you install mmcls as a python package, open you python interpreter and copy&paste the following codes.
```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') # or device='cuda:0'
inference_model(model, 'demo/demo.JPEG')
```
You will see a dict printed, including the predicted label, score and category name.
## Customize Installation
### CUDA versions
When installing PyTorch, you need to specify the version of CUDA. If you are
not clear on which to choose, follow our recommendations:
- 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.
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.
```{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.
```
### Install MMCV without MIM
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.
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.
For example, the following command install mmcv-full built for PyTorch 1.10.x and CUDA 11.3.
```shell
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
```
### 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
```
**Step 2.** Install MMClassification from the source.
```shell
!git clone https://github.com/open-mmlab/mmclassification.git
%cd mmclassification
!pip install -e .
```
**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.
```
### Using MMClassification with Docker
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
# 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.

180
docs/en/tutorials/new_dataset.md
View File

@ -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).
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
### Reorganize dataset to existing format
The simplest way is to convert your dataset to existing dataset formats (ImageNet).
The simplest way to use your own dataset is to convert it to existing dataset formats.
For training, it differentiates classes by folders. The directory of training data is as follows:
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.

7
docs/zh_CN/compatibility.md 100644
View File

@ -0,0 +1,7 @@
# 0.x 相关兼容性问题
## MMClassification 0.20.1
### MMCV 兼容性
在 Twins 骨干网络中，我们使用了 MMCV 提供的 `PatchEmbed` 模块，该模块是在 MMCV 1.4.2 版本加入的，因此我们需要将 MMCV 依赖版本升至 1.4.2。

72
docs/zh_CN/faq.md 100644
View File

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

4
docs/zh_CN/index.rst
View File

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

334
docs/zh_CN/install.md
View File

@ -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 虚拟环境，并激活
```shell
conda create -n open-mmlab python=3.8 -y
conda activate open-mmlab
```
2. 按照 [官方指南](https://pytorch.org/) 安装 PyTorch 和 TorchVision，如：
```shell
conda install pytorch torchvision -c pytorch
```
```{note}
请确保 CUDA 编译版本和运行版本相匹配。
可以参照 [PyTorch 官网](https://pytorch.org/) 对预编译包所支持的 CUDA 版本进行核对。
```
*例 1*：如果你已经安装了 CUDA 10.1 版本，并且想要安装 PyTorch 1.5.1 版本，
则需要安装 CUDA 10.1 下预编译的 PyTorch。
```shell
conda install pytorch==1.5.1 torchvision==0.6.1 cudatoolkit=10.1 -c pytorch
```
*例 2*：如果你已经安装了 CUDA 11.3 版本，并且想要安装 PyTorch 1.10.1 版本，
则需要安装 CUDA 11.3 下预编译的 PyTorch。
```shell
conda install pytorch==1.10.1 torchvision==0.11.2 cudatoolkit=11.3 -c pytorch
```
如果 PyTorch 是由源码进行编译安装（而非直接下载预编译好的安装包），则可以使用更多的 CUDA 版本（如 9.0 版本）。
3. 安装 MMCV
MMCV 是 MMClassification 的基础库。它有两个版本：
- **mmcv**：精简版，不包含 CUDA 算子但包含其余所有特性和功能，类似 MMCV 1.0 之前的版本。如果你不需要使用 CUDA 算子的话，精简版可以作为一个考虑选项。
- **mmcv-full**：完整版，包含所有的特性以及丰富的开箱即用的 CUDA 算子。注意完整版本可能需要更长时间来编译。
如果你希望安装 mmcv-full，你可以根据 [该教程](https://mmcv.readthedocs.io/en/latest/get_started/installation.html) 完成安装或编译。
一个更好的选择是使用 [MIM](https://github.com/open-mmlab/mim) 来自动选择适合你的 mmcv-full 版本。在使用 MIM 安装 MMClassification 的时候，它就会自动完成 mmcv-full 的安装。
```shell
pip install openmim
```
## 安装 MMClassification 库
根据你的需求，我们支持两种安装模式。
- [仅作为 Python 包使用](#仅作为-python-包使用)：该模式下，你只希望在你的项目中调用 MMClassification 的 API，或者导入 MMClassification 中的模块
- [基于 MMClassification 进行开发（推荐）](#基于-mmclassification-进行开发)：该模式下，你希望基于 MMClassification 框架开发你自己的图像分类任务，需要添加新的功能，比如新的模型或是数据集。并且你可以使用我们提供的所有工具。
### 仅作为 Python 包使用
如果你已经安装了 MIM，那么只需要使用 `mim install mmcls` 命令来安装 MMClassification。MIM 将会根据你的环境选择安装合适的 mmcv-full 版本。另外，MIM 还提供了一系列其他功能来协助进行训练、参数搜索及模型筛选等。
或者，你可以直接通过 pip 来安装，使用 `pip install mmcls` 命令。这种情况下，如果你希望使用 mmcv-full，那么需要提前手动安装 mmcv-full。
### 基于 MMClassification 进行开发
在该模式下，任何本地修改都会直接生效，不需要重新安装（除非提交了一些 commit，并且希望提升版本号）。
1. 克隆最新的 MMClassification 仓库
```shell
git clone https://github.com/open-mmlab/mmclassification.git
cd mmclassification
```
2. 【可选】 签出到 `dev` 分支
```shell
git checkout dev
```
*我需要做这一步吗？* `dev` 分支是开发中的分支，包含了一些试验性的功能。如果你需要这些功能，或者准备参与 MMClassification 开发，那么需要做这一步。
2. 安装依赖包和 MMClassification
使用 MIM，MIM 会自动安装适合你环境的 mmcv-full。
```shell
mim install -e .
```
或者使用 pip，如果你希望使用 mmcv-full，你需要提前手动安装。
```shell
pip install -e .
```
## 利用 Docker 镜像安装 MMClassification
MMClassification 提供 [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile) ，可以通过以下命令创建 docker 镜像。
**第 2 步** 创建一个 conda 虚拟环境并激活它。
```shell
# 创建基于 PyTorch 1.8.1, CUDA 10.2, CUDNN 7 以及最近版本的 MMCV-full 的镜像 。
docker build -f ./docker/Dockerfile --rm -t mmcls:latest .
conda create --name openmmlab python=3.8 -y
conda activate openmmlab
```
```{important}
请确保已经安装了 [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker).
```
**第 3 步** 按照[官方指南](https://pytorch.org/get-started/locally/)安装 PyTorch。例如：
运行一个基于上述镜像的容器：
在 GPU 平台：
```shell
docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/workspace/mmclassification/data mmcls:latest /bin/bash
conda install pytorch torchvision -c pytorch
```
## 在多个 MMClassification 版本下进行开发
```{warning}
以上命令会自动安装最新版的 PyTorch 与对应的 cudatoolkit，请检查它们是否与你的环境匹配。
```
MMClassification 的训练和测试脚本已经修改了 `PYTHONPATH` 变量，以确保其能够运行当前目录下的 MMClassification。
如果想要运行环境下默认的 MMClassification，用户需要在训练和测试脚本中去除这一行：
在 CPU 平台：
```shell
PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
conda install pytorch torchvision cpuonly -c pytorch
```
# 安装
我们推荐用户按照我们的最佳实践来安装 MMClassification。但除此之外，如果你想根据
你的习惯完成安装流程，也可以参见[自定义安装](#自定义安装)一节来获取更多信息。
## 最佳实践
**第 1 步** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMCV](https://github.com/open-mmlab/mmcv)
```shell
pip install -U openmim
mim install mmcv-full
```
**第 2 步** 安装 MMClassification
根据具体需求，我们支持两种安装模式：
- [从源码安装（推荐）](#从源码安装)：希望基于 MMClassification 框架开发自己的图像分类任务，需要添加新的功能，比如新的模型或是数据集，或者使用我们提供的各种工具。
- [作为 Python 包安装](#作为-python-包安装)：只是希望调用 MMClassification 的 API 接口，或者在自己的项目中导入 MMClassification 中的模块。
### 从源码安装
这种情况下，从源码按如下方式安装 mmcls：
```shell
git clone https://github.com/open-mmlab/mmclassification.git
cd mmclassification
pip install -v -e .
# "-v" 表示输出更多安装相关的信息
# "-e" 表示以可编辑形式安装，这样可以在不重新安装的情况下，让本地修改直接生效
```
另外，如果你希望向 MMClassification 贡献代码，或者使用试验中的功能，请签出到 `dev` 分支。
```shell
git checkout dev
```
### 作为 Python 包安装
直接使用 pip 安装即可。
```shell
pip install mmcls
```
## 验证安装
为了验证 MMClassification 的安装是否正确，我们提供了一些示例代码来执行模型推理。
**第 1 步** 我们需要下载配置文件和模型权重文件
```shell
mim download mmcls --config resnet50_8xb32_in1k --dest .
```
**第 2 步** 验证示例的推理流程
如果你是**从源码安装**的 mmcls，那么直接运行以下命令进行验证：
```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')
```
你会看到输出一个字典，包含预测的标签、得分及类别名。
## 自定义安装
### CUDA 版本
安装 PyTorch 时，需要指定 CUDA 版本。如果您不清楚选择哪个，请遵循我们的建议：
- 对于 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
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
```
### 在 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
!git clone https://github.com/open-mmlab/mmclassification.git
%cd mmclassification
!pip install -e .
```
**第 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 的工作路径。
```
### 通过 Docker 使用 MMClassification
MMClassification 提供 [Dockerfile](https://github.com/open-mmlab/mmclassification/blob/master/docker/Dockerfile)
用于构建镜像。请确保你的 [Docker 版本](https://docs.docker.com/engine/install/) >=19.03。
```shell
# 构建默认的 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)。

156
docs/zh_CN/tutorials/new_dataset.md
View File

@ -1,44 +1,128 @@
# 教程 3：如何添加新数据集
# 教程 3：如何自定义数据集
## 通过重新组织数据来自定义数据集
我们支持许多常用的图像分类领域公开数据集，你可以在
[此页面](https://mmclassification.readthedocs.io/zh_CN/master/api/datasets.html)中找到它们。
在本节中，我们将介绍如何[使用自己的数据集](#使用自己的数据集)以及如何[使用数据集包装](#使用数据集包装)。
## 使用自己的数据集
### 将数据集重新组织为已有格式
最简单的方法是将数据集转换为现有的数据集格式 (ImageNet)。
想要使用自己的数据集，最简单的方法就是将数据集转换为现有的数据集格式。
为了训练，根据图片的类别，存放至不同子目录下。训练数据文件夹结构如下所示：
对于多分类任务，我们推荐使用 [`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`，分别用于训练、验证和测试。**每一个**子
数据集都需要被组织成如上的一种结构。
举个例子，完整的数据集结构如下所示（使用第一种组织结构）：
```
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
```
为了验证，我们提供了一个注释列表。列表的每一行都包含一个文件名及其相应的真实标签。格式如下：
之后在你的配置文件中，可以修改其中的 `data` 字段为如下格式：
```
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'] # 数据集中各类别的名称
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
)
)
...
```
注：真实标签的值应该位于 `[0, 类别数目 - 1]` 之间
### 自定义数据集的示例
用户可以编写一个继承自 `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)。

2
mmcls/models/backbones/densenet.py
View File

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

2
mmcls/models/backbones/van.py
View File

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