diff --git a/.github/ISSUE_TEMPLATE/questions-help-support.md b/.github/ISSUE_TEMPLATE/questions-help-support.md index 67aa105124..afa521ff6a 100644 --- a/.github/ISSUE_TEMPLATE/questions-help-support.md +++ b/.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. diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index c30873d9e3..ff28a57164 100644 --- a/GETTING_STARTED.md +++ b/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. diff --git a/INSTALL.md b/INSTALL.md index 3e5e26c6f5..61e012d330 100644 --- a/INSTALL.md +++ b/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 diff --git a/detectron2/modeling/backbone/build.py b/detectron2/modeling/backbone/build.py index 8a1bbc950b..3d2ecae783 100644 --- a/detectron2/modeling/backbone/build.py +++ b/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`. """ diff --git a/detectron2/modeling/meta_arch/build.py b/detectron2/modeling/meta_arch/build.py index e7980b6efc..34bd4b7902 100644 --- a/detectron2/modeling/meta_arch/build.py +++ b/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. """ diff --git a/detectron2/modeling/proposal_generator/build.py b/detectron2/modeling/proposal_generator/build.py index 6d24206c4f..7f252bcb98 100644 --- a/detectron2/modeling/proposal_generator/build.py +++ b/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 diff --git a/detectron2/modeling/roi_heads/box_head.py b/detectron2/modeling/roi_heads/box_head.py index d2fc0323ba..e73a6a2624 100644 --- a/detectron2/modeling/roi_heads/box_head.py +++ b/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)`. """ diff --git a/detectron2/modeling/roi_heads/keypoint_head.py b/detectron2/modeling/roi_heads/keypoint_head.py index 3242b381d0..69dcf08eb0 100644 --- a/detectron2/modeling/roi_heads/keypoint_head.py +++ b/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)`. """ diff --git a/detectron2/modeling/roi_heads/mask_head.py b/detectron2/modeling/roi_heads/mask_head.py index 5fa41e04cd..1702973257 100644 --- a/detectron2/modeling/roi_heads/mask_head.py +++ b/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)`. """ diff --git a/detectron2/modeling/roi_heads/roi_heads.py b/detectron2/modeling/roi_heads/roi_heads.py index 07438ddcaf..a899663f68 100644 --- a/detectron2/modeling/roi_heads/roi_heads.py +++ b/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__) diff --git a/detectron2/utils/registry.py b/detectron2/utils/registry.py index 1826420420..c9aef9202a 100644 --- a/detectron2/utils/registry.py +++ b/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): diff --git a/docs/conf.py b/docs/conf.py index 7b83c4ab25..becfeee58b 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/modules/modeling.rst b/docs/modules/modeling.rst index c71ab2c7fb..640d1e07fd 100644 --- a/docs/modules/modeling.rst +++ b/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 diff --git a/docs/notes/benchmarks.md b/docs/notes/benchmarks.md index 8d3c3013a5..3158b1f9a6 100644 --- a/docs/notes/benchmarks.md +++ b/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: ``` +* __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.
diff --git a/docs/tutorials/models.md b/docs/tutorials/models.md index 9489da2cfb..f46f23fc79 100644 --- a/docs/tutorials/models.md +++ b/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). diff --git a/projects/TridentNet/README.md b/projects/TridentNet/README.md index 15cd5da70c..c0eb972eeb 100644 --- a/projects/TridentNet/README.md +++ b/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)]
-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 ``` diff --git a/setup.py b/setup.py index 3bf383c9a5..14fe1ca358 100644 --- a/setup.py +++ b/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",