update docs

Summary: Pull Request resolved: fairinternal/detectron2#365

Differential Revision: D19292963

Pulled By: ppwwyyxx

fbshipit-source-id: b209bdedfeb81f8aacf8239a0a31b99fc26fd2c5

Author: ppwwyyxx

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

@@ -1,5 +1,5 @@
 ---
-name: "❓How to Use Detectron2"
+name: "❓How to do something?"
 about: How to do X with detectron2? How detectron2 does X?
 
 ---

GETTING_STARTED.md

@@ -26,7 +26,8 @@ python demo/demo.py --config-file configs/COCO-InstanceSegmentation/mask_rcnn_R_
 The configs are made for training, therefore we need to specify `MODEL.WEIGHTS` to a model from model zoo for evaluation.
 This command will run the inference and show visualizations in an OpenCV window.
 
-For details of the command line arguments, see `demo.py -h`. Some common ones are:
+For details of the command line arguments, see `demo.py -h` or look at its source code
+to understand its behavior. Some common arguments are:
 * To run __on your webcam__, replace `--input files` with `--webcam`.
 * To run __on a video__, replace `--input files` with `--video-input video.mp4`.
 * To run __on cpu__, add `MODEL.DEVICE cpu` after `--opts`.

INSTALL.md

@@ -23,14 +23,14 @@ After having the above dependencies, run:
 git clone https://github.com/facebookresearch/detectron2.git
 cd detectron2
 pip install -e .
+# (add --user if you don't have permission)
 
 # or if you are on macOS
 # MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ pip install -e .
-
-# or, as an alternative to `pip install`, use
-# python setup.py build develop
 ```
-Note: you often need to rebuild detectron2 after reinstalling PyTorch.
+
+To __rebuild__ detectron2, `rm -rf build/ **/*.so` then `pip install -e .`.
+You often need to rebuild detectron2 after reinstalling PyTorch.
 
 ### Common Installation Issues
 
@@ -60,7 +60,7 @@ Undefined C++ symbols in `detectron2/_C*.so`.
 Usually it's because the library is compiled with a newer C++ compiler but run with an old C++ run time.
 This can happen with old anaconda.
 
-Try `conda update libgcc`. Then remove the files you built (`build/`, `**/*.so`) and rebuild them.
+Try `conda update libgcc`. Then rebuild detectron2.
 </details>
 
 <details>

demo/README.md

@@ -1,7 +1,7 @@
 
 ## Detectron2 Demo
 
-We provide a command line tools for running a simple demo.
+We provide a command line tool to run a simple demo of builtin models.
 The usage is explained in [GETTING_STARTED.md](../GETTING_STARTED.md).
 
 See our [blog post](https://ai.facebook.com/blog/-detectron2-a-pytorch-based-modular-object-detection-library-)

detectron2/config/defaults.py

@@ -30,7 +30,7 @@
 # to be loaded to the model. You can find available models in the model zoo.
 _C.MODEL.WEIGHTS = ""
 
-# Values to be used for image normalization (BGR order).
+# Values to be used for image normalization (BGR order, since INPUT.FORMAT defaults to BGR).
 # To train on images of different number of channels, just set different mean & std.
 # Default values are the mean pixel value from ImageNet: [103.53, 116.28, 123.675]
 _C.MODEL.PIXEL_MEAN = [103.530, 116.280, 123.675]

detectron2/evaluation/coco_evaluation.py

@@ -44,7 +44,13 @@ def __init__(self, dataset_name, cfg, distributed, output_dir=None):
             cfg (CfgNode): config instance
             distributed (True): if True, will collect results from all ranks for evaluation.
                 Otherwise, will evaluate the results in the current process.
-            output_dir (str): optional, an output directory to dump results.
+            output_dir (str): optional, an output directory to dump all
+                results predicted on the dataset. The dump contains two files:
+
+                1. "instance_predictions.pth" a file in torch serialization
+                   format that contains all the raw original predictions.
+                2. "coco_instances_results.json" a json file in COCO's result
+                   format.
         """
         self._tasks = self._tasks_from_config(cfg)
         self._distributed = distributed

detectron2/modeling/proposal_generator/__init__.py

@@ -1,3 +1,3 @@
 # Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
 from .build import PROPOSAL_GENERATOR_REGISTRY, build_proposal_generator
-from .rpn import RPN_HEAD_REGISTRY, build_rpn_head
+from .rpn import RPN_HEAD_REGISTRY, build_rpn_head, RPN

detectron2/modeling/proposal_generator/rpn.py

@@ -133,8 +133,8 @@ def forward(self, images, features, gt_instances=None):
                 Each `Instances` stores ground-truth instances for the corresponding image.
 
         Returns:
-            proposals: list[Instances] or None
-            loss: dict[Tensor]
+            proposals: list[Instances]: contains fields "proposal_boxes", "objectness_logits"
+            loss: dict[Tensor] or None
         """
         gt_boxes = [x.gt_boxes for x in gt_instances] if gt_instances is not None else None
         del gt_instances

detectron2/modeling/proposal_generator/rrpn.py

@@ -28,20 +28,7 @@ def __init__(self, cfg, input_shape: Dict[str, ShapeSpec]):
         self.box2box_transform = Box2BoxTransformRotated(weights=cfg.MODEL.RPN.BBOX_REG_WEIGHTS)
 
     def forward(self, images, features, gt_instances=None):
-        """
-        Args:
-            images (ImageList): input images of length `N`
-            features (dict[str: Tensor]): input data as a mapping from feature
-                map name to tensor. Axis 0 represents the number of images `N` in
-                the input data; axes 1-3 are channels, height, and width, which may
-                vary between feature maps (e.g., if a feature pyramid is used).
-            gt_instances (list[Instances], optional): a length `N` list of `Instances`s.
-                Each `Instances` stores ground-truth instances for the corresponding image.
-
-        Returns:
-            proposals: list[Instances] or None
-            loss: dict[Tensor]
-        """
+        # same signature as RPN.forward
         gt_boxes = [x.gt_boxes for x in gt_instances] if gt_instances is not None else None
         del gt_instances
         features = [features[f] for f in self.in_features]

detectron2/structures/boxes.py

@@ -120,7 +120,7 @@ class Boxes:
     (support indexing, `to(device)`, `.device`, and iteration over all boxes)
 
     Attributes:
-        tensor: float matrix of Nx4.
+        tensor (torch.Tensor): float matrix of Nx4.
     """
 
     BoxSizeType = Union[List[int], Tuple[int, int]]

docs/tutorials/models.md

@@ -96,3 +96,6 @@ from detectron2.utils.events import EventStorage
 with EventStorage() as storage:
   losses = model(inputs)
 ```
+
+Another small thing to remember: detectron2 models do not support `model.to(device)` or `model.cpu()`.
+The device is defined in `cfg.MODEL.DEVICE` and cannot be changed afterwards.

projects/DensePose/doc/GETTING_STARTED.md

@@ -11,6 +11,16 @@ Please see [Apply Net](TOOL_APPLY_NET.md) for more details on the tool.
 
 ## Training
 
+First, prepare the [dataset](http://densepose.org/#dataset) into the following structure under the directory you'll run training scripts:
+<pre>
+datasets/coco/
+  annotations/
+    densepose_{train,minival,valminusminival}2014.json
+    <a href="densepose/densepose_minival2014_100.json">densepose_minival2014_100.json </a>  (optional, for testing only)
+  {train,val}2014/
+    # image files that are mentioned in the corresponding json
+</pre>
+
 To train a model one can use the [train_net.py](../train_net.py) script.
 This script was used to train all DensePose models in [Model Zoo](MODEL_ZOO.md).
 For example, to launch end-to-end DensePose-RCNN training with ResNet-50 FPN backbone