diff --git a/docs/en/get_started.md b/docs/en/get_started.md index 71504dcc037..334eca569b7 100644 --- a/docs/en/get_started.md +++ b/docs/en/get_started.md @@ -83,7 +83,7 @@ The downloading will take several seconds or more, depending on your network env **Step 2.** Verify the inference demo. -Option (a). If you install MMDetection from source, just run the following command. +Case a: If you install MMDetection from source, just run the following command. ```shell python demo/image_demo.py demo/demo.jpg yolov3_mobilenetv2_8xb24-320-300e_coco.py yolov3_mobilenetv2_320_300e_coco_20210719_215349-d18dff72.pth --device cpu --out-file result.jpg @@ -91,7 +91,7 @@ python demo/image_demo.py demo/demo.jpg yolov3_mobilenetv2_8xb24-320-300e_coco.p You will see a new image `result.jpg` on your current folder, where bounding boxes are plotted on cars, benches, etc. -Option (b). If you install MMDetection with MIM, open your python interpreter and copy&paste the following codes. +Case b: If you install MMDetection with MIM, open your python interpreter and copy&paste the following codes. ```python from mmdet.apis import init_detector, inference_detector @@ -174,7 +174,7 @@ The following table lists affected algorithms. #### Install on Google Colab -[Google Colab](https://research.google.com/) usually has PyTorch installed, +[Google Colab](https://colab.research.google.com/) usually has PyTorch installed, thus we only need to install MMEngine, MMCV, and MMDetection with the following commands. **Step 1.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv) using [MIM](https://github.com/open-mmlab/mim). @@ -182,7 +182,7 @@ thus we only need to install MMEngine, MMCV, and MMDetection with the following ```shell !pip3 install openmim !mim install mmengine -!mim install mmcv>=2.0.0rc1,<2.1.0 +!mim install "mmcv>=2.0.0rc1,<2.1.0" ``` **Step 2.** Install MMDetection from the source. @@ -226,7 +226,7 @@ docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection/data mmdetect If you have some issues during the installation, please first view the [FAQ](notes/faq.md) page. You may [open an issue](https://github.com/open-mmlab/mmdetection/issues/new/choose) on GitHub if no solution is found. -### Use Multiple Versions of MMDetection in Develoement +### Use Multiple Versions of MMDetection in Development Training and testing scripts have already been modified in `PYTHONPATH` in order to make sure the scripts are using their own versions of MMDetection. diff --git a/docs/en/overview.md b/docs/en/overview.md index 54303f741a9..f78b658f017 100644 --- a/docs/en/overview.md +++ b/docs/en/overview.md @@ -13,19 +13,19 @@ MMDetection consists of 7 main parts, apis, structures, datasets, models, engine - **apis** provides high-level APIs for model inference. - **structures** provides data structures like bbox, mask, and DetDataSample. - **datasets** supports various dataset for object detection, instance segmentation, and panoptic segmentation. - - **transforms** contains a lot of useful data augmentation transforms . + - **transforms** contains a lot of useful data augmentation transforms. - **samplers** defines different data loader sampling strategy. - **models** is the most vital part for detectors and contains different components of a detector. - **detectors** defines all of the detection model classes. - **data_preprocessors** is for preprocessing the input data of the model. - - **backbones** contains various backbone networks - - **necks** contains various neck components + - **backbones** contains various backbone networks. + - **necks** contains various neck components. - **dense_heads** contains various detection heads that perform dense predictions. - **roi_heads** contains various detection heads that predict from RoIs. - - **seg_heads** contains various segmentation heads - - **losses** contains various loss functions + - **seg_heads** contains various segmentation heads. + - **losses** contains various loss functions. - **task_modules** provides modules for detection tasks. E.g. assigners, samplers, box coders, and prior generators. - - **layers** provides some basic neural network layers + - **layers** provides some basic neural network layers. - **engine** is a part for runtime components. - **runner** provides extensions for [MMEngine's runner](https://mmengine.readthedocs.io/en/latest/tutorials/runner.html). - **schedulers** provides schedulers for adjusting optimization hyperparameters. diff --git a/docs/zh_cn/get_started.md b/docs/zh_cn/get_started.md index 3c7481da148..611cd3e5dc6 100644 --- a/docs/zh_cn/get_started.md +++ b/docs/zh_cn/get_started.md @@ -4,22 +4,22 @@ 本节中,我们将演示如何用 PyTorch 准备一个环境。 -MMDetection 支持在 Linux,Windows 和 macOS 上运行。它需要 Python 3.6 以上,CUDA 9.2 以上和 PyTorch 1.6 以上. +MMDetection 支持在 Linux,Windows 和 macOS 上运行。它需要 Python 3.6 以上,CUDA 9.2 以上和 PyTorch 1.6 以上。 ```{note} -如果你对 PyTorch 有经验并且已经安装了它,你可以直接跳转到[下一小节](#安装流程)。否则,你可以按照下述步骤进行准备 +如果你对 PyTorch 有经验并且已经安装了它,你可以直接跳转到[下一小节](#安装流程)。否则,你可以按照下述步骤进行准备。 ``` -**步骤 0.** 从 [官方网站](https://docs.conda.io/en/latest/miniconda.html) 下载并安装 Miniconda。 +**步骤 0.** 从[官方网站](https://docs.conda.io/en/latest/miniconda.html)下载并安装 Miniconda。 **步骤 1.** 创建并激活一个 conda 环境。 ```shell -conda create -n open-mmlab python=3.7 -y -conda activate open-mmlab +conda create --name openmmlab python=3.8 -y +conda activate openmmlab ``` -**步骤 2.** 基于 [PyTorch 官方说明](https://pytorch.org/get-started/locally/) 安装 PyTorch。 +**步骤 2.** 基于 [PyTorch 官方说明](https://pytorch.org/get-started/locally/)安装 PyTorch。 在 GPU 平台上: @@ -27,7 +27,7 @@ conda activate open-mmlab conda install pytorch torchvision -c pytorch ``` -在 CPU 平台上: +在 CPU 平台上: ```shell conda install pytorch torchvision cpuonly -c pytorch @@ -35,9 +35,11 @@ conda install pytorch torchvision cpuonly -c pytorch ## 安装流程 +我们推荐用户参照我们的最佳实践安装 MMDetection。不过,整个过程也是可定制化的,更多信息请参考[自定义安装](#自定义安装)章节。 + ### 最佳实践 -**步骤 0.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv) 。 +**步骤 0.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)。 ```shell pip install -U openmim @@ -45,11 +47,11 @@ mim install mmengine mim install "mmcv>=2.0.0rc1" ``` -**注意:** 在 MMCV-v2.x 中,`mmcv-full` 改名为 `mmcv`,如果你想安装不包含 CUDA 算子精简版,可以通过 `mim install mmcv-lite>=2.0.0rc1` 来安装。 +**注意:** 在 MMCV-v2.x 中,`mmcv-full` 改名为 `mmcv`,如果你想安装不包含 CUDA 算子精简版,可以通过 `mim install "mmcv-lite>=2.0.0rc1"` 来安装。 -**步骤 1.** 安装 MMDetection +**步骤 1.** 安装 MMDetection。 -方案 1. 如果你基于 MMDetection 框架开发自己的任务,建议从源码安装 +方案 a:如果你开发并直接运行 mmdet,从源码安装它: ```shell git clone https://github.com/open-mmlab/mmdetection.git -b 3.x @@ -60,7 +62,7 @@ pip install -v -e . # "-e" 表示在可编辑模式下安装项目,因此对代码所做的任何本地修改都会生效,从而无需重新安装。 ``` -方案 2. 如果你将 mmdet 作为依赖或第三方 Python 包,使用 MIM 安装 +方案 b:如果你将 mmdet 作为依赖或第三方 Python 包,使用 MIM 安装: ```shell mim install "mmdet>=3.0.0rc0" @@ -76,11 +78,11 @@ mim install "mmdet>=3.0.0rc0" mim download mmdet --config yolov3_mobilenetv2_8xb24-320-300e_coco --dest . ``` -载将需要几秒钟或更长时间,这取决于你的网络环境。完成后,你会在当前文件夹中发现两个文件 `yolov3_mobilenetv2_8xb24-320-300e_coco.py` and `yolov3_mobilenetv2_320_300e_coco_20210719_215349-d18dff72.pth` +下载将需要几秒钟或更长时间,这取决于你的网络环境。完成后,你会在当前文件夹中发现两个文件 `yolov3_mobilenetv2_8xb24-320-300e_coco.py` 和 `yolov3_mobilenetv2_320_300e_coco_20210719_215349-d18dff72.pth`。 -**步骤 2.** 推理验证 +**步骤 2.** 推理验证。 -方案 1. 如果你通过源码安装的 MMDetection,那么直接运行以下命令进行验证: +方案 a:如果你通过源码安装的 MMDetection,那么直接运行以下命令进行验证: ```shell python demo/image_demo.py demo/demo.jpg yolov3_mobilenetv2_8xb24-320-300e_coco.py yolov3_mobilenetv2_320_300e_coco_20210719_215349-d18dff72.pth --device cpu --out-file result.jpg @@ -88,7 +90,7 @@ python demo/image_demo.py demo/demo.jpg yolov3_mobilenetv2_8xb24-320-300e_coco.p 你会在当前文件夹中看到一个新的图像 `result.jpg`,图像中包含有网络预测的检测框。 -方案 2. 如果你通过 MIM 安装的 MMDetection, 那么可以打开你的 Python 解析器,复制并粘贴以下代码: +方案 b:如果你通过 MIM 安装的 MMDetection,那么可以打开你的 Python 解析器,复制并粘贴以下代码: ```python from mmdet.apis import init_detector, inference_detector @@ -101,31 +103,28 @@ model = init_detector(config_file, checkpoint_file, device='cpu') # or device=' inference_detector(model, 'demo/demo.jpg') ``` -你将会看到一个包含 `DetDataSample` 的列表,预测结果在 `pred_instance` 里,包含有预测框,预测分数和预测类别。 +你将会看到一个包含 `DetDataSample` 的列表,预测结果在 `pred_instance` 里,包含有检测框,类别和得分。 ### 自定义安装 #### CUDA 版本 -在安装 PyTorch 时,你需要指定 CUDA 的版本。如果你不清楚应该选择哪一个,请遵循我们的建议。 +在安装 PyTorch 时,你需要指定 CUDA 的版本。如果你不清楚应该选择哪一个,请遵循我们的建议: -- 对于 Ampere 架构的 NVIDIA GPU,例如 GeForce 30 系列 以及 NVIDIA A100,CUDA 11 是必需的。 +- 对于 Ampere 架构的 NVIDIA GPU,例如 GeForce 30 系列以及 NVIDIA A100,CUDA 11 是必需的。 - 对于更早的 NVIDIA GPU,CUDA 11 是向后兼容 (backward compatible) 的,但 CUDA 10.2 能够提供更好的兼容性,也更加轻量。 -请确保你的 GPU 驱动版本满足最低的版本需求,参阅 NVIDIA 官方的 [CUDA工具箱和相应的驱动版本关系表](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions) 。 +请确保你的 GPU 驱动版本满足最低的版本需求,参阅 NVIDIA 官方的 [CUDA 工具箱和相应的驱动版本关系表](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 版本)。 +如果按照我们的最佳实践,安装 CUDA 运行时库就足够了,这是因为不需要在本地编译 CUDA 代码。但如果你希望从源码编译 MMCV,或是开发其他 CUDA 算子,那么就必须安装完整的 CUDA 工具链,参见 [NVIDIA 官网](https://developer.nvidia.com/cuda-downloads),另外还需要确保该 CUDA 工具链的版本与 PyTorch 安装时的配置相匹配(如用 `conda install` 安装 PyTorch 时指定的 cudatoolkit 版本)。 ``` #### 不使用 MIM 安装 MMEngine -要使用 pip 而不是 MIM 来安装 MMEngine,请遵照 [MMEngine 安装指南](https://mmengine.readthedocs.io/en/latest/get_started/installation.html) 。 +要使用 pip 而不是 MIM 来安装 MMEngine,请遵照 [MMEngine 安装指南](https://mmengine.readthedocs.io/zh_CN/latest/get_started/installation.html)。 -例如,你可以通过以下命令安装 MMEngine +例如,你可以通过以下命令安装 MMEngine。 ```shell pip install mmengine @@ -133,13 +132,11 @@ pip install mmengine #### 不使用 MIM 安装 MMCV -MMCV 包含 C++ 和 CUDA 扩展,因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些 -依赖,选择合适的 MMCV 预编译包,使安装更简单,但它并不是必需的。 +MMCV 包含 C++ 和 CUDA 扩展,因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些依赖,选择合适的 MMCV 预编译包,使安装更简单,但它并不是必需的。 -要使用 pip 而不是 MIM 来安装 MMCV,请遵照 [MMCV 安装指南](https://mmcv.readthedocs.io/zh_CN/2.x/get_started/installation.html) 。 -它需要您用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。 +要使用 pip 而不是 MIM 来安装 MMCV,请遵照 [MMCV 安装指南](https://mmcv.readthedocs.io/zh_CN/2.x/get_started/installation.html)。它需要您用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。 -例如,下述命令将会安装基于 PyTorch 1.12.x 和 CUDA 11.6 编译的 mmcv。 +例如,下述命令将会安装基于 PyTorch 1.12.x 和 CUDA 11.6 编译的 MMCV。 ```shell pip install "mmcv>=2.0.0rc1" -f https://download.openmmlab.com/mmcv/dist/cu116/torch1.12.0/index.html @@ -147,24 +144,24 @@ pip install "mmcv>=2.0.0rc1" -f https://download.openmmlab.com/mmcv/dist/cu116/t #### 在 CPU 环境中安装 -我们的代码能够建立在只使用 CPU 的环境(CUDA 不可用)。 +MMDetection 可以在 CPU 环境中构建。在 CPU 模式下,可以进行模型训练(需要 MMCV 版本 >= 2.0.0rc1)、测试或者推理。 -在 CPU 模式下,可以进行模型训练(需要 MMCV 版本 >= 2.0.0rc1)、测试或者推理,然而以下功能将在 CPU 模式下不能使用: +但是,以下功能在该模式下不能使用: - Deformable Convolution - Modulated Deformable Convolution - ROI pooling - Deformable ROI pooling -- CARAFE: Content-Aware ReAssembly of FEatures +- CARAFE - SyncBatchNorm -- CrissCrossAttention: Criss-Cross Attention +- CrissCrossAttention - MaskedConv2d - Temporal Interlace Shift - nms_cuda - sigmoid_focal_loss_cuda - bbox_overlaps -因此,如果尝试使用包含上述操作的模型进行训练/测试/推理,将会报错。下表列出了由于依赖上述算子而无法在 CPU 上运行的相关模型: +因此,如果尝试训练/测试/推理包含上述算子的模型,将会报错。下表列出了将会受影响的相关算法。 | 操作 | 模型 | | :-----------------------------------------------------: | :--------------------------------------------------------------------------------------: | @@ -175,9 +172,9 @@ pip install "mmcv>=2.0.0rc1" -f https://download.openmmlab.com/mmcv/dist/cu116/t #### 在 Google Colab 中安装 -[Google Colab](https://colab.research.google.com/) 通常已经包含了 PyTorch 环境,因此我们只需要安装 MMEngine, MMCV 和 MMDetection 即可,命令如下: +[Google Colab](https://colab.research.google.com/) 通常已经包含了 PyTorch 环境,因此我们只需要安装 MMEngine,MMCV 和 MMDetection 即可,命令如下: -**步骤 1.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv) 。 +**步骤 1.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)。 ```shell !pip3 install openmim @@ -198,7 +195,7 @@ pip install "mmcv>=2.0.0rc1" -f https://download.openmmlab.com/mmcv/dist/cu116/t ```python import mmdet print(mmdet.__version__) -# 预期输出: 3.0.0rc0 或其他版本号 +# 预期输出:3.0.0rc0 或其他版本号 ``` ```{note} @@ -207,11 +204,11 @@ print(mmdet.__version__) #### 通过 Docker 使用 MMDetection -们提供了一个 [Dockerfile](../../docker/Dockerfile) 来构建一个镜像。请确保你的 [docker版本](https://docs.docker.com/engine/install/) >=19.03。 +我们提供了一个 [Dockerfile](../../docker/Dockerfile) 来构建一个镜像。请确保你的 [docker 版本](https://docs.docker.com/engine/install/) >=19.03。 ```shell -# build an image with PyTorch 1.9, CUDA 11.1 -# If you prefer other versions, just modified the Dockerfile +# 基于 PyTorch 1.9,CUDA 11.1 构建镜像 +# 如果你想要其他版本,只需要修改 Dockerfile docker build -t mmdetection docker/ ``` @@ -223,15 +220,13 @@ docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection/data mmdetect ### 排除故障 -如果你在安装过程中遇到一些问题,请先查看 [FAQ](notes/faq.md) 页面。 - -如果没有找到解决方案,你也可以在 GitHub 上 [打开一个问题](https://github.com/open-mmlab/mmdetection/issues/new/choose) 。 +如果你在安装过程中遇到一些问题,请先查看 [FAQ](notes/faq.md) 页面。如果没有找到解决方案,你也可以在 GitHub 上[提出一个问题](https://github.com/open-mmlab/mmdetection/issues/new/choose)。 ### 使用多个 MMDetection 版本进行开发 -训练和测试的脚本已经在 PYTHONPATH 中进行了修改,以确保脚本使用当前目录中的 MMDetection。 +训练和测试的脚本已经在 `PYTHONPATH` 中进行了修改,以确保脚本使用当前目录中的 MMDetection。 -要使环境中安装默认的 MMDetection 而不是当前正在在使用的,可以删除出现在相关脚本中的代码: +要使环境中安装默认版本的 MMDetection 而不是当前正在使用的,可以删除出现在相关脚本中的代码: ```shell PYTHONPATH="$(dirname $0)/..":$PYTHONPATH diff --git a/docs/zh_cn/overview.md b/docs/zh_cn/overview.md index b60e43c706e..b27ead66357 100644 --- a/docs/zh_cn/overview.md +++ b/docs/zh_cn/overview.md @@ -8,7 +8,7 @@ MMDetection 是一个目标检测工具箱,包含了丰富的目标检测、实例分割、全景分割算法以及相关的组件和模块,下面是它的整体框架: -MMDetection 由 7 个主要部分组成,apis、structures、datasets、models、engine、评估和可视化。 +MMDetection 由 7 个主要部分组成,apis、structures、datasets、models、engine、evaluation 和 visualization。 - **apis** 为模型推理提供高级 API。 - **structures** 提供 bbox、mask 和 DetDataSample 等数据结构。 @@ -18,19 +18,19 @@ MMDetection 由 7 个主要部分组成,apis、structures、datasets、models - **models** 是检测器最重要的部分,包含检测器的不同组件。 - **detectors** 定义所有检测模型类。 - **data_preprocessors** 用于预处理模型的输入数据。 - - **backbones** 包含各种骨干网络 - - **necks** 包含各种模型颈部组件 + - **backbones** 包含各种骨干网络。 + - **necks** 包含各种模型颈部组件。 - **dense_heads** 包含执行密集预测的各种检测头。 - **roi_heads** 包含从 RoI 预测的各种检测头。 - - **seg_heads** 包含各种分割头 - - **losses** 包含各种损失函数 - - **task_modules** 为检测任务提供模块。例如 assigners、samplers、box coders 和 prior generators。 - - **layers** 提供了一些基本的神经网络层 + - **seg_heads** 包含各种分割头。 + - **losses** 包含各种损失函数。 + - **task_modules** 为检测任务提供模块,例如 assigners、samplers、box coders 和 prior generators。 + - **layers** 提供了一些基本的神经网络层。 - **engine** 是运行时组件的一部分。 - - **runner** 为 [MMEngine 的执行器](https://mmengine.readthedocs.io/en/latest/tutorials/runner.html)提供扩展。 + - **runner** 为 [MMEngine 的执行器](https://mmengine.readthedocs.io/zh_CN/latest/tutorials/runner.html)提供扩展。 - **schedulers** 提供用于调整优化超参数的调度程序。 - **optimizers** 提供优化器和优化器封装。 - - **hooks** 提供 runner 的各种钩子。 + - **hooks** 提供执行器的各种钩子。 - **evaluation** 为评估模型性能提供不同的指标。 - **visualization** 用于可视化检测结果。 @@ -42,11 +42,11 @@ MMDetection 由 7 个主要部分组成,apis、structures、datasets、models 2. MMDetection 的基本使用方法请参考以下教程。 - - [训练和测试](https://mmdetection.readthedocs.io/en/dev-3.x/user_guides/index.html#train-test) + - [训练和测试](https://mmdetection.readthedocs.io/zh_CN/dev-3.x/user_guides/index.html#train-test) - - [实用工具](https://mmdetection.readthedocs.io/en/dev-3.x/user_guides/index.html#useful-tools) + - [实用工具](https://mmdetection.readthedocs.io/zh_CN/dev-3.x/user_guides/index.html#useful-tools) 3. 参考以下教程深入了解: - - [基础概念](https://mmdetection.readthedocs.io/en/dev-3.x/advanced_guides/index.html#basic-concepts) - - [组件定制](https://mmdetection.readthedocs.io/en/dev-3.x/advanced_guides/index.html#component-customization) + - [基础概念](https://mmdetection.readthedocs.io/zh_CN/dev-3.x/advanced_guides/index.html#basic-concepts) + - [组件定制](https://mmdetection.readthedocs.io/zh_CN/dev-3.x/advanced_guides/index.html#component-customization)