Add docs for RPN

anhlt · Aug 24, 2018 · f7528ff · f7528ff
1 parent 37490cd
commit f7528ff
Show file tree

Hide file tree

Showing 9 changed files with 239 additions and 35 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,7 @@
+
+Region Proposal Network
+-----------------------
+
+.. autoclass:: faster_rcnn.faster_rcnn.RPN
+   :members:
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,10 +16,34 @@
 import sys
 import os
 
+autodoc_mock_imports = [
+    'torch', 
+    'torch.nn', 
+    'torch.nn.functional',
+    'Variable',
+    'torch.autograd', 
+    'pygtk', 
+    'gtk', 
+    'gobject', 
+    'argparse', 
+    'numpy', 
+    'pandas',
+    'faster_rcnn.fastrcnn.nms_wrapper',
+    'faster_rcnn.rpn_msr',
+    'faster_rcnn.network',
+    'faster_rcnn.rpn_msr.anchor_target_layer',
+    'torchvision.models',
+    'faster_rcnn.roi_pooling.modules.roi_pool',
+    'network',
+    'PIL',
+    'torchvision'
+]
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -33,6 +57,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/index.rst b/docs/index.rst
@@ -7,12 +7,36 @@ Welcome to Faster RCNN's documentation!
 =======================================
 
 Contents:
+---------
+
+.. toctree::
+    :maxdepth: 1
+
+    user/install
+
+
+
+Tutorial
+--------
+
+This part of the documentation, tutorial to train faster-rcnn on custom datasets
+
+.. toctree::
+    :maxdepth: 2
+
+    tutorial/mscoco
+    tutorial/voc
+
+The API Documentation / Guide
+-----------------------------
+
+If you are looking for information on a specific function, class, or method,
+this part of the documentation is for you.
 
 .. toctree::
    :maxdepth: 2
 
-   user/intro
-   user/install
+   api
 
 
 

diff --git a/docs/tutorial/mscoco.md b/docs/tutorial/mscoco.md
@@ -0,0 +1,16 @@
+MSCOCO dataset
+=======================
+
+```
+data
+├── annotations
+│   ├── captions_train2014.json
+│   ├── captions_val2014.json
+│   ├── instances_train2014.json
+│   ├── instances_val2014.json
+│   ├── person_keypoints_train2014.json
+│   └── person_keypoints_val2014.json
+└── images
+    ├── train2014
+    └── val2014
+```
diff --git a/docs/tutorial/voc.md b/docs/tutorial/voc.md
@@ -0,0 +1,7 @@
+VOC dataset
+====================================
+
+#### Datasets
+
+Sample flower dataset that contain total 280 images, belong to 2 species.
+    [Download](https://drive.google.com/open?id=1VJG28h-3p2cy5q-TR8BS3R7Ps19Ht8jy)
diff --git a/docs/user/install.md b/docs/user/install.md
@@ -1,7 +1,6 @@
 Installation
-=====================
+============
 
-### How to install
 
 #### System requirements
 
@@ -14,11 +13,11 @@ We provide the `Dockerfile` and `docker-compose.yml` for you to install the envi
 
 1. Install Docker
 
-    Install Docker from [Homepage]("https://docs.docker.com/install/")
+    Install Docker from [Homepage](https://docs.docker.com/install/)
 
 2. Install CUDA on Host Machine
 
-    [Install Cuda 8.0 on Ubuntu 16.04]("https://askubuntu.com/questions/799184/how-can-i-install-cuda-on-ubuntu-16-04")
+    [Install Cuda 8.0 on Ubuntu 16.04](https://askubuntu.com/questions/799184/how-can-i-install-cuda-on-ubuntu-16-04)
 
 3. Install docker-compose
 
@@ -33,8 +32,45 @@ We provide the `Dockerfile` and `docker-compose.yml` for you to install the envi
 1. Use docker-compose to create a docker image
 
     ```bash
-        cd ~\workspace\faster-rcnn
-        docker-compose up --build
+    cd ~\workspace\faster_rcnn
+    docker-compose up --build
     ```
 
+
+#### Compile Cython module 
+
+There are 3 modules need to compile `nms` , `roi_pooling` , `utils`. We need to exec `\bin\bash` on Docker image to build those modules
+
+
+```bash
+    cd ~/workspace/faster_rcnn
+    docker-compose exec python /bin/bash
+```
+
+- Compile `nms`
+
+    ```bash
+    cd /data/faster_rcnn/nms
+    python setup.py build_ext --inplace 
+    rm -rf build
+    ```
+
+- Compile `utils`
+
+    ```bash
+    cd /data/faster_rcnn/utils
+    python setup.py build_ext --inplace 
+    ```
+
+- Compile `roi_pooling`
+
+    ```bash
+    cd /data/faster_rcnn/roi_pooling/src/cuda/  
+    nvcc -c -o roi_pooling.cu.o roi_pooling_kernel.cu -D GOOGLE_CUDA=1 -x cu -Xcompiler -fPIC -arch=sm_61
+
+    cd /data/faster_rcnn/roi_pooling
+    python setup.py build_ext --inplace 
+    ```
+
+
 
diff --git a/docs/user/intro.md b/docs/user/intro.md
diff --git a/faster_rcnn/faster_rcnn.py b/faster_rcnn/faster_rcnn.py
@@ -6,11 +6,10 @@
 from .rpn_msr.proposal_layer import ProposalLayer
 from .rpn_msr.anchor_target_layer import AnchorTargerLayer
 from rpn_msr.proposal_target_layer import ProposalTargetLayer
-from .network import vgg16, Conv2d, np_to_variable, FC, tensor_to_variable
+from .network import vgg16, Conv2d, np_to_variable, FC, tensor_to_variable, smooth_l1_loss
 from roi_pooling.modules.roi_pool import RoIPool
 from .fastrcnn.bbox_transform import bbox_transform_inv, clip_boxes
 from .fastrcnn.nms_wrapper import nms
-from network import smooth_l1_loss
 from PIL import Image
 from torchvision import transforms
 
@@ -25,6 +24,31 @@ def nms_detections(pred_boxes, scores, nms_thresh, inds=None):
 
 
 class RPN(nn.Module):
+
+    """Summary
+    
+    Attributes
+    ----------
+    anchor_scales : list
+        Description
+    anchor_target_layer : TYPE
+        Description
+    bbox_conv : TYPE
+        Description
+    conv1 : TYPE
+        Description
+    cross_entropy : TYPE
+        Description
+    features : TYPE
+        Description
+    loss_box : TYPE
+        Description
+    proposal_layer : TYPE
+        Description
+    score_conv : TYPE
+        Description
+    """
+
     _feat_stride = [16, ]
     anchor_scales = [4, 8, 16, 32]
 
@@ -63,7 +87,24 @@ def _computer_forward(self, im_data):
     def forward(self,
                 im_data,
                 im_info, gt_boxes=None, gt_boxes_index=[]):
-
+        """Summary
+        
+        Parameters
+        ----------
+        im_data : TYPE
+            Description
+        im_info : TYPE
+            Description
+        gt_boxes : None, optional
+            Description
+        gt_boxes_index : list, optional
+            Description
+        
+        Returns
+        -------
+        TYPE
+            Description
+        """
         features, rpn_bbox_pred, rpn_cls_score = self._computer_forward(
             im_data)
         batch_size = features.shape[0]
@@ -116,7 +157,39 @@ def predict_rois(self, im_data, im_info):
 
 
 class FastRCNN(nn.Module):
-    """docstring for FasterRCNN"""
+    """docstring for FasterRCNN
+    
+    Attributes
+    ----------
+    bbox_fc : TYPE
+        Description
+    classes : TYPE
+        Description
+    cross_entropy : TYPE
+        Description
+    debug : TYPE
+        Description
+    fc6 : TYPE
+        Description
+    fc7 : TYPE
+        Description
+    loss_box : TYPE
+        Description
+    MAX_SIZE : int
+        Description
+    n_classes : TYPE
+        Description
+    proposal_target_layer : TYPE
+        Description
+    roi_pool : TYPE
+        Description
+    rpn : TYPE
+        Description
+    SCALES : tuple
+        Description
+    score_fc : TYPE
+        Description
+    """
 
     SCALES = (600, )
     MAX_SIZE = 1000
@@ -143,10 +216,34 @@ def __init__(self, classes, debug=False):
 
     @property
     def loss(self):
+        """Summary
+        
+        Returns
+        -------
+        TYPE
+            Description
+        """
         return self.cross_entropy + 10 * self.loss_box + self.rpn.loss
 
     def forward(self, im_data, im_info, gt_boxes=None, gt_boxes_index=[]):
-
+        """Summary
+        
+        Parameters
+        ----------
+        im_data : TYPE
+            Description
+        im_info : TYPE
+            Description
+        gt_boxes : None, optional
+            Description
+        gt_boxes_index : list, optional
+            Description
+        
+        Returns
+        -------
+        TYPE
+            Description
+        """
         features, rois = self.rpn(
             im_data, im_info, gt_boxes, gt_boxes_index)
 
@@ -228,12 +325,19 @@ def detect(self, image, thr=0.5):
 
     def get_image_blob(self, im):
         """Converts an image into a network input.
-        Arguments:
-            im (ndarray): a color image in BGR order
-        Returns:
-            blob (ndarray): a data blob holding an image pyramid
-            im_scale_factors (list): list of image scales (relative to im) used
-                in the image pyramid
+        
+        Parameters
+        ----------
+        im : ndarray
+            a color image in BGR order
+        
+        Returns
+        -------
+        blob : ndarray
+            a data blob holding an image pyramid
+        im_scale_factors : list
+            list of image scales (relative to im) used
+            in the image pyramid
         """
         transform = transforms.Compose([
             transforms.Resize(600),

diff --git a/howtorun.txt b/howtorun.txt