update docs

Summary: Pull Request resolved: facebookresearch#28

Differential Revision: D17895078

Pulled By: ppwwyyxx

fbshipit-source-id: 79d307f16e5ba61db5d21214ce9abe27de92296b

Author: ppwwyyxx

.github/ISSUE_TEMPLATE/questions-help-support.md

@@ -1,6 +1,6 @@
 ---
-name: "❓Questions/Help/Support"
-about: Do you need support?
+name: "❓Usage Questions / General Inquiries"
+about: How to do X ?
 
 ---
 
@@ -10,5 +10,5 @@ General questions about detectron2.
 
 NOTE:
 
-If you met an unexpected error when using detectron2,
-please use the "Unexpected Problems / Bugs" issue category instead.
+If you met any unexpected issue when using detectron2 and wish to know why,
+please use the "Unexpected Problems / Bugs" issue template.

GETTING_STARTED.md

@@ -20,7 +20,7 @@ For more advanced tutorials, refer to our [documentation](https://detectron2.rea
 ```
 python demo/demo.py --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \
   --input input1.jpg input2.jpg \
-	--opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl
+  --opts MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl
 ```
 It will run the inference and show visualizations in an OpenCV window.
 

INSTALL.md

@@ -1,6 +1,9 @@
 ## Installation
 
-Our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5) also has step-by-step instructions that install detectron2.
+Our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)
+has step-by-step instructions that install detectron2.
+The [Dockerfile](https://github.com/facebookresearch/detectron2/blob/master/Dockerfile)
+also installs detectron2 with a few simple commands.
 
 ### Requirements
 - Python >= 3.6

detectron2/modeling/backbone/build.py

@@ -5,8 +5,15 @@
 from .backbone import Backbone
 
 BACKBONE_REGISTRY = Registry("BACKBONE")
-"""
-Registry for backbones, which extract feature maps from images.
+BACKBONE_REGISTRY.__doc__ = """
+Registry for backbones, which extract feature maps from images
+
+The registered object must be a callable that accepts two arguments:
+
+1. A :class:`detectron2.config.CfgNode`
+2. A :class:`detectron2.layers.ShapeSpec`, which contains the input shape specification.
+
+It must returns an instance of :class:`Backbone`.
 """
 
 

detectron2/modeling/meta_arch/build.py

@@ -2,8 +2,11 @@
 from detectron2.utils.registry import Registry
 
 META_ARCH_REGISTRY = Registry("META_ARCH")  # noqa F401 isort:skip
-"""
+META_ARCH_REGISTRY.__doc__ = """
 Registry for meta-architectures, i.e. the whole model.
+
+The registered object will be called with `obj(cfg)`
+and expected to return a `nn.Module` object.
 """
 
 

detectron2/modeling/proposal_generator/build.py

@@ -2,8 +2,11 @@
 from detectron2.utils.registry import Registry
 
 PROPOSAL_GENERATOR_REGISTRY = Registry("PROPOSAL_GENERATOR")
-"""
+PROPOSAL_GENERATOR_REGISTRY.__doc__ = """
 Registry for proposal generator, which produces object proposals from feature maps.
+
+The registered object will be called with `obj(cfg, input_shape)`.
+The call should return a `nn.Module` object.
 """
 
 from . import rpn, rrpn  # noqa F401 isort:skip

detectron2/modeling/roi_heads/box_head.py

@@ -9,8 +9,10 @@
 from detectron2.utils.registry import Registry
 
 ROI_BOX_HEAD_REGISTRY = Registry("ROI_BOX_HEAD")
-"""
+ROI_BOX_HEAD_REGISTRY.__doc__ = """
 Registry for box heads, which make box predictions from per-region features.
+
+The registered object will be called with `obj(cfg, input_shape)`.
 """
 
 

detectron2/modeling/roi_heads/keypoint_head.py

@@ -11,8 +11,10 @@
 _TOTAL_SKIPPED = 0
 
 ROI_KEYPOINT_HEAD_REGISTRY = Registry("ROI_KEYPOINT_HEAD")
-"""
+ROI_KEYPOINT_HEAD_REGISTRY.__doc__ = """
 Registry for keypoint heads, which make keypoint predictions from per-region features.
+
+The registered object will be called with `obj(cfg, input_shape)`.
 """
 
 

detectron2/modeling/roi_heads/mask_head.py

@@ -9,9 +9,11 @@
 from detectron2.utils.registry import Registry
 
 ROI_MASK_HEAD_REGISTRY = Registry("ROI_MASK_HEAD")
-"""
+ROI_MASK_HEAD_REGISTRY.__doc__ = """
 Registry for mask heads, which predicts instance masks given
 per-region features.
+
+The registered object will be called with `obj(cfg, input_shape)`.
 """
 
 

detectron2/modeling/roi_heads/roi_heads.py

@@ -22,10 +22,13 @@
 from .mask_head import build_mask_head, mask_rcnn_inference, mask_rcnn_loss
 
 ROI_HEADS_REGISTRY = Registry("ROI_HEADS")
-"""
+ROI_HEADS_REGISTRY.__doc__ = """
 Registry for ROI heads in a generalized R-CNN model.
 ROIHeads take feature maps and region proposals, and
 perform per-region computation.
+
+The registered object will be called with `obj(cfg, input_shape)`.
+The call is expected to return an :class:`ROIHeads`.
 """
 
 logger = logging.getLogger(__name__)

detectron2/utils/registry.py

@@ -19,7 +19,9 @@ class MyBackbone():
 
     Or:
 
-        BACKBONE_REGISTRY.register(obj=MyBackbone)
+    .. code-block:: python
+
+        BACKBONE_REGISTRY.register(MyBackbone)
     """
 
     def __init__(self, name):

docs/conf.py

@@ -44,12 +44,15 @@
         "torch",
         "torchvision",
         "torch.nn",
+        "torch.nn.parallel",
         "torch.distributed",
         "torch.multiprocessing",
         "torch.autograd",
         "torch.autograd.function",
         "torch.nn.modules",
         "torch.nn.modules.utils",
+        "torch.utils",
+        "torch.utils.data",
         "torchvision",
         "torchvision.ops",
     ]:
@@ -235,9 +238,23 @@
 todo_include_todos = True
 
 
+_DEPRECATED_NAMES = set(["out_feature_channels", "out_feature_strides", "out_features"])
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    # we hide something deliberately
+    if getattr(obj, "__HIDE_SPHINX_DOC__", False):
+        return True
+    # Hide some names that are deprecated or not intended to be used
+    if name in _DEPRECATED_NAMES:
+        return True
+    return None
+
+
 def setup(app):
     from recommonmark.transform import AutoStructify
 
+    app.connect("autodoc-skip-member", autodoc_skip_member)
     # app.connect('autodoc-skip-member', autodoc_skip_member)
     app.add_config_value(
         "recommonmark_config",

docs/modules/modeling.rst

@@ -5,3 +5,25 @@ detectron2.modeling package
     :members:
     :undoc-members:
     :show-inheritance:
+
+
+Model Registries
+-----------------
+
+These are different registries provided in modeling.
+Each registry provide you the ability to replace it with your customized component,
+without having to modify detectron2's code.
+
+Note that it is impossible to allow users to customize any line of code directly.
+Even just to add one line at some place,
+you'll likely need to find out the smallest registry which contains that line,
+and register your component to that registry.
+
+
+.. autodata:: detectron2.modeling.META_ARCH_REGISTRY
+.. autodata:: detectron2.modeling.BACKBONE_REGISTRY
+.. autodata:: detectron2.modeling.PROPOSAL_GENERATOR_REGISTRY
+.. autodata:: detectron2.modeling.ROI_HEADS_REGISTRY
+.. autodata:: detectron2.modeling.ROI_BOX_HEAD_REGISTRY
+.. autodata:: detectron2.modeling.ROI_MASK_HEAD_REGISTRY
+.. autodata:: detectron2.modeling.ROI_KEYPOINT_HEAD_REGISTRY

docs/notes/benchmarks.md

@@ -8,7 +8,7 @@ with some other popular open source Mask R-CNN implementations.
 ### Settings
 
 * Hardware: 8 NVIDIA V100s.
-* Software: CUDA 10.0, cuDNN 7.6.4, PyTorch 1.3.0.dev20190920 (nightly build), TensorFlow 1.5.0rc2, Keras 2.2.5.
+* Software: CUDA 10.0, cuDNN 7.6.4, PyTorch 1.3.0.dev20190920 (nightly build), TensorFlow 1.5.0rc2, Keras 2.2.5, MxNet 1.6.0b20190820.
 * Model: an end-to-end R-50-FPN Mask-RCNN model, using the same hyperparameter as the
 	[Detectron baseline config](https://github.com/facebookresearch/Detectron/blob/master/configs/12_2017_baselines/e2e_mask_rcnn_R-50-FPN_1x.yaml).
 * Metrics: We use the average throughput in iterations 100-500 to skip GPU warmup time.
@@ -31,6 +31,8 @@ with some other popular open source Mask R-CNN implementations.
 +-----------------------------+--------------------+
 | mmdetection_                | 41                 |
 +-----------------------------+--------------------+
+| simpledet_                  | 39                 |
++-----------------------------+--------------------+
 | Detectron_                  | 19                 |
 +-----------------------------+--------------------+
 | `matterport/Mask_RCNN`__    | 14                 |
@@ -39,6 +41,7 @@ with some other popular open source Mask R-CNN implementations.
 .. _maskrcnn-benchmark: https://github.com/facebookresearch/maskrcnn-benchmark/
 .. _tensorpack: https://github.com/tensorpack/tensorpack/tree/master/examples/FasterRCNN
 .. _mmdetection: https://github.com/open-mmlab/mmdetection/
+.. _simpledet: https://github.com/TuSimple/simpledet/
 .. _Detectron: https://github.com/facebookresearch/Detectron
 __ https://github.com/matterport/Mask_RCNN/
 ```
@@ -109,15 +112,23 @@ Details for each implementation:
 	```
 	</details>
 
+* __SimpleDet__: at commit `9187a1`, run
+	```
+	python detection_train.py --config config/mask_r50v1_fpn_1x.py
+	```
+
 * __Detectron__: run
   ```
   python tools/train_net.py --cfg configs/12_2017_baselines/e2e_mask_rcnn_R-50-FPN_1x.yaml
   ```
+  Note that many of its ops run on CPUs, therefore the performance is limited.
 
 * __matterport/Mask_RCNN__: at commit `3deaec`, apply the following diff, `export TF_CUDNN_USE_AUTOTUNE=0`, then run
 	```
 	python coco.py train --dataset=/data/coco/ --model=imagenet
 	```
+  Note that many small details in this implementation might be different
+  from Detectron's standards.
 
 	<details>
 	<summary>

docs/tutorials/models.md

@@ -15,18 +15,26 @@ behavior of certain internal components of standard models.
 
 For example, to add a new backbone, import this code:
 ```python
-from detectron2.modeling import BACKBONE_REGISTRY, Backbone
+from detectron2.modeling import BACKBONE_REGISTRY, Backbone, ShapeSpec
+
 @BACKBONE_REGISTRY.register()
-class NewBackBone(Backbone):
+class ToyBackBone(Backbone):
   def __init__(self, cfg, input_shape):
     # create your own backbone
+    self.conv1 = nn.Conv2d(3, 64, kernel_size=7, stride=16, padding=3)
+
+  def forward(self, image):
+    return {"conv1": self.conv1(image)}
+
+  def output_shape(self):
+    return {"conv1": ShapeSpec(channels=64, stride=16)}
 ```
-which will allow you to use `cfg.MODEL.BACKBONE.NAME = 'NewBackBone'` in your config file.
+Then, you can use `cfg.MODEL.BACKBONE.NAME = 'ToyBackBone'` in your config file.
 
 As another example, to add new abilities to the ROI heads in the Generalized R-CNN meta-architecture,
 you can implement a new
 [ROIHeads](../modules/modeling.html#detectron2.modeling.ROIHeads) subclass and put it in the `ROI_HEADS_REGISTRY`.
 See [densepose in detectron2](https://github.com/facebookresearch/detectron2/tree/master/projects/DensePose)
-for an example.
+for an example that implements new ROIHeads.
 
-Other registries can be found in [API documentation](../modules/modeling.html).
+Other registries can be found in [API documentation](../modules/modeling.html#model-registries).

projects/TridentNet/README.md

@@ -4,17 +4,18 @@
 
 Yanghao Li\*, Yuntao Chen\*, Naiyan Wang, Zhaoxiang Zhang
 
-[[`TridentNet`](https://github.com/TuSimple/simpledet/tree/master/models/tridentnet)] [[`arXiv`](https://arxiv.org/abs/1802.00434)] [[`BibTeX`](#CitingTridentNet)]
+[[`TridentNet`](https://github.com/TuSimple/simpledet/tree/master/models/tridentnet)] [[`arXiv`](https://arxiv.org/abs/1901.01892)] [[`BibTeX`](#CitingTridentNet)]
 
 <div align="center">
   <img src="https://drive.google.com/uc?export=view&id=10THEPdIPmf3ooMyNzrfZbpWihEBvixwt" width="700px" />
 </div>
 
-In this repository, we implement TridentNet-Fast in the Detectron2 framework. Trident Network (TridentNet) aims to generate scale-specific feature maps with a uniform representational power. We construct a parallel multi-branch architecture in which each branch shares the same transformation parameters but with different receptive fields. TridentNet-Fast is a fast approximation version of TridentNet that could achieve significant improvements without any additional parameters and computational cost.
+In this repository, we implement TridentNet-Fast in Detectron2.
+Trident Network (TridentNet) aims to generate scale-specific feature maps with a uniform representational power. We construct a parallel multi-branch architecture in which each branch shares the same transformation parameters but with different receptive fields. TridentNet-Fast is a fast approximation version of TridentNet that could achieve significant improvements without any additional parameters and computational cost.
 
 ## Training
 
-To train a model one can call
+To train a model, run
 ```bash
 python /path/to/detectron2/projects/TridentNet/train_net.py --config-file <config.yaml>
 ```

setup.py

@@ -7,6 +7,9 @@
 import torch
 from torch.utils.cpp_extension import CUDA_HOME, CppExtension, CUDAExtension
 
+torch_ver = [int(x) for x in torch.__version__.split(".")[:2]]
+assert torch_ver >= [1, 3], "Requires PyTorch >= 1.3"
+
 
 def get_extensions():
     this_dir = os.path.dirname(os.path.abspath(__file__))
@@ -64,6 +67,7 @@ def get_extensions():
     description="Detectron2 is FAIR's next-generation research "
     "platform for object detection and segmentation.",
     packages=find_packages(exclude=("configs", "tests")),
+    python_requires=">=3.6",
     install_requires=[
         "termcolor>=1.1",
         "Pillow",