Revise docs (#2566)

* Revise README.md

* Revise `GETTING_STARTED.md`

* Revise `INSTALL.md`

* Add `CONFIG.md`

* Fix RetinaNet backbones in README

* Fix cascade backbones in README

* Fix capitalization

* Replace demo images and update visualize funcall

* Revise `DATA.md`

* Fix link to `DATA.md`

* Fix capitalization

PaddleCV/object_detection/README.md

 # PaddlePaddle Object Detection
 
-This object detection framework is based on PaddlePaddle. We want to provide classically and state of the art detection algorithms in generic object detection and specific target detection for users. And we aimed to make this framework easy to extend, train, and deploy. We aimed to make it easy to use in research and products.
+The goal of PaddleDetection is to provide easy access to a wide range of object
+detection models in both industry and research settings. we design
+PaddleDetection to be not only performant, production-ready but also highly
+flexible, catering to research needs.
 
 
 <div align="center">
-  <img src="demo/output/000000523957.jpg" />
+  <img src="demo/output/000000570688.jpg" />
 </div>
 
 
 ## Introduction
 
-Major features:
+Design Principles:
 
-- Easy to Deploy:
-  All the operations related to inference are implemented by C++ and CUDA, it makes the detection model easy to deploy in products on the server without Python based on the high efficient inference engine of PaddlePaddle.
-  We release detection models based on ResNet-D backbone, for example, the accuracy of Faster-RCNN model with FPN based on ResNet50 VD is close to model based on ResNet 101. But the former is smaller and faster.
+- Production Ready:
+Key operations are implemented in C++ and CUDA, together with PaddlePaddle's
+highly efficient inference engine, enables easy deployment in server environments.
 
-- Easy to Customize:
-   All components are modular encapsulated, including the data transforms. It's easy to plug in and pull out any module. For example, users can switch backbone easily or add mixup data augmentation for models.
+- Highly Flexible:
+Components are designed to be modular. Model architectures, as well as data
+preprocess pipelines, can be easily customized with simple configuration
+changes.
 
-- High Efficiency:
-  Based on the high efficient PaddlePaddle framework, less memory is required. For example, the batch size of Mask-RCNN based on ResNet50 can be 5 per Tesla V100 (16G) when multi-GPU training. The training speed of Yolo v3 is faster than other frameworks.  
+- Performance Optimized:
+With the help of the underlying PaddlePaddle framework, faster training and
+reduced GPU memory footprint is achieved. Notably, Yolo V3 training is
+much faster compared to other frameworks. Another example is Mask-RCNN
+(ResNet50), we managed to fit up to 5 images per GPU (V100 16GB) during
+training.
 
-The supported architectures are as follows:
+Supported Architectures:
 
-|                    | ResNet |ResNet vd| ResNeXt  | SENet    | MobileNet | DarkNet|
-|--------------------|:------:|--------:|:--------:|:--------:|:---------:|:------:|
-| Faster R-CNN       | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| Faster R-CNN + FPN | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| Mask R-CNN         | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| Mask R-CNN + FPN   | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| Cascade R-CNN      | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| RetinaNet          | ✓      | ✓      | ✓        |  ✓       | ✗        | ✗      |
-| Yolov3             | ✓      | ✗      | ✗         |  ✗       | ✓        | ✓     |
-| SSD                | ✗      | ✗      | ✗         |  ✗       | ✓        | ✗      |
+|                    | ResNet | ResNet-vd <sup>[1](#vd)</sup> | ResNeXt | SENet | MobileNet | DarkNet |
+|--------------------|:------:|------------------------------:|:-------:|:-----:|:---------:|:-------:|
+| Faster R-CNN       | ✓      |                             ✓ | ✓       | ✓     | ✗         | ✗       |
+| Faster R-CNN + FPN | ✓      |                             ✓ | ✓       | ✓     | ✗         | ✗       |
+| Mask R-CNN         | ✓      |                             ✓ | ✓       | ✓     | ✗         | ✗       |
+| Mask R-CNN + FPN   | ✓      |                             ✓ | ✓       | ✓     | ✗         | ✗       |
+| Cascade R-CNN      | ✓      |                             ✗ | ✗       | ✗     | ✗         | ✗       |
+| RetinaNet          | ✓      |                             ✗ | ✗       | ✗     | ✗         | ✗       |
+| Yolov3             | ✓      |                             ✗ | ✗       | ✗     | ✓         | ✓       |
+| SSD                | ✗      |                             ✗ | ✗       | ✗     | ✓         | ✗       |
 
-The extensive capabilities:
+<a name="vd">[1]</a> ResNet-vd models offer much improved accuracy with negligible performance cost.
 
-- [x] **Synchronized batch norm**:  used in Yolo v3.
-- [x] **Group Norm**: supported this operation, the related model will be added later.
-- [x] **Modulated deformable convolution**: supported this operation, the related model will be added later.
-- [x] **Deformable PSRoI Pooling**: supported this operation, the related model will be added later.
+Advanced Features:
 
+- [x] **Synchronized Batch Norm**: currently used by Yolo V3.
+- [x] **Group Norm**: pretrained models to be released.
+- [x] **Modulated Deformable Convolution**: pretrained models to be released.
+- [x] **Deformable PSRoI Pooling**: pretrained models to be released.
 
-#### Work in Progress and to Do
-
-- About Framework:
-   - Mixed precision training and distributed training.
-   - 8-bit deployment.
-   - Easy to customize the user-defined function.
-
-- About Algorithms:
-   - More SOTA models.
-   - More easy-to-deployed models.
-
-We are glad to receive your feedback.
 
 ## Model zoo
 
-The trained models can be available in PaddlePaddle [detection model zoo](docs/MODEL_ZOO.md).
+Pretrained models are available in the PaddlePaddle [detection model zoo](docs/MODEL_ZOO.md).
+
 
 ## Installation
 
-Please follow the [installation instructions](docs/INSTALL.md) to install  and prepare environment.
+Please follow the [installation guide](docs/INSTALL.md).
+
 
 ## Get Started
 
-For quickly start, infer an image:
+For inference, simply run the following command and the visualized result will
+be saved in `output/`.
 
 ```bash
 export PYTHONPATH=`pwd`:$PYTHONPATH
 python tools/infer.py -c configs/mask_rcnn_r50_1x.yml \
-    -o weights=http://
-    -infer_img=demo/000000523957.jpg
+    -o weights=https://paddlemodels.bj.bcebos.com/object_detection/mask_rcnn_r50_1x.tar
+    -infer_img=demo/000000570688.jpg
 ```
 
-The predicted  and visualized results are saved in `output/1.jpg`.
+For detailed training and evaluation workflow, please refer to [GETTING_STARTED.md](docs/GETTING_STARTED.md).
 
-For more detailed training and evaluating pipeline, please refer [GETTING_STARTED.md](docs/GETTING_STARTED.md).
+We also recommend users to take a look at the [IPython Notebook demo](demo/mask_rcnn_demo.ipynb)
 
+Further information can be found in these documentations:
 
-More documentation:
+- [Introduction to the configuration workflow.](docs/CONFIG.md)
+- [Guide to custom dataset and preprocess pipeline.](docs/DATA.md)
 
-- [How to config an object detection pipeline.](docs/CONFIG.md)
-- [How to use customized dataset and add data preprocessing.](docs/DATA.md)
 
+##  Todo List
 
-## Deploy
+Please note this is a work in progress, substantial changes may come in the
+near future.
+Some of the planned features include:
 
-The example of how to use PaddlePaddle to deploy detection model will be added later.
+- [ ] Mixed precision training.
+- [ ] Distributed training.
+- [ ] Inference in 8-bit mode.
+- [ ] User defined operations.
+- [ ] Larger model zoo.
 
-## Updates
 
-The major updates are as follows:
+## Updates
 
-#### 2019-07-03
-- Release the unified detection framework.
-- Supported algorithms: Faster R-CNN, Mask R-CNN, Faster R-CNN + FPN, Mask R-CNN + FPN, Cascade-Faster-RCNN + FPN, RetinaNet, Yolo v3, and SSD.
-- Release the first version of Model Zoo.
+#### Initial release (7/3/2019)
+- Initial release of PaddleDetection and detection model zoo
+- Models included: Faster R-CNN, Mask R-CNN, Faster R-CNN+FPN, Mask
+  R-CNN+FPN, Cascade-Faster-RCNN+FPN, RetinaNet, Yolo v3, and SSD.
 
 
 ## Contributing
 
-We appreciate everyone's contributions!
+Contributions are highly welcomed and we would really appreciate your feedback!!

PaddleCV/object_detection/docs/CONFIG.md

+# Introduction
+
+PaddleDetection takes a rather principled approach to configuration management. We aim to automate the configuration workflow and to reduce configuration errors.
+
+
+# Rationale
+
+Presently, configuration in mainstream frameworks are usually dictionary based: the global config is simply a giant, loosely defined Python dictionary.
+
+This approach is error prone, e.g., misspelled or displaced keys may lead to serious errors in training process, causing time loss and wasted resources.
+
+To avoid the common pitfalls, with automation and static analysis in mind, we propose a configuration design that is user friendly, easy to maintain and extensible.
+
+
+# Design
+
+The design utilizes some of Python's reflection mechanism to extract configuration schematics from python class definitions.
+
+To be specific, it extracts information from class constructor arguments, including names, docstrings, default values, data types (if type hints are available).
+
+This approach advocates modular and testable design, leading to a unified and extensible code base.
+
+
+## API
+
+Most of the functionality is exposed in `ppdet.core.workspace` module.
+
+-   `register`: This decorator register a class as configurable module; it understands several special annotations in the class definition.
+    -   `__category__`: For better organization, modules are classified into categories.
+    -   `__inject__`: A list of constructor arguments, which are intended to take module instances as input, module instances will be created at runtime an injected. The corresponding configuration value can be a class name string, a serialized object, a config key pointing to a serialized object, or a dict (in which case the constructor needs to handle it, see example below).
+    -   `__op__`: Shortcut for wrapping PaddlePaddle operators into a callable objects, together with `__append_doc__` (extracting docstring from target PaddlePaddle operator automatically), this can be a real time saver.
+-   `serializable`: This decorator make a class directly serializable in yaml config file, by taking advantage of [pyyaml](https://pyyaml.org/wiki/PyYAMLDocumentation)'s serialization mechanism.
+-   `create`: Constructs a module instance according to global configuration.
+-   `load_config` and `merge_config`: Loading yaml file and merge config settings from command line.
+
+
+## Example
+
+Take the `RPNHead` module for example, it is composed of several PaddlePaddle operators. We first wrap those operators into classes, then pass in instances of these classes when instantiating the `RPNHead` module.
+
+```python
+# excerpt from `ppdet/modeling/ops.py`
+from ppdet.core.workspace import register, serializable
+
+# ... more operators
+
+@register
+@serializable
+class GenerateProposals(object):
+    # NOTE this class simply wraps a PaddlePaddle operator
+    __op__ = fluid.layers.generate_proposals
+    # NOTE docstring for args are extracted from PaddlePaddle OP
+    __append_doc__ = True
+
+    def __init__(self,
+                 pre_nms_top_n=6000,
+                 post_nms_top_n=1000,
+                 nms_thresh=.5,
+                 min_size=.1,
+                 eta=1.):
+        super(GenerateProposals, self).__init__()
+        self.pre_nms_top_n = pre_nms_top_n
+        self.post_nms_top_n = post_nms_top_n
+        self.nms_thresh = nms_thresh
+        self.min_size = min_size
+        self.eta = eta
+
+# ... more operators
+
+# excerpt from `ppdet/modeling/anchor_heads/rpn_head.py`
+from ppdet.core.workspace import register
+from ppdet.modeling.ops import AnchorGenerator, RPNTargetAssign, GenerateProposals
+
+@register
+class RPNHead(object):
+    """
+    RPN Head
+
+    Args:
+        anchor_generator (object): `AnchorGenerator` instance
+        rpn_target_assign (object): `RPNTargetAssign` instance
+        train_proposal (object): `GenerateProposals` instance for training
+        test_proposal (object): `GenerateProposals` instance for testing
+    """
+    __inject__ = [
+        'anchor_generator', 'rpn_target_assign', 'train_proposal',
+        'test_proposal'
+    ]
+
+    def __init__(self,
+                 anchor_generator=AnchorGenerator().__dict__,
+                 rpn_target_assign=RPNTargetAssign().__dict__,
+                 train_proposal=GenerateProposals(12000, 2000).__dict__,
+                 test_proposal=GenerateProposals().__dict__):
+        super(RPNHead, self).__init__()
+        self.anchor_generator = anchor_generator
+        self.rpn_target_assign = rpn_target_assign
+        self.train_proposal = train_proposal
+        self.test_proposal = test_proposal
+        if isinstance(anchor_generator, dict):
+            self.anchor_generator = AnchorGenerator(**anchor_generator)
+        if isinstance(rpn_target_assign, dict):
+            self.rpn_target_assign = RPNTargetAssign(**rpn_target_assign)
+        if isinstance(train_proposal, dict):
+            self.train_proposal = GenerateProposals(**train_proposal)
+        if isinstance(test_proposal, dict):
+            self.test_proposal = GenerateProposals(**test_proposal)
+```
+
+The corresponding(generated) YAML snippet is as follows, note this is the configuration in **FULL**, all the default values can be omitted. In case of the above example, all arguments have default value, meaning nothing is required in the config file.
+
+```yaml
+RPNHead:
+  test_prop:
+    eta: 1.0
+    min_size: 0.1
+    nms_thresh: 0.5
+    post_nms_top_n: 1000
+    pre_nms_top_n: 6000
+  train_prop:
+    eta: 1.0
+    min_size: 0.1
+    nms_thresh: 0.5
+    post_nms_top_n: 2000
+    pre_nms_top_n: 12000
+  anchor_generator:
+    # ...
+  rpn_target_assign:
+    # ...
+```
+
+Example snippet that make use of the `RPNHead` module.
+
+```python
+from ppdet.core.worskspace import load_config, merge_config, create
+
+load_config('some_config_file.yml')
+merge_config(more_config_options_from_command_line)
+
+rpn_head = create('RPNHead')
+# ... code that use the created module!
+```
+
+Configuration file can also have serialized objects in it, denoted with `!`, for example
+
+```yaml
+LearningRate:
+  base_lr: 0.01
+  schedulers:
+  - !PiecewiseDecay
+    gamma: 0.1
+    milestones: [60000, 80000]
+  - !LinearWarmup
+    start_factor: 0.3333333333333333
+    steps: 500
+```
+
+
+# Requirements
+
+Two python packages are used, both are optional.
+
+-   [typeguard](https://github.com/agronholm/typeguard) is used for type checking in Python 3.
+-   [docstring\_parser](https://github.com/rr-/docstring_parser) is needed for docstring parsing.
+
+To install them, simply run:
+
+```shell
+pip install typeguard http://github.com/willthefrog/docstring_parser/tarball/master
+```
+
+
+# Tooling
+
+A small utility (`tools/configure.py`) is included to simplify the configuration process, it provides 4 commands to walk users through the configuration process:
+
+1.  `list`: List currently registered modules by category, one can also specify which category to list with the `--category` flag.
+2.  `help`: Get help information for a module, including description, options, configuration template and example command line flags.
+3.  `analyze`: Check configuration file for missing/extraneous options, options with mismatch type (if type hint is given) and missing dependencies, it also highlights user provided values (overridden default values).
+4.  `generate`: Generate a configuration template for a given list of modules. By default it generates a complete configuration file, which can be quite verbose; if a `--minimal` flag is given, it generates a template that only contain non optional settings. For example, to generate a configuration for Faster R-CNN architecture with `ResNet` backbone and `FPN`, run:
+
+    ```shell
+    python tools/configure.py generate FasterRCNN ResNet RPNHead RoIAlign BBoxAssigner BBoxHead FasterRCNNTrainFeed FasterRCNNTestFeed LearningRate OptimizerBuilder
+    ```
+
+    For a minimal version, run:
+
+    ```shell
+    python tools/configure.py --minimal generate FasterRCNN BBoxHead
+    ```

PaddleCV/object_detection/docs/DATA.md

 ## Introduction
-This is a Python module used to load and convert data into formats for detection model training, evaluation and inference. The converted sample schema is a tuple of np.ndarrays. For example, the schema of Faster R-CNN training data is: `[(im, im_info, im_id, gt_bbox, gt_class, is_crowd), (...)]`.
+
+The data pipeline is responsible for loading and converting data. Each
+resulting data sample is a tuple of np.ndarrays.
+For example, Faster R-CNN training uses samples of this format: `[(im,
+im_info, im_id, gt_bbox, gt_class, is_crowd), (...)]`.
 
 ### Implementation
-This module is consists of four sub-systems: data parsing, image pre-processing, data conversion and data feeding apis.  
 
-We use `dataset.Dataset` to abstract a set of data samples. For example, `COCO` data contains 3 sets of data for training, validation, and testing respectively. Original data stored in files could be loaded into memory using `dataset.source`; Then make use of `dataset.transform` to process the data; Finally, the batch data could be fetched by the api of `dataset.Reader`.
+The data pipeline consists of four sub-systems: data parsing, image
+pre-processing, data conversion and data feeding APIs.
+
+Data samples are collected to form `dataset.Dataset`s, usually 3 sets are
+needed for training, validation, and testing respectively.
 
-Sub-systems introduction:
-1. Data prasing  
-By data parsing, we can get a `dataset.Dataset` instance, whose implementation is located in `dataset.source`. This sub-system is used to parse different data formats, which is easy to add new data format supports. Currently, only following data sources are included:
+First, `dataset.source` loads the data files into memory, then
+`dataset.transform` processes them, and lastly, the batched samples
+are fetched by `dataset.Reader`.
+
+Sub-systems details:
+1. Data parsing
+Parses various data sources and creates `dataset.Dataset` instances. Currently,
+following data sources are supported:
 
-- COCO data source  
-This kind of source is used to load `COCO` data directly, eg: `COCO2017`. It's composed of json files for labeling info and image files. And it's directory structure is as follows:
+- COCO data source
+Loads `COCO` type datasets with directory structures like this:
 
   ```
   data/coco/
@@ -29,9 +41,8 @@ This kind of source is used to load `COCO` data directly, eg: `COCO2017`. It's c
   |   ...
   ```
 
-- Pascal VOC data source  
-This kind of source is used to load `VOC` data directly, eg: `VOC2007`. It's composed of xml files for labeling info and image files. And it's directory structure is as follows:
-
+- Pascal VOC data source
+Loads `Pascal VOC` like datasets with directory structure like this:
 
   ```
   data/pascalvoc/
@@ -59,28 +70,28 @@ This kind of source is used to load `VOC` data directly, eg: `VOC2007`. It's com
   |   ...
   ```
 
-
-
-- Roidb data source  
-This kind of source is a normalized data format which only contains a pickle file. The pickle file only has a dictionary which only has a list named 'records' (maybe there is a mapping file for label name to label id named 'canme2id'). You can convert `COCO` or `VOC` data into this format.  The pickle file's content is as follows:
+- Roidb data source
+A generalized data source serialized as pickle files, which have the following
+structure:
 ```python
-(records, catname2clsid)
-'records' is list of dict whose structure is:
+(records, cname2id)
+# `cname2id` is a `dict` which maps category name to class IDs
+# and `records` is a list of dict of this structure:
 {
-    'im_file': im_fname, # image file name
-    'im_id': im_id, # image id
-    'h': im_h, # height of image
-    'w': im_w, # width
-    'is_crowd': is_crowd,
-    'gt_class': gt_class,
-    'gt_bbox': gt_bbox,
-    'gt_poly': gt_poly,
+    'im_file': im_fname,    # image file name
+    'im_id': im_id,         # image ID
+    'h': im_h,              # height of image
+    'w': im_w,              # width of image
+    'is_crowd': is_crowd,   # crowd marker
+    'gt_class': gt_class,   # ground truth class
+    'gt_bbox': gt_bbox,     # ground truth bounding box
+    'gt_poly': gt_poly,     # ground truth segmentation
 }
-'cname2id' is a dict to map category name to class id
-
 ```
-We also provide the tool to generate the roidb data source in `./tools/`. You can use the follow command to implement.
-```python
+
+We provide a tool to generate roidb data sources. To convert `COCO` or `VOC`
+like dataset, run this command:
+```sh
 # --type: the type of original data (xml or json)
 # --annotation: the path of file, which contains the name of annotation files
 # --save-dir: the save path
@@ -92,81 +103,80 @@ python ./tools/generate_data_for_training.py
             --samples=-1
 ```
 
- 2. Image preprocessing  
- Image preprocessing subsystem includes operations such as image decoding, expanding, cropping, etc. We use `dataset.transform.operator` to unify the implementation, which is convenient for extension. In addition, multiple operators can be combined to form a complex processing pipeline, and used by data transformers in `dataset.transformer`, such as multi-threading to acclerate a complex image data processing.
-
- 3. Data transformer  
- The function of the data transformer is used to convert a `dataset.Dataset` to a new `dataset.Dataset`, for example: convert a jpeg image dataset into a decoded and resized dataset. We use the decorator pattern to implement different transformers which are all subclass of `dataset.Dataset`. For example, the `dataset.transform.paralle_map` transformer is for multi-process preprocessing, more transformers can be found in `dataset.transform.transformer`.
-
- 4. Data feeding apis  
-To facilitate data pipeline building and data feeding for training, we combine multiple `dataset.Dataset` to form a `dataset.Reader` which can provide data for training, validation and testing respectively. The user only needs to call `Reader.[train|eval|infer]` to get the corresponding data stream. `Reader` supports yaml file to configure data address, preprocessing oprators, acceleration mode, and so on.
-
-
+ 2. Image preprocessing
+the `dataset.transform.operator` module provides operations such as image
+decoding, expanding, cropping, etc. Multiple operators are combined to form
+larger processing pipelines.
+
+ 3. Data transformer
+Transform a `dataset.Dataset` to achieve various desired effects, Notably: the
+`dataset.transform.paralle_map` transformer accelerates image processing with
+multi-threads or multi-processes. More transformers can be found in
+`dataset.transform.transformer`.
+
+ 4. Data feeding apis
+To facilitate data pipeline building, we combine multiple `dataset.Dataset` to
+form a `dataset.Reader` which can provide data for training, validation and
+testing respectively. Users can simply call `Reader.[train|eval|infer]` to get
+the corresponding data stream. Many aspect of the `Reader`, such as storage
+location, preprocessing pipeline, acceleration mode can be configured with yaml
+files.
 
 The main APIs are as follows:
 
-
-
 1. Data parsing
 
- - `source/coco_loader.py`: Use to parse the COCO dataset. [detail code](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/coco_loader.py)
- - `source/voc_loader.py`: Use to parse the Pascal VOC dataset. [detail code](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/voc_loader.py)  
- [Note] When using VOC datasets, if you do not use the default label list, you need to generate `label_list.txt` using `tools/generate_data_for_training.py` (the usage method is same as generating the roidb data source) or provide `label_list.txt` in `data/pascalvoc/ImageSets/Main` firstly. Also set the parameter `use_default_label` to `false` in the configuration file.
- - `source/loader.py`: Use to parse the Roidb dataset. [detail code](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/loader.py)
+ - `source/coco_loader.py`: COCO dataset parser. [source](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/coco_loader.py)
+ - `source/voc_loader.py`: Pascal VOC dataset parser. [source](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/voc_loader.py)
+ [Note] To use a non-default label list for VOC datasets, a `label_list.txt`
+ file is needed, one can use the provided label list
+ (`data/pascalvoc/ImageSets/Main/label_list.txt`) or generate a custom one (with `tools/generate_data_for_training.py`). Also, `use_default_label` option should
+ be set to `false` in the configuration file
+ - `source/loader.py`: Roidb dataset parser. [source](https://github.com/PaddlePaddle/models/blob/develop/PaddleCV/object_detection/ppdet/data/source/loader.py)
 
 2. Operator
  `transform/operators.py`: Contains a variety of data enhancement methods, including:
-
-```  python
-RandomFlipImage: Horizontal flip.
-RandomDistort: Distort brightness, contrast, saturation, and hue.
-ResizeImage: Adjust the image size according to the specific interpolation method.
-RandomInterpImage: Use a random interpolation method to resize the image.
-CropImage: Crop image with respect to different scale, aspect ratio, and overlap.
-ExpandImage: Put the original image into a larger expanded image which is initialized using image mean.
-DecodeImage: Read images in RGB format.
-Permute: Arrange the channels of the image and converted to the BGR format.
-NormalizeImage: Normalize image pixel values.
-NormalizeBox: Normalize the bounding box.
-MixupImage: Mixup two images in proportion.
-```
-[Note] The mixup operation can refer to[paper](https://arxiv.org/pdf/1710.09412.pdf)。
-
-`transform/arrange_sample.py`: Sort the data which need to input the network.  
+- `DecodeImage`: Read images in RGB format.
+- `RandomFlipImage`: Horizontal flip.
+- `RandomDistort`: Distort brightness, contrast, saturation, and hue.
+- `ResizeImage`: Resize image with interpolation.
+- `RandomInterpImage`: Use a random interpolation method to resize the image.
+- `CropImage`: Crop image with respect to different scale, aspect ratio, and overlap.
+- `ExpandImage`: Pad image to a larger size, padding filled with mean image value.
+- `NormalizeImage`: Normalize image pixel values.
+- `NormalizeBox`: Normalize the bounding box.
+- `Permute`: Arrange the channels of the image and optionally convert image to BGR format.
+- `MixupImage`: Mixup two images with given fraction<sup>[1](#vd)</sup>.
+
+<a name="mix">[1]</a> Please refer to [this paper](https://arxiv.org/pdf/1710.09412.pdf)。
+
+`transform/arrange_sample.py`: Assemble the data samples needed by different models.
 3. Transformer
-`transform/post_map.py`: A pre-processing operation for completing batch data, which mainly includes:
-
-```  python
-Randomly adjust the image size of the batch data
-Multi-scale adjustment of image size
-Padding operation
-```
-`transform/transformer.py`: Used to filter useless data and return batch data.
-`transform/parallel_map.py`: Used to achieve acceleration.  
+`transform/post_map.py`: Transformations that operates on whole batches, mainly for:
+- Padding whole batch to given stride values
+- Resize images to Multi-scales
+- Randomly adjust the image size of the batch data
+`transform/transformer.py`: Data filtering batching.
+`transform/parallel_map.py`: Accelerate data processing with multi-threads/multi-processes.
 4. Reader
-`reader.py`: Used to combine source and transformer operations, and return batch data according to `max_iter`.
+`reader.py`: Combine source and transforms, return batch data according to `max_iter`.
 `data_feed.py`: Configure default parameters for `reader.py`.
 
 
-
-
-
 ### Usage
 
-#### Ordinary usage
-The function of this module is completed by combining the configuration information in the yaml file. The use of yaml files can be found in the configuration file section.
+#### Canned Datasets
 
- - Read data for training
+Preset for common datasets, e.g., `MS-COCO` and `Pascal Voc` are included. In
+most cases, user can simply use these canned dataset as is. Moreover, the
+whole data pipeline is fully customizable through the yaml configuration files.
 
-``` python
-ccfg = load_cfg('./config.yml')
-coco = Reader(ccfg.DATA, ccfg.TRANSFORM, maxiter=-1)
-```
-#### How to use customized dataset?
-- Option 1: Convert the dataset to the VOC format or COCO format.
-```python
- # In ./tools/, the code named labelme2coco.py is provided to convert
- # the dataset which is annotatedby Labelme to a COCO dataset.
+#### Custom Datasets
+
+- Option 1: Convert the dataset to COCO or VOC format.
+```sh
+ # a small utility (`tools/labelme2coco.py`) is provided to convert
+ # Labelme-annotated dataset to COCO format.
  python ./tools/labelme2coco.py --json_input_dir ./labelme_annos/
                                 --image_input_dir ./labelme_imgs/
                                 --output_dir ./cocome/
@@ -180,13 +190,14 @@ coco = Reader(ccfg.DATA, ccfg.TRANSFORM, maxiter=-1)
  # --val_proportion：The validation proportion of annatation data.
  # --test_proportion: The inference proportion of annatation data.
 ```
-- Option 2:
-
-1. Following the `./source/coco_loader.py` and `./source/voc_loader.py`, add `./source/XX_loader.py` and implement the `load` function.
-2. Add the entry for `./source/XX_loader.py` in the `load` function of `./source/loader.py`.
-3. Modify `./source/__init__.py`:
 
+- Option 2:
 
+1. Add `source/XX_loader.py` and implement the `load` function, following the
+   example of `source/coco_loader.py` and `source/voc_loader.py`.
+2. Modify the `load` function in `source/loader.py` to make use of the newly
+   added data loader.
+3. Modify `/source/__init__.py` accordingly.
 ```python
 if data_cf['type'] in ['VOCSource', 'COCOSource', 'RoiDbSource']:
     source_type = 'RoiDbSource'
@@ -194,9 +205,12 @@ if data_cf['type'] in ['VOCSource', 'COCOSource', 'RoiDbSource']:
 if data_cf['type'] in ['VOCSource', 'COCOSource', 'RoiDbSource', 'XXSource']:
     source_type = 'RoiDbSource'
 ```
-
-4. In the configure file, define the `type` of `dataset` as `XXSource`。  
+4. In the configure file, define the `type` of `dataset` as `XXSource`.
 
 #### How to add data pre-processing？
-- If you want to add the enhanced preprocessing of a single image, you can refer to the code of each class in `transform/operators.py`, and create a new class to implement new data enhancement. Also add the name of this preprocessing to the configuration file.
-- If you want to add image preprocessing for a single batch, you can refer to the code for each function in `build_post_map` of `transform/post_map.py`, and create a new internal function to implement new batch data preprocessing. Also add the name of this preprocessing to the configuration file.
+
+- To add pre-processing operation for a single image, refer to the classes in
+  `transform/operators.py`, and implement the desired transformation with a new
+  class.
+- To add pre-processing for a batch, one needs to modify the `build_post_map`
+  function in `transform/post_map.py`.

PaddleCV/object_detection/docs/GETTING_STARTED.md

 # Getting Started
 
-Please refer [installation instructions](INSTALL.md) to install PaddlePaddle and prepare dataset at first.
+For setting up the test environment, please refer to [installation
+instructions](INSTALL.md).
 
 
-## Train a Model
+## Training
+
+
+#### Single-GPU Training
 
-#### One-Device Training
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0
-# export CPU_NUM=1 # for CPU training
 python tools/train.py -c configs/faster_rcnn_r50_1x.yml
 ```
 
-#### Multi-Device Training
+#### Multi-GPU Training
+
 
 ```bash
-export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 # set devices
-# export CPU_NUM=8 # for CPU training
+export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
 python tools/train.py -c =configs/faster_rcnn_r50_1x.yml
 ```
 
-- Default dataset directory is `dataset/coco`, users also can specify it in the configure file.
-- Pretrained model will be downloaded automatically and saved at `~/.cache/paddle/weights`.
-- Model will be saved at  `output/faster_rcnn_r50_1x` by default, users also can specify it in the configure file.
-- All hyper parameters can refer input config.
-- Change config file for other models.
-- For more help, please run `python tools/train.py --help`.
+- Datasets is stored in `dataset/coco` by default (configurable).
+- Pretrained model is downloaded automatically and cached in `~/.cache/paddle/weights`.
+- Model checkpoints is saved in `output` by default (configurable).
+- To check out hyper parameters used, please refer to the config file.
 
+Alternating between training epoch and evaluation run is possible, simply pass
+in `--eval=True` to do so (tested with `SSD` detector on Pascal-VOC, not
+recommended for two stage models or training sessions on COCO dataset)
 
-For `SSD` on Pascal-VOC dataset,  set `--eval=True` to do evaluation during training.
-For other models based on COCO dataset, the evaluating during training is not fully verified, better to do evaluation after training.
 
-
-## Evaluate with Pretrained models.
+## Evaluation
 
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0
-# export CPU_NUM=1 # for CPU training
+# or run on CPU with:
+# export CPU_NUM=1
 python tools/eval.py -c configs/faster_rcnn_r50_1x.yml
 ```
 
-- The default model directory is `output/faster_rcnn_r50_1x`, you also can specify it.
-- For R-CNN and SSD models, do not support evaluating by multi-device now, we will enhanced it in next version.
-- For more help, please run `python tools/eval.py --help`.
+- Checkpoint is loaded from `output` by default (configurable)
+- Multi-GPU evaluation for R-CNN and SSD models is not supported at the
+moment, but it is a planned feature
+
 
+## Inference
 
-## Inference with Pretrained Models
 
-- Infer one image:
+- Run inference on a single image:
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0
-python tools/infer.py -c configs/faster_rcnn_r50_1x.yml --infer_img=demo/000000000139.jpg
+# or run on CPU with:
+# export CPU_NUM=1
+python tools/infer.py -c configs/faster_rcnn_r50_1x.yml --infer_img=demo/000000570688.jpg
 ```
 
-- Infer several images:
+- Batch inference:
 
 ```bash
 export CUDA_VISIBLE_DEVICES=0
+# or run on CPU with:
+# export CPU_NUM=1
 python tools/infer.py -c configs/faster_rcnn_r50_1x.yml --infer_dir=demo
 ```
 
-The predicted and visualized images are saved in `output` by default, users can change saved directory by specifying `--savefile=`.  For more help please run `python tools/infer.py --help`.
+The visualization files are saved in `output` by default, to specify a different
+path, simply add a `--save_file=` flag.
 
 
 ## FAQ
 
 
-Q: Why the loss may be NaN when using single GPU to train?
+Q: Why do I get `NaN` loss values during single GPU training?
 
-A: The default learning rate is adapt to multi-device training, when use single GPU and small batch size, you need to decrease `base_lr` by corresponding multiples.  
+A: The default learning rate is tuned to multi-GPU training (8x GPUs), it must
+be adapted for single GPU training accordingly (e.g., divide by 8).

PaddleCV/object_detection/docs/INSTALL.md

-# Installing PaddleDetection
+# Installation
 
 ---
 ## Table of Contents
@@ -12,22 +12,24 @@
 
 ## Introduction
 
-This document covers how to install PaddleDetection, its dependencies (including PaddlePaddle), and COCO and PASCAL VOC dataset.
+This document covers how to install PaddleDetection, its dependencies
+(including PaddlePaddle), together with COCO and PASCAL VOC dataset.
 
 For general information about PaddleDetection, please see [README.md](../README.md).
 
 
 ## PaddlePaddle
 
-Running PaddleDetection requires PaddelPaddle Fluid v.1.5 and later. please follow the installation instructions in [installation document](http://www.paddlepaddle.org/documentation/docs/en/1.4/beginners_guide/install/index_en.html).
+Running PaddleDetection requires PaddlePaddle Fluid v.1.5 and later. please follow the instructions in [installation document](http://www.paddlepaddle.org/documentation/docs/en/1.4/beginners_guide/install/index_en.html).
 
-Please make sure your PaddlePaddle installation was sucessful and the version of your PaddlePaddle is not lower than the version required. You can check PaddlePaddle installation with following commands.
+Please make sure your PaddlePaddle installation was successful and the version
+of your PaddlePaddle is not lower than required. Verify with the following commands.
 
 ```
 # To check if PaddlePaddle installation was sucessful
 python -c "from paddle.fluid import fluid; fluid.install_check.run_check()"
 
-# To print PaddlePaddle version
+# To check PaddlePaddle version
 python -c "import paddle; print(paddle.__version__)"
 ```
 
@@ -41,9 +43,9 @@ python -c "import paddle; print(paddle.__version__)"
 
 ## Other Dependencies
 
-**Install the [COCO-API](https://github.com/cocodataset/cocoapi):**
+[COCO-API](https://github.com/cocodataset/cocoapi):
 
-To train the model, COCO-API is needed. Installation is as follows:
+COCO-API is needed for training. Installation is as follows:
 
     git clone https://github.com/cocodataset/cocoapi.git
     cd cocoapi/PythonAPI
@@ -60,7 +62,8 @@ To train the model, COCO-API is needed. Installation is as follows:
 
 **Clone Paddle models repository:**
 
-You can clone Paddle models and change directory to PaddleDetection module with folloing commands:
+You can clone Paddle models and change working directory to PaddleDetection
+with the following commands:
 
 ```
 cd <path/to/clone/models>
@@ -68,15 +71,15 @@ git clone https://github.com/PaddlePaddle/models
 cd models/PaddleCV/object_detection
 ```
 
-**Install Python module requirements:**
+**Install Python dependencies:**
 
-Other python module requirements is set in [requirements.txt](../requirements.txt), you can install these requirements with folloing command:
+Required python packages are specified in [requirements.txt](./requirements.txt), and can be installed with:
 
 ```
 pip install -r requirements.txt
 ```
 
-**Check PaddleDetection architectures tests pass:**
+**Make sure the tests pass:**
 
 ```
 export PYTHONPATH=`pwd`:$PYTHONPATH
@@ -86,18 +89,22 @@ python ppdet/modeling/tests/test_architectures.py
 
 ## Datasets
 
-PaddleDetection support train/eval/infer models with dataset [MSCOCO](http://cocodataset.org) and [PASCAL VOC](http://host.robots.ox.ac.uk/pascal/VOC/), you can set up dataset as follows.
+PaddleDetection includes support for [MSCOCO](http://cocodataset.org) and [PASCAL VOC](http://host.robots.ox.ac.uk/pascal/VOC/) by default, please follow these instructions to set up the dataset.
 
-**Create symlinks for datasets:**
+**Create symlinks for local datasets:**
 
-Dataset default path in PaddleDetection config files is `dataset/coco` and `dataset/voc`, you can set symlinks for your COCO/COCO-like or VOC/VOC-like datasets with following commands:
+Default dataset path in config files is `data/coco` and `data/voc`, if the
+datasets are already available on disk, you can simply create symlinks to
+their directories:
 
 ```
-ln -sf <path/to/coco> $PaddleDetection/data/coco
-ln -sf <path/to/voc> $PaddleDetection/data/voc
+ln -sf <path/to/coco> <path/to/paddle_detection>/data/coco
+ln -sf <path/to/voc> <path/to/paddle_detection>/data/voc
 ```
 
-If you do not have datasets locally, you can download dataset as follows:
+**Download datasets manually:**
+
+On the other hand, to download the datasets, run the following commands:
 
 - MS-COCO
 
@@ -113,9 +120,14 @@ cd dataset/voc
 ./download.sh
 ```
 
-**Auto download datasets:**
+**Download datasets automatically:**
 
-If you set up models while `data/coc` and `data/voc` is not found, PaddleDetection will automaticaly download them from [MSCOCO-2017](http://images.cocodataset.org) and [VOC2012](http://host.robots.ox.ac.uk/pascal/VOC), the decompressed datasets will be places in `~/.cache/paddle/dataset/` and can be discovered automaticaly in the next setting up time.
+If a training session is started but the dataset is not setup properly (e.g,
+not found in `data/coc` or `data/voc`), PaddleDetection can automatically
+download them from [MSCOCO-2017](http://images.cocodataset.org) and
+[VOC2012](http://host.robots.ox.ac.uk/pascal/VOC), the decompressed datasets
+will be cached in `~/.cache/paddle/dataset/` and can be discovered automatically
+subsequently.
 
 
-**NOTE:** For further informations on the datasets, please see [DATASET.md](DATA.md)
+**NOTE:** For further informations on the datasets, please see [DATA.md](DATA.md)