[Doc] Add compatibility doc based on #470 (#504)

* Add compatibility doc based on #470 * Update zh-CN readme * add VoteNet ckpt conversion and fix relative path * fix another relative path under docs folder * fix typo * beautify docs and change order in compat doc
open-mmlab · May 10, 2021 · 7054878 · 7054878
1 parent ad2450b
commit 7054878
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -119,6 +119,8 @@ Please refer to [getting_started.md](docs/getting_started.md) for installation.
 
 Please see [getting_started.md](docs/getting_started.md) for the basic usage of MMDetection3D. We provide guidance for quick run [with existing dataset](docs/1_exist_data_model.md) and [with customized dataset](docs/2_new_data_model.md) for beginners. There are also tutorials for [learning configuration systems](docs/tutorials/config.md), [adding new dataset](docs/tutorials/customize_dataset.md), [designing data pipeline](docs/tutorials/data_pipeline.md), [customizing models](docs/tutorials/customize_models.md), [customizing runtime settings](docs/tutorials/customize_runtime.md) and [Waymo dataset](docs/tutorials/waymo.md).
 
+Please refer to [FAQ](docs/faq.md) for frequently asked questions. When updating the version of MMDetection3D, please also check the [compatibility doc](docs/compatibility.md) to be aware of the BC-breaking updates introduced in each version.
+
 ## Citation
 
 If you find this project useful in your research, please consider cite:

diff --git a/README_zh-CN.md b/README_zh-CN.md
@@ -118,6 +118,8 @@ MMDetection3D 是一个基于 PyTorch 的目标检测开源工具箱, 下一代
 
 请参考[快速入门文档](docs/get_started.md)学习 MMDetection3D 的基本使用。 我们为新手提供了分别针对[已有数据集](docs/1_exist_data_model.md)和[新数据集](docs/2_new_data_model.md)的使用指南。我们也提供了一些进阶教程，内容覆盖了[学习配置文件](docs/tutorials/config.md), [增加数据集支持](docs/tutorials/customize_dataset.md), [设计新的数据预处理流程](docs/tutorials/data_pipeline.md), [增加自定义模型](docs/tutorials/customize_models.md), [增加自定义的运行时配置](docs/tutorials/customize_runtime.md)和 [Waymo 数据集](docs/tutorials/waymo.md).
 
+请参考 [FAQ](docs/faq.md) 查看一些常见的问题与解答。在升级 MMDetection3D 的版本时，请查看[兼容性文档](docs/compatibility.md)以知晓每个版本引入的不与之前版本兼容的更新。
+
 ## 引用
 
 如果你觉得本项目对你的研究工作有所帮助，请参考如下 bibtex 引用 MMdetection3D

diff --git a/docs/0_demo.md b/docs/0_demo.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-We provide scipts for multi-modality/single-modality and indoor/outdoor 3D detection demos. The pre-trained models can be downloaded from [model zoo](../docs/model_zoo.md). We provide pre-processed sample data from KITTI and SUN RGB-D dataset. You can use any other data following our pre-processing steps.
+We provide scipts for multi-modality/single-modality and indoor/outdoor 3D detection demos. The pre-trained models can be downloaded from [model zoo](https://github.com/open-mmlab/mmdetection3d/blob/master/docs/model_zoo.md). We provide pre-processed sample data from KITTI and SUN RGB-D dataset. You can use any other data following our pre-processing steps.
 
 ## Testing
 

diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -0,0 +1,21 @@
+# Compatibility with Previous Versions of MMDetection3D
+
+This document provides detailed descriptions of the BC-breaking changes in MMDetection3D.
+
+## MMDetection3D 0.12.0
+
+### SUNRGBD dataset for ImVoteNet
+
+We adopt a new pre-processing procedure for the SUNRGBD dataset in order to support ImVoteNet, which is a multi-modality method requiring both image and point cloud data. In previous versions of MMDetection3D, SUNRGBD dataset was only used for point cloud based 3D detection methods. In MMDetection3D 0.12.0, we add ImVoteNet to our model zoo, thus updating SUNRGBD correspondingly by adding image-related pre-processing steps. Specificly, we made these changes:
+
+- Fix a bug in the image file path in meta data.
+- Convert calibration matrices from double to float to avoid type mismatch in further operations.
+- Add instructions in the documents on preparing image data.
+
+Please refer to the SUNRGBD [README.md](https://github.com/open-mmlab/mmdetection3d/blob/master/data/sunrgbd/README.md) for more details.
+
+## MMDetection3D 0.6.0
+
+### VoteNet model structure update
+
+In MMDetection 0.6.0, we updated the model structure of VoteNet, therefore model checkpoints generated by MMDetection < 0.6.0 should be first converted to a format compatible with the latest VoteNet structure via this [script](https://github.com/open-mmlab/mmdetection3d/blob/master/tools/model_converters/convert_votenet_checkpoints.py). For more details, please refer to the VoteNet [README.md](https://github.com/open-mmlab/mmdetection3d/tree/master/configs/votenet/README.md)
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -95,7 +95,7 @@ pip install mmcv-full
 
 Note:
 
-MMDetection3D v0.13.0 is only compatiable with MMDetection version `mmdet>=2.10.0, <=2.11.0`. The future versions will only support mmdet>=2.12.0 since the v0.14.0 (to be released in May).
+MMDetection3D v0.13.0 is only compatible with MMDetection version `mmdet>=2.10.0, <=2.11.0`. The future versions will only support `mmdet>=2.12.0` since v0.14.0 (to be released in May).
 
 ```shell
 pip install git+https://github.com/open-mmlab/mmdetection.git

diff --git a/docs/index.rst b/docs/index.rst
@@ -35,6 +35,7 @@ Welcome to MMDetection3D's documentation!
 
  benchmarks.md
  faq.md
+ compatibility.md
 
 .. toctree::
  :caption: API Reference