diff --git a/docs/en/conf.py b/docs/en/conf.py index 588a7816..76b99303 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -129,7 +129,7 @@ html_theme_options = { # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] html_css_files = ['css/readthedocs.css'] -# html_js_files = ['js/custom.js'] +html_js_files = ['js/custom.js'] # -- Options for HTMLHelp output --------------------------------------------- @@ -236,5 +236,4 @@ def builder_inited_handler(app): def setup(app): - app.add_js_file('./_static/js/custom.js') app.connect('builder-inited', builder_inited_handler) diff --git a/docs/zh_CN/_static/css/readthedocs.css b/docs/zh_CN/_static/css/readthedocs.css index 0df09691..5263f47e 100644 --- a/docs/zh_CN/_static/css/readthedocs.css +++ b/docs/zh_CN/_static/css/readthedocs.css @@ -14,3 +14,7 @@ article.pytorch-article .section :not(dt) > code { background-color: #f3f4f7; border-radius: 5px; } + +table.colwidths-auto td { + width: 50% +} diff --git a/docs/zh_CN/_static/js/custom.js b/docs/zh_CN/_static/js/custom.js new file mode 100644 index 00000000..44a4057d --- /dev/null +++ b/docs/zh_CN/_static/js/custom.js @@ -0,0 +1 @@ +var collapsedSections = ['Model zoo']; diff --git a/docs/zh_CN/api.rst b/docs/zh_CN/api.rst deleted file mode 100644 index cb6666f9..00000000 --- a/docs/zh_CN/api.rst +++ /dev/null @@ -1,68 +0,0 @@ -mmcls.apis -------------- -.. automodule:: mmcls.apis - :members: - -mmcls.core -------------- - -evaluation -^^^^^^^^^^ -.. automodule:: mmcls.core.evaluation - :members: - -mmcls.models ---------------- - -models -^^^^^^ -.. automodule:: mmcls.models - :members: - -classifiers -^^^^^^^^^^^ -.. automodule:: mmcls.models.classifiers - :members: - -backbones -^^^^^^^^^^ -.. automodule:: mmcls.models.backbones - :members: - -heads -^^^^^^^^^^ -.. automodule:: mmcls.models.heads - :members: - -necks -^^^^^^ -.. automodule:: mmcls.models.necks - :members: - -losses -^^^^^^ -.. automodule:: mmcls.models.losses - :members: - -utils -^^^^^^ -.. automodule:: mmcls.models.utils - :members: - -mmcls.datasets ------------------ - -datasets -^^^^^^^^ -.. automodule:: mmcls.datasets - :members: - -pipelines -^^^^^^^^^ -.. automodule:: mmcls.datasets.pipelines - :members: - -mmcls.utils --------------- -.. automodule:: mmcls.utils - :members: diff --git a/docs/zh_CN/api/apis.rst b/docs/zh_CN/api/apis.rst new file mode 100644 index 00000000..67e05b93 --- /dev/null +++ b/docs/zh_CN/api/apis.rst @@ -0,0 +1,45 @@ +.. role:: hidden + :class: hidden-section + +mmcls.apis +=================================== + +These are some high-level APIs for classification tasks. + +.. contents:: mmcls.apis + :depth: 2 + :local: + :backlinks: top + +.. currentmodule:: mmcls.apis + +Train +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + + init_random_seed + set_random_seed + train_model + +Test +------------------ +.. autosummary:: + :toctree: generated + :nosignatures: + + single_gpu_test + multi_gpu_test + +Inference +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + + init_model + inference_model + show_result_pyplot diff --git a/docs/zh_CN/api/core.rst b/docs/zh_CN/api/core.rst new file mode 100644 index 00000000..0f83483c --- /dev/null +++ b/docs/zh_CN/api/core.rst @@ -0,0 +1,61 @@ +.. role:: hidden + :class: hidden-section + +mmcls.core +=================================== + +This package includes some runtime components. These components are useful in +classification tasks but not supported by MMCV yet. + +.. note:: + + Some components may be moved to MMCV in the future. + +.. contents:: mmcls.core + :depth: 2 + :local: + :backlinks: top + +.. currentmodule:: mmcls.core + +Evaluation +------------------ + +Evaluation metrics calculation functions + +.. autosummary:: + :toctree: generated + :nosignatures: + + precision + recall + f1_score + precision_recall_f1 + average_precision + mAP + support + average_performance + calculate_confusion_matrix + +Hook +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + ClassNumCheckHook + PreciseBNHook + CosineAnnealingCooldownLrUpdaterHook + + +Optimizers +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + Lamb diff --git a/docs/zh_CN/api/datasets.rst b/docs/zh_CN/api/datasets.rst new file mode 100644 index 00000000..585f5586 --- /dev/null +++ b/docs/zh_CN/api/datasets.rst @@ -0,0 +1,56 @@ +.. role:: hidden + :class: hidden-section + +mmcls.datasets +=================================== + +The ``datasets`` package contains several usual datasets for image classification tasks and some dataset wrappers. + +.. currentmodule:: mmcls.datasets + +Custom Dataset +-------------- + +.. autoclass:: CustomDataset + +ImageNet +-------- + +.. autoclass:: ImageNet + +.. autoclass:: ImageNet21k + +CIFAR +----- + +.. autoclass:: CIFAR10 + +.. autoclass:: CIFAR100 + +MNIST +----- + +.. autoclass:: MNIST + +.. autoclass:: FashionMNIST + +VOC +--- + +.. autoclass:: VOC + +Base classes +------------ + +.. autoclass:: BaseDataset + +.. autoclass:: MultiLabelDataset + +Dataset Wrappers +---------------- + +.. autoclass:: ConcatDataset + +.. autoclass:: RepeatDataset + +.. autoclass:: ClassBalancedDataset diff --git a/docs/zh_CN/api/models.rst b/docs/zh_CN/api/models.rst new file mode 100644 index 00000000..7b953024 --- /dev/null +++ b/docs/zh_CN/api/models.rst @@ -0,0 +1,137 @@ +.. role:: hidden + :class: hidden-section + +mmcls.models +=================================== + +The ``models`` package contains several sub-packages for addressing the different components of a model. + +- :ref:`classifiers`: The top-level module which defines the whole process of a classification model. +- :ref:`backbones`: Usually a feature extraction network, e.g., ResNet, MobileNet. +- :ref:`necks`: The component between backbones and heads, e.g., GlobalAveragePooling. +- :ref:`heads`: The component for specific tasks. In MMClassification, we provides heads for classification. +- :ref:`losses`: Loss functions. + +.. currentmodule:: mmcls.models + +.. autosummary:: + :toctree: generated + :nosignatures: + + build_classifier + build_backbone + build_neck + build_head + build_loss + +.. _classifiers: + +Classifier +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + BaseClassifier + ImageClassifier + +.. _backbones: + +Backbones +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + AlexNet + CSPDarkNet + CSPNet + CSPResNeXt + CSPResNet + Conformer + ConvMixer + ConvNeXt + DistilledVisionTransformer + EfficientNet + HRNet + LeNet5 + MlpMixer + MobileNetV2 + MobileNetV3 + PCPVT + PoolFormer + RegNet + RepMLPNet + RepVGG + Res2Net + ResNeSt + ResNeXt + ResNet + ResNetV1c + ResNetV1d + ResNet_CIFAR + SEResNeXt + SEResNet + SVT + ShuffleNetV1 + ShuffleNetV2 + SwinTransformer + T2T_ViT + TIMMBackbone + TNT + VGG + VisionTransformer + +.. _necks: + +Necks +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + GlobalAveragePooling + GeneralizedMeanPooling + HRFuseScales + +.. _heads: + +Heads +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + ClsHead + LinearClsHead + StackedLinearClsHead + MultiLabelClsHead + MultiLabelLinearClsHead + VisionTransformerClsHead + DeiTClsHead + ConformerHead + +.. _losses: + +Losses +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + Accuracy + AsymmetricLoss + CrossEntropyLoss + LabelSmoothLoss + FocalLoss + SeesawLoss diff --git a/docs/zh_CN/api/models.utils.augment.rst b/docs/zh_CN/api/models.utils.augment.rst new file mode 100644 index 00000000..54442f71 --- /dev/null +++ b/docs/zh_CN/api/models.utils.augment.rst @@ -0,0 +1,35 @@ +.. role:: hidden + :class: hidden-section + +Batch Augmentation +=================================== + +Batch augmentation is the augmentation which involve multiple samples, such as Mixup and CutMix. + +In MMClassification, these batch augmentation is used as a part of :ref:`classifiers`. A typical usage is as below: + +.. code-block:: python + + model = dict( + backbone = ..., + neck = ..., + head = ..., + train_cfg=dict(augments=[ + dict(type='BatchMixup', alpha=0.8, prob=0.5, num_classes=num_classes), + dict(type='BatchCutMix', alpha=1.0, prob=0.5, num_classes=num_classes), + ])) + ) + +.. currentmodule:: mmcls.models.utils.augment + +Mixup +----- +.. autoclass:: BatchMixupLayer + +CutMix +------ +.. autoclass:: BatchCutMixLayer + +ResizeMix +--------- +.. autoclass:: BatchResizeMixLayer diff --git a/docs/zh_CN/api/models.utils.rst b/docs/zh_CN/api/models.utils.rst new file mode 100644 index 00000000..c9687a72 --- /dev/null +++ b/docs/zh_CN/api/models.utils.rst @@ -0,0 +1,50 @@ +.. role:: hidden + :class: hidden-section + +mmcls.models.utils +=================================== + +This package includes some helper functions and common components used in various networks. + +.. contents:: mmcls.models.utils + :depth: 2 + :local: + :backlinks: top + +.. currentmodule:: mmcls.models.utils + +Common Components +------------------ + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + InvertedResidual + SELayer + ShiftWindowMSA + MultiheadAttention + ConditionalPositionEncoding + +Helper Functions +------------------ + +channel_shuffle +^^^^^^^^^^^^^^^ +.. autofunction:: channel_shuffle + +make_divisible +^^^^^^^^^^^^^^ +.. autofunction:: make_divisible + +to_ntuple +^^^^^^^^^^^^^^ +.. autofunction:: to_ntuple +.. autofunction:: to_2tuple +.. autofunction:: to_3tuple +.. autofunction:: to_4tuple + +is_tracing +^^^^^^^^^^^^^^ +.. autofunction:: is_tracing diff --git a/docs/zh_CN/api/transforms.rst b/docs/zh_CN/api/transforms.rst new file mode 100644 index 00000000..4a39f082 --- /dev/null +++ b/docs/zh_CN/api/transforms.rst @@ -0,0 +1,171 @@ +.. role:: hidden + :class: hidden-section + +Data Transformations +*********************************** + +In MMClassification, the data preparation and the dataset is decomposed. The +datasets only define how to get samples' basic information from the file +system. These basic information includes the ground-truth label and raw images +data / the paths of images. + +To prepare the inputs data, we need to do some transformations on these basic +information. These transformations includes loading, preprocessing and +formatting. And a series of data transformations makes up a data pipeline. +Therefore, you can find the a ``pipeline`` argument in the configs of dataset, +for example: + +.. code:: python + + img_norm_cfg = dict( + mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True) + train_pipeline = [ + dict(type='LoadImageFromFile'), + dict(type='RandomResizedCrop', size=224), + dict(type='RandomFlip', flip_prob=0.5, direction='horizontal'), + dict(type='Normalize', **img_norm_cfg), + dict(type='ImageToTensor', keys=['img']), + dict(type='ToTensor', keys=['gt_label']), + dict(type='Collect', keys=['img', 'gt_label']) + ] + test_pipeline = [ + dict(type='LoadImageFromFile'), + dict(type='Resize', size=256), + dict(type='CenterCrop', crop_size=224), + dict(type='Normalize', **img_norm_cfg), + dict(type='ImageToTensor', keys=['img']), + dict(type='Collect', keys=['img']) + ] + + data = dict( + train=dict(..., pipeline=train_pipeline), + val=dict(..., pipeline=test_pipeline), + test=dict(..., pipeline=test_pipeline), + ) + +Every item of a pipeline list is one of the following data transformations class. And if you want to add a custom data transformation class, the tutorial :doc:`Custom Data Pipelines ` will help you. + +.. contents:: mmcls.datasets.pipelines + :depth: 2 + :local: + :backlinks: top + +.. currentmodule:: mmcls.datasets.pipelines + +Loading +======= + +LoadImageFromFile +--------------------- +.. autoclass:: LoadImageFromFile + +Preprocessing and Augmentation +============================== + +CenterCrop +--------------------- +.. autoclass:: CenterCrop + +Lighting +--------------------- +.. autoclass:: Lighting + +Normalize +--------------------- +.. autoclass:: Normalize + +Pad +--------------------- +.. autoclass:: Pad + +Resize +--------------------- +.. autoclass:: Resize + +RandomCrop +--------------------- +.. autoclass:: RandomCrop + +RandomErasing +--------------------- +.. autoclass:: RandomErasing + +RandomFlip +--------------------- +.. autoclass:: RandomFlip + +RandomGrayscale +--------------------- +.. autoclass:: RandomGrayscale + +RandomResizedCrop +--------------------- +.. autoclass:: RandomResizedCrop + +ColorJitter +--------------------- +.. autoclass:: ColorJitter + + +Composed Augmentation +--------------------- +Composed augmentation is a kind of methods which compose a series of data +augmentation transformations, such as ``AutoAugment`` and ``RandAugment``. + +.. autoclass:: AutoAugment + +.. autoclass:: RandAugment + +In composed augmentation, we need to specify several data transformations or +several groups of data transformations (The ``policies`` argument) as the +random sampling space. These data transformations are chosen from the below +table. In addition, we provide some preset policies in `this folder`_. + +.. _this folder: https://github.com/open-mmlab/mmclassification/tree/master/configs/_base_/datasets/pipelines + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: classtemplate.rst + + AutoContrast + Brightness + ColorTransform + Contrast + Cutout + Equalize + Invert + Posterize + Rotate + Sharpness + Shear + Solarize + SolarizeAdd + Translate + +Formatting +========== + +Collect +--------------------- +.. autoclass:: Collect + +ImageToTensor +--------------------- +.. autoclass:: ImageToTensor + +ToNumpy +--------------------- +.. autoclass:: ToNumpy + +ToPIL +--------------------- +.. autoclass:: ToPIL + +ToTensor +--------------------- +.. autoclass:: ToTensor + +Transpose +--------------------- +.. autoclass:: Transpose diff --git a/docs/zh_CN/api/utils.rst b/docs/zh_CN/api/utils.rst new file mode 100644 index 00000000..206fc82c --- /dev/null +++ b/docs/zh_CN/api/utils.rst @@ -0,0 +1,23 @@ +.. role:: hidden + :class: hidden-section + +mmcls.utils +=================================== + +These are some useful help function in the ``utils`` package. + +.. contents:: mmcls.utils + :depth: 1 + :local: + :backlinks: top + +.. currentmodule:: mmcls.utils + +.. autosummary:: + :toctree: generated + :nosignatures: + + collect_env + get_root_logger + load_json_log + setup_multi_processes diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index b8adbc3e..4a214d87 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -44,6 +44,8 @@ release = get_version() # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx_markdown_tables', @@ -127,6 +129,7 @@ html_theme_options = { # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] html_css_files = ['css/readthedocs.css'] +html_js_files = ['js/custom.js'] # -- Options for HTMLHelp output --------------------------------------------- @@ -204,6 +207,15 @@ StandaloneHTMLBuilder.supported_image_types = [ # Ignore >>> when copying code copybutton_prompt_text = r'>>> |\.\.\. ' copybutton_prompt_is_regexp = True +# Auto-generated header anchors +myst_heading_anchors = 3 +# Configuration for intersphinx +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'numpy': ('https://numpy.org/doc/stable', None), + 'torch': ('https://pytorch.org/docs/stable/', None), + 'mmcv': ('https://mmcv.readthedocs.io/en/master/', None), +} def builder_inited_handler(app): diff --git a/docs/zh_CN/docutils.conf b/docs/zh_CN/docutils.conf new file mode 100644 index 00000000..0c00c846 --- /dev/null +++ b/docs/zh_CN/docutils.conf @@ -0,0 +1,2 @@ +[html writers] +table_style: colwidths-auto diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index 68226e9d..11120da8 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -59,7 +59,14 @@ You can switch between Chinese and English documentation in the lower-left corne .. toctree:: :caption: API 参考文档 - api.rst + mmcls.apis + mmcls.core + mmcls.models + mmcls.models.utils + mmcls.datasets + 数据转换 + 批数据增强 + mmcls.utils .. toctree:: diff --git a/docs/zh_CN/tools/onnx2tensorrt.md b/docs/zh_CN/tools/onnx2tensorrt.md index ad0fd90f..fdcbf139 100644 --- a/docs/zh_CN/tools/onnx2tensorrt.md +++ b/docs/zh_CN/tools/onnx2tensorrt.md @@ -2,13 +2,12 @@ -- [ONNX 转 TensorRT（试验性的）](#onnx-tensorrt) - - [如何将模型从 ONNX 转换到 TensorRT](#id1) - - [准备工作](#id2) - - [使用方法](#id3) - - [支持转换至 TensorRT 的模型列表](#tensorrt) - - [提示](#id4) - - [常见问题](#id5) +- [如何将模型从 ONNX 转换到 TensorRT](#如何将模型从-onnx-转换到-tensorrt) + - [准备工作](#准备工作) + - [使用方法](#使用方法) +- [支持转换至 TensorRT 的模型列表](#支持转换至-tensorrt-的模型列表) +- [提示](#提示) +- [常见问题](#常见问题) diff --git a/docs/zh_CN/tools/pytorch2onnx.md b/docs/zh_CN/tools/pytorch2onnx.md index abe8ff73..c217407e 100644 --- a/docs/zh_CN/tools/pytorch2onnx.md +++ b/docs/zh_CN/tools/pytorch2onnx.md @@ -2,13 +2,12 @@ -- [Pytorch 转 ONNX （试验性的）](#pytorch-onnx) - - [如何将模型从 PyTorch 转换到 ONNX](#id1) - - [准备工作](#id2) - - [使用方法](#id3) - - [支持导出至 ONNX 的模型列表](#onnx) - - [提示](#id4) - - [常见问题](#id5) +- [如何将模型从 PyTorch 转换到 ONNX](#如何将模型从-pytorch-转换到-onnx) + - [准备工作](#准备工作) + - [使用方法](#使用方法) +- [支持导出至 ONNX 的模型列表](#支持导出至-onnx-的模型列表) +- [提示](#提示) +- [常见问题](#常见问题) diff --git a/docs/zh_CN/tools/pytorch2torchscript.md b/docs/zh_CN/tools/pytorch2torchscript.md index 9a48a1b6..02b12e34 100644 --- a/docs/zh_CN/tools/pytorch2torchscript.md +++ b/docs/zh_CN/tools/pytorch2torchscript.md @@ -2,11 +2,10 @@ -- [Pytorch 转 TorchScript （试验性的）](#pytorch-torchscript) - - [如何将 PyTorch 模型转换至 TorchScript](#id1) - - [使用方法](#id2) - - [提示](#id3) - - [常见问题](#id4) +- [如何将 PyTorch 模型转换至 TorchScript](#如何将-pytorch-模型转换至-torchscript) + - [使用方法](#使用方法) +- [提示](#提示) +- [常见问题](#常见问题) diff --git a/docs/zh_CN/tutorials/runtime.md b/docs/zh_CN/tutorials/runtime.md index 71de8c3e..47556c1a 100644 --- a/docs/zh_CN/tutorials/runtime.md +++ b/docs/zh_CN/tutorials/runtime.md @@ -7,14 +7,8 @@ - [定制工作流](#定制工作流) - [钩子](#钩子) - [默认训练钩子](#默认训练钩子) - - [权重文件钩子（CheckpointHook）](#权重文件钩子（checkpointhook）) - - [日志钩子（LoggerHooks）](#日志钩子（loggerhooks）) - - [验证钩子（EvalHook）](#验证钩子（evalhook）) - [使用内置钩子](#使用内置钩子) - [自定义钩子](#自定义钩子) - - [1. 创建一个新钩子](#1.-创建一个新钩子) - - [2. 注册新钩子](#2.-注册新钩子) - - [3. 修改配置](#3.-修改配置) - [常见问题](#常见问题) @@ -183,7 +177,7 @@ custom_hooks = [ ## 自定义钩子 -### 1. 创建一个新钩子 +### 创建一个新钩子 这里举一个在 MMClassification 中创建一个新钩子，并在训练中使用它的示例： @@ -218,7 +212,7 @@ class MyHook(Hook): 根据钩子的功能，用户需要指定钩子在训练的每个阶段将要执行的操作，比如 `before_run`，`after_run`，`before_epoch`，`after_epoch`，`before_iter` 和 `after_iter`。 -### 2. 注册新钩子 +### 注册新钩子 之后，需要导入 `MyHook`。假设该文件在 `mmcls/core/utils/my_hook.py`，有两种办法导入它： @@ -238,7 +232,7 @@ __all__ = ['MyHook'] custom_imports = dict(imports=['mmcls.core.utils.my_hook'], allow_failed_imports=False) ``` -### 3. 修改配置 +### 修改配置 ```python custom_hooks = [ diff --git a/requirements/docs.txt b/requirements/docs.txt index 405668dc..41b221f0 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,6 +1,6 @@ -docutils==0.16.0 +docutils==0.17.1 myst-parser -git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme -sphinx==4.0.2 +-e git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme +sphinx==4.5.0 sphinx-copybutton sphinx_markdown_tables