Initial commit

# compilation and distribution

__pycache__

_ext

*.pyc

*.so

maskrcnn_benchmark.egg-info/

build/

dist/

# pytorch/python/numpy formats

*.pth

*.pkl

*.npy

# ipython/jupyter notebooks

*.ipynb

**/.ipynb_checkpoints/

# Editor temporaries

*.swn

*.swo

*.swp

*~

# Pycharm editor settings

.idea

# project dirs

/datasets

/models

 No newline at end of file

## Abstractions

The main abstractions introduced by `maskrcnn_benchmark` that are useful to

have in mind are the following:

### ImageList

In PyTorch, the first dimension of the input to the network generally represents

the batch dimension, and thus all elements of the same batch have the same

height / width.

In order to support images with different sizes and aspect ratios in the same

batch, we created the `ImageList` class, which holds internally a batch of

images (os possibly different sizes). The images are padded with zeros such that

they have the same final size and batched over the first dimension. The original

sizes of the images before padding are stored in the `image_sizes` attribute,

and the batched tensor in `tensors`.

We provide a convenience function `to_image_list` that accepts a few different

input types, including a list of tensors, and returns an `ImageList` object.

```python

from maskrcnn_benchmark.structures.image_list import to_image_list

images = [torch.rand(3, 100, 200), torch.rand(3, 150, 170)]

batched_images = to_image_list(images)

# it is also possible to make the final batched image be a multiple of a number

batched_images_32 = to_image_list(images, size_divisible=32)

```

### BoxList

The `BoxList` class holds a set of bounding boxes (represented as a `Nx4` tensor) for

a specific image, as well as the size of the image as a `(width, height)` tuple.

It also contains a set of methods that allow to perform geometric

transformations to the bounding boxes (such as cropping, scaling and flipping).

The class accepts bounding boxes from two different input formats:

- `xyxy`, where each box is encoded as a `x1`, `y1`, `x2` and `y2` coordinates, and

- `xywh`, where each box is encoded as `x1`, `y1`, `w` and `h`.

Additionally, each `BoxList` instance can also hold arbitrary additional information

for each bounding box, such as labels, visibility, probability scores etc.

Here is an example on how to create a `BoxList` from a list of coordinates:

```python

from maskrcnn_benchmark.structures.bounding_box import BoxList, FLIP_LEFT_RIGHT

width = 100

height = 200

boxes = [

  [0, 10, 50, 50],

  [50, 20, 90, 60],

  [10, 10, 50, 50]

]

# create a BoxList with 3 boxes

bbox = BoxList(boxes, image_size=(width, height), mode='xyxy')

# perform some box transformations, has similar API as PIL.Image

bbox_scaled = bbox.resize((width * 2, height * 3))

bbox_flipped = bbox.transpose(FLIP_LEFT_RIGHT)

# add labels for each bbox

labels = torch.tensor([0, 10, 1])

bbox.add_field('labels', labels)

# bbox also support a few operations, like indexing

# here, selects boxes 0 and 2

bbox_subset = bbox[[0, 2]]

```

# Code of Conduct

Facebook has adopted a Code of Conduct that we expect project participants to adhere to.

Please read the [full text](https://code.fb.com/codeofconduct/)

so that you can understand what actions will and will not be tolerated.

# Contributing to Mask-RCNN Benchmark

We want to make contributing to this project as easy and transparent as

possible.

## Our Development Process

Minor changes and improvements will be released on an ongoing basis. Larger changes (e.g., changesets implementing a new paper) will be released on a more periodic basis.

## Pull Requests

We actively welcome your pull requests.

1. Fork the repo and create your branch from `master`.

2. If you've added code that should be tested, add tests.

3. If you've changed APIs, update the documentation.

4. Ensure the test suite passes.

5. Make sure your code lints.

6. If you haven't already, complete the Contributor License Agreement ("CLA").

## Contributor License Agreement ("CLA")

In order to accept your pull request, we need you to submit a CLA. You only need

to do this once to work on any of Facebook's open source projects.

Complete your CLA here: <https://code.facebook.com/cla>

## Issues

We use GitHub issues to track public bugs. Please ensure your description is

clear and has sufficient instructions to be able to reproduce the issue.

Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe

disclosure of security bugs. In those cases, please go through the process

outlined on that page and do not file a public issue.

## Coding Style  

* 4 spaces for indentation rather than tabs

* 80 character line length

* PEP8 formatting following [Black](https://black.readthedocs.io/en/stable/)

## License

By contributing to Mask-RCNN Benchmark, you agree that your contributions will be licensed

under the LICENSE file in the root directory of this source tree.

## Installation

### Requirements:

- PyTorch 1.0 from a nightly release. Installation instructions can be found in https://pytorch.org/get-started/locally/

- torchvision from master

- cocoapi

- yacs

- matplotlib

- GCC >= 4.9

- (optional) OpenCV for the webcam demo

### Option 1: Step-by-step installation

```bash

# first, make sure that your conda is setup properly with the right environment

# for that, check that `which conda`, `which pip` and `which python` points to the

# right path. From a clean conda env, this is what you need to do

conda create --name maskrcnn_benchmark

conda activate maskrcnn_benchmark

# this installs the right pip and dependencies for the fresh python

conda install ipython

export INSTALL_DIR=$PWD

# install pycocotools

cd $INSTALL_DIR

git clone https://github.com/cocodataset/cocoapi.git

cd cocoapi/PythonAPI

python setup.py build_ext install

# install PyTorch Detection

cd $INSTALL_DIR

git clone https://github.com/facebookresearch/maskrcnn-benchmark.git

cd maskrcnn-benchmark

# maskrcnn_benchmark and coco api dependencies

pip install -r requirements.txt

# follow PyTorch installation in https://pytorch.org/get-started/locally/

# we give the instructions for CUDA 9.0

conda install -c pytorch pytorch torchvision cudatoolkit=9.0

# the following will install the lib with

# symbolic links, so that you can modify

# the files if you want and won't need to

# re-build it

python setup.py build develop

unset INSTALL_DIR

# or if you are on macOS

# MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python setup.py build develop

```

### Option 2: Docker Image (Requires CUDA, Linux only)

Build image with defaults (`CUDA=9.0`, `CUDNN=7`):

    nvidia-docker build -t maskrcnn-benchmark docker/

Build image with other CUDA and CUDNN versions:

    nvidia-docker build -t maskrcnn-benchmark --build-arg CUDA=9.2 --build-arg CUDNN=7 docker/ 

Build and run image with built-in jupyter notebook(note that the password is used to log in jupyter notebook):

    nvidia-docker build -t maskrcnn-benchmark-jupyter docker/docker-jupyter/

    nvidia-docker run -td -p 8888:8888 -e PASSWORD=<password> -v <host-dir>:<container-dir> maskrcnn-benchmark-jupyter