updates in docker&docs

Summary: Pull Request resolved: fairinternal/detectron2#402

Reviewed By: rbgirshick

Differential Revision: D21245938

Pulled By: ppwwyyxx

fbshipit-source-id: 3c0972929431a5fa70870c39ae18cf38fa0fa6ad

.circleci/config.yml

@@ -90,14 +90,14 @@ jobs:
       # Cache the venv directory that contains dependencies
       - restore_cache:
           keys:
-            - cache-key-{{ .Branch }}-ID-20200124
+            - cache-key-{{ .Branch }}-ID-20200425
 
       - <<: *install_dep
 
       - save_cache:
           paths:
             - ~/venv
-          key: cache-key-{{ .Branch }}-ID-20200124
+          key: cache-key-{{ .Branch }}-ID-20200425
 
       - <<: *install_detectron2
 

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

@@ -4,18 +4,24 @@ about: How to do X with detectron2? How detectron2 does X?
 
 ---
 
-## ❓ How to use Detectron2
+## ❓ How to do something using detectron2
 
-Questions like:
+General questions in learning detectron2, like:
 
 1. How to do X with detectron2?
 2. How detectron2 does X?
 
+
+
 NOTE:
 
-1. If you met any unexpected issue when using detectron2 and wish to know why,
-   please use the "Unexpected Problems / Bugs" issue template.
+1. Only general answers are provided for how-to questions.
+   If you want to ask about "why X did not work",
+   please use the [Unexpected behaviors / Bugs](https://github.com/facebookresearch/detectron2/issues/new?template=unexpected-problems-bugs.md)
+   issue template.
+
+2. About how to implement new models / new dataloader / new training logic, etc., check documentation first.
 
-2. We do not answer general machine learning / computer vision questions that are not specific to
-	 detectron2, such as how a model works, how to improve your training/make it converge, or what algorithm/methods can be
-	 used to achieve X.
+3. We do not answer general machine learning / computer vision questions that are not specific to
+   detectron2, such as how a model works, how to improve your training/make it converge, or what algorithm/methods can be
+   used to achieve X.

INSTALL.md

@@ -16,14 +16,15 @@ also installs detectron2 with a few simple commands.
 
 ### Build Detectron2 from Source
 
-After having the above dependencies and gcc & g++ ≥ 5, run:
+gcc & g++ ≥ 5 are required. [ninja](https://ninja-build.org/) is recommended for faster build.
+After having them, run:
 ```
 python -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
 # (add --user if you don't have permission)
 
 # Or, to install it from a local clone:
 git clone https://github.com/facebookresearch/detectron2.git
-cd detectron2 && python -m pip install -e .
+python -m pip install -e detectron2
 
 # Or if you are on macOS
 # CC=clang CXX=clang++ python -m pip install -e .
@@ -40,7 +41,8 @@ python -m pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wh
 You can replace cu101 with "cu{100,92}" or "cpu".
 
 Note that:
-1. Such installation has to be used with the latest official PyTorch release (currently 1.4).
+1. Such installation has to be used with certain version of official PyTorch release.
+   See [releases](https://github.com/facebookresearch/detectron2/releases) for requirements.
    It will not work with your custom build of PyTorch.
 2. Such installation is out-of-date w.r.t. master branch of detectron2. It may not be
 	 compatible with the master branch of a research project that uses detectron2 (e.g. those in

detectron2/utils/collect_env.py

@@ -131,6 +131,13 @@ def collect_env_info():
     except AttributeError:
         data.append(("torchvision", "unknown"))
 
+    try:
+        import fvcore
+
+        data.append(("fvcore", fvcore.__version__))
+    except ImportError:
+        pass
+
     try:
         import cv2
 

docker/Dockerfile

@@ -3,7 +3,7 @@ FROM nvidia/cuda:10.1-cudnn7-devel
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get update && apt-get install -y \
 	python3-opencv ca-certificates python3-dev git wget sudo  \
-	cmake protobuf-compiler libprotobuf-dev && \
+	cmake ninja-build protobuf-compiler libprotobuf-dev && \
   rm -rf /var/lib/apt/lists/*
 RUN ln -sv /usr/bin/python3 /usr/bin/python
 
@@ -28,10 +28,13 @@ RUN pip install --user 'git+https://github.com/cocodataset/cocoapi.git#subdirect
 RUN pip install --user 'git+https://github.com/facebookresearch/fvcore'
 # install detectron2
 RUN git clone https://github.com/facebookresearch/detectron2 detectron2_repo
+# set FORCE_CUDA because during `docker build` cuda is not accessible
 ENV FORCE_CUDA="1"
-# This will build detectron2 for all common cuda architectures and take a lot more time,
+# This will by default build detectron2 for all common cuda architectures and take a lot more time,
 # because inside `docker build`, there is no way to tell which architecture will be used.
-ENV TORCH_CUDA_ARCH_LIST="Kepler;Kepler+Tesla;Maxwell;Maxwell+Tegra;Pascal;Volta;Turing"
+ARG TORCH_CUDA_ARCH_LIST="Kepler;Kepler+Tesla;Maxwell;Maxwell+Tegra;Pascal;Volta;Turing"
+ENV TORCH_CUDA_ARCH_LIST="${TORCH_CUDA_ARCH_LIST}"
+
 RUN pip install --user -e detectron2_repo
 
 # Set a fixed model cache directory.

docker/Dockerfile-circleci

@@ -3,7 +3,7 @@ FROM nvidia/cuda:10.1-cudnn7-devel
 
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get update && apt-get install -y \
-	python3-opencv ca-certificates python3-dev git wget sudo && \
+	python3-opencv ca-certificates python3-dev git wget sudo ninja-build && \
   rm -rf /var/lib/apt/lists/*
 
 RUN wget -q https://bootstrap.pypa.io/get-pip.py && \

docker/README.md

@@ -1,24 +1,36 @@
-## Run the container
-Change to the *docker* directory of this repository:
+
+## Use the container (with docker ≥ 19.03)
+
+```
+cd docker/
+# Build:
+docker build --build-arg USER_ID=$UID -t detectron2:v0 .
+# Run:
+docker run --gpus all -it \
+	--shm-size=8gb --env="DISPLAY" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
+	--name=detectron2 detectron2:v0
+
+# Grant docker access to host X server to show images
+xhost +local:`docker inspect --format='{{ .Config.Hostname }}' detectron2`
+```
+
+## Use the container (with docker < 19.03)
+
+Install docker-compose and nvidia-docker2, then run:
 ```
-cd docker
-USER_ID=$UID docker-compose run detectron2
+cd docker && USER_ID=$UID docker-compose run detectron2
 ```
 
 #### Using a persistent cache directory
-Prevents models to be re-downloaded on every run, by storing them in a cache directory.
 
-`docker-compose run --volume=/path/to/cache:/tmp:rw detectron2`
+You can prevent models from being re-downloaded on every run,
+by storing them in a cache directory.
 
-## Rebuild the container
-Rebuild the container  by `USER_ID=$UID docker-compose build detectron2`.
-This is only necessary when `Dockerfile` has been changed. The initial build is done automatically.
+To do this, add `--volume=$HOME/.torch/fvcore_cache:/tmp:rw` in the run command.
 
 ## Install new dependencies
 Add the following to `Dockerfile` to make persistent changes.
 ```
-RUN sudo apt-get update && sudo apt-get install -y \
-  nano vim emacs
-RUN pip install --user pandas
+RUN sudo apt-get update && sudo apt-get install -y vim
 ```
 Or run them in the container to make temporary changes.

docs/notes/changelog.md

@@ -2,7 +2,7 @@
 
 ### Releases
 See release log at
-[https://github.com/facebookresearch/detectron2/releases](https://github.com/facebookresearch/detectron2/releases)
+[https://github.com/facebookresearch/detectron2/releases](https://github.com/facebookresearch/detectron2/releases).
 
 ### Notable Backward Incompatible Changes:
 
@@ -16,7 +16,10 @@ See release log at
 * v1: Rename `RPN_HEAD.NAME` to `RPN.HEAD_NAME`.
 * v2: A batch of rename of many configurations before release.
 
-### Known Bugs in Historical Versions:
+### Silent Regression in Historical Versions:
+
+We list a few silent regressions since they may silently produce incorrect results and will be hard to debug.
+
 * 03/30/2020 - 04/01/2020: ResNets are not correctly built.
 * 12/19/2019 - 12/26/2019: Using aspect ratio grouping causes a drop in accuracy.
 * release - 11/9/2019: Test time augmentation does not predict the last category.

docs/tutorials/deployment.md

@@ -53,25 +53,24 @@ You can also load `model.pb` to tools such as [netron](https://github.com/lutzro
 The model can be loaded in C++. An example [caffe2_mask_rcnn.cpp](../../tools/deploy/) is given,
 which performs CPU inference using `COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x`.
 
-The C++ code needs to be built with:
-* `libtorch.so`, `libc10.so`
+The C++ example needs to be built with:
+* PyTorch with caffe2 inside
 * gflags, glog, opencv
 * protobuf headers that match the version of your caffe2
 * MKL headers if caffe2 is built with MKL
-* `-D_GLIBCXX_USE_CXX11_ABI=` equals `torch._C._GLIBCXX_USE_CXX11_ABI`
 
 As an example, the following works inside [official detectron2 docker](../../docker/):
 ```
 sudo apt update && sudo apt install libgflags-dev libgoogle-glog-dev libopencv-dev
 pip install mkl-include
 wget https://github.com/protocolbuffers/protobuf/releases/download/v3.6.1/protobuf-cpp-3.6.1.tar.gz
 tar xf protobuf-cpp-3.6.1.tar.gz
-export TORCH_ROOT=/home/appuser/.local/lib/python3.6/site-packages/torch/
-g++ -O2 caffe2_mask_rcnn.cpp  `pkg-config --libs --cflags opencv` -Iprotobuf-3.6.1/src/  \
-   -lgflags -lglog -I$TORCH_ROOT/include -L$TORCH_ROOT/lib -lc10 -ltorch \
-   -I/home/appuser/.local/include -D_GLIBCXX_USE_CXX11_ABI=0 -o caffe2_mask_rcnn
+export CPATH=$(readlink -f ./protobuf-3.6.1/src/):$HOME/.local/include
+export CMAKE_PREFIX_PATH=/home/appuser/.local/lib/python3.6/site-packages/torch/
+mkdir build && cd build
+cmake -DTORCH_CUDA_ARCH_LIST=$TORCH_CUDA_ARCH_LIST .. && make
 
-export LD_LIBRARY_PATH=$TORCH_ROOT/lib
+# To run:
 ./caffe2_mask_rcnn --predict_net=./model.pb --init_net=./model_init.pb --input=input.jpg
 ```
 
@@ -88,7 +87,7 @@ Note that:
   its custom lightweight post-processing (e.g. full-image masks for every detected object is often not necessary).
 
 We also provide a python wrapper around the converted model, in the
-[Caffe2Model.__call__](../modules/export.html#detectron2.export.Caffe2Model.__call__) method.
+[Caffe2Model.\_\_call\_\_](../modules/export.html#detectron2.export.Caffe2Model.__call__) method.
 This method has an interface that's identical to the [pytorch versions of models](./models.md),
 and it internally applies pre/post-processing code to match the formats.
 They can serve as a reference for pre/post-processing in actual deployment.

docs/tutorials/extend.md

@@ -48,6 +48,6 @@ see the following tutorials for more details:
 * Detectron2 contains the standard logic that creates a data loader for training/testing from a
   dataset, but you can write your own as well. See [Use Custom Data Loaders](./data_loading.md).
 * Detectron2 implements many standard detection models, and provide ways for you
-  to overwrite their behaviors. See [Use Models](models.html) and [Write Models](./write-models.md).
+  to overwrite their behaviors. See [Use Models](./models.md) and [Write Models](./write-models.md).
 * Detectron2 provides a default training loop that is good for common training tasks.
   You can customize it with hooks, or write your own loop instead. See [training](./training.md).

docs/tutorials/models.md

@@ -33,7 +33,7 @@ Each dict corresponds to one image and the required keys
 depend on the type of model, and whether the model is in training or evaluation mode.
 For example, in order to do inference,
 all existing models expect the "image" key, and optionally "height" and "width".
-The detailed format of inputs and outputs are explained below.
+The detailed format of inputs and outputs of existing models are explained below.
 
 When in training mode, all models are required to be used under an `EventStorage`.
 The training statistics will be put into the storage:
@@ -51,13 +51,16 @@ and operates on single image rather than batches.
 
 ### Model Input Format
 
-All builtin models take a `list[dict]` as the inputs. Each dict
+Users can implement custom models that support any arbitrary input format.
+Here we describe the standard input format that all builtin models support in detectron2.
+They all take a `list[dict]` as the inputs. Each dict
 corresponds to information about one image.
 
 The dict may contain the following keys:
 
 * "image": `Tensor` in (C, H, W) format. The meaning of channels are defined by `cfg.INPUT.FORMAT`.
-  Image normalization, if any, will be performed inside the model.
+  Image normalization, if any, will be performed inside the model using
+	`cfg.MODEL.PIXEL_{MEAN,STD}`.
 * "instances": an [Instances](../modules/structures.html#detectron2.structures.Instances)
   object, with the following fields:
   + "gt_boxes": a [Boxes](../modules/structures.html#detectron2.structures.Boxes) object storing N boxes, one for each instance.

tests/README.md

@@ -2,7 +2,8 @@
 
 To run the unittests, do:
 ```
-python -m unittest discover -v -s tests
+cd detectron2
+python -m unittest discover -v -s ./tests
 ```
 
 There are also end-to-end inference & training tests, in [dev/run_*_tests.sh](../dev).

tools/deploy/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+# See https://pytorch.org/tutorials/advanced/cpp_frontend.html
+cmake_minimum_required(VERSION 3.0 FATAL_ERROR)
+project(caffe2_mask_rcnn)
+
+find_package(Torch REQUIRED)
+find_package(gflags REQUIRED)
+find_package(OpenCV REQUIRED)
+
+add_executable(caffe2_mask_rcnn caffe2_mask_rcnn.cpp)
+target_link_libraries(
+  caffe2_mask_rcnn
+  "${TORCH_LIBRARIES}" gflags glog ${OpenCV_LIBS})
+set_property(TARGET caffe2_mask_rcnn PROPERTY CXX_STANDARD 14)