add docs for image aug - object detection

Author: zsdonghao

docs/modules/prepro.rst

@@ -220,6 +220,45 @@ Greyscale erosion
 Object detection
 -------------------
 
+Tutorial for Image Aug
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Hi, here is an example for image augmentation on VOC dataset.
+
+.. code-block:: python
+
+  ## download the VOC dataset
+  imgs_file_list, imgs_semseg_file_list, imgs_insseg_file_list, imgs_ann_file_list, \
+      classes, classes_in_person, classes_dict,\
+      n_objs_list, objs_info_list, objs_info_dicts = tl.files.load_voc_dataset(dataset="2012", contain_classes_in_person=False)
+
+  ## parse the annotation into list format
+  ann_list = []
+  for info in objs_info_list:
+      ann = tl.prepro.parse_darknet_ann_str_to_list(info)
+      c, b = tl.prepro.parse_darknet_ann_list_to_cls_box(ann)
+      ann_list.append([c, b])
+
+  ## different types of image augmentation
+  image = tl.vis.read_image(imgs_file_list[idx])
+  tl.vis.draw_boxes_and_labels_to_image(image, ann_list[idx][0], ann_list[idx][1], [], classes, True, save_name='_im_original.png')
+
+  im_flip, coords = tl.prepro.obj_box_left_right_flip(image, coords=ann_list[idx][1], is_rescale=True, is_center=True, is_random=False)
+  tl.vis.draw_boxes_and_labels_to_image(im_flip, ann_list[idx][0], coords, [], classes, True, save_name='_im_flip.png')
+
+  im_resize, coords = tl.prepro.obj_box_imresize(image, coords=ann_list[idx][1], size=[300, 200], is_rescale=True)
+  tl.vis.draw_boxes_and_labels_to_image(im_resize, ann_list[idx][0], coords, [], classes, True, save_name='_im_resize.png')
+
+  im_crop, clas, coords = tl.prepro.obj_box_crop(image, classes=ann_list[idx][0], coords=ann_list[idx][1], wrg=200, hrg=200, is_rescale=True, is_center=True, is_random=False)
+  tl.vis.draw_boxes_and_labels_to_image(im_crop, clas, coords, [], classes, True, save_name='_im_crop.png')
+
+  im_shfit, clas, coords = tl.prepro.obj_box_shift(image, classes=ann_list[idx][0], coords=ann_list[idx][1], wrg=0.1, hrg=0.1, is_rescale=True, is_center=True, is_random=False)
+  tl.vis.draw_boxes_and_labels_to_image(im_shfit, clas, coords, [], classes, True, save_name='_im_shift.png')
+
+  im_zoom, clas, coords = tl.prepro.obj_box_zoom(image, classes=ann_list[idx][0], coords=ann_list[idx][1], zoom_range=(1.3, 0.7), is_rescale=True, is_center=True, is_random=False)
+  tl.vis.draw_boxes_and_labels_to_image(im_zoom, clas, coords, [], classes, True, save_name='_im_zoom.png')
+
+
 Coordinate pixel unit to percentage
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. autofunction:: obj_box_coord_rescale

tensorlayer/files.py

@@ -708,10 +708,10 @@ def load_celebA_dataset(dirpath='data'):
     return data_files
 
 def load_voc_dataset(path='data/VOC', dataset='2012', contain_classes_in_person=False):
-    """Pascal VOC 2012 Dataset has 20 objects ``"aeroplane", "bicycle", "bird",
+    """ Pascal VOC 2012 Dataset has 20 objects "aeroplane", "bicycle", "bird",
         "boat", "bottle", "bus", "car", "cat", "chair", "cow", "diningtable",
         "dog", "horse", "motorbike", "person", "pottedplant", "sheep", "sofa",
-        "train", "tvmonitor"`` and additional 3 classes ``"head", "hand", "foot"``
+        "train", "tvmonitor"`` and additional 3 classes ``"head", "hand", "foot"
         for person.
 
     Parameters
@@ -746,6 +746,32 @@ def load_voc_dataset(path='data/VOC', dataset='2012', contain_classes_in_person=
         ``{imgs_file_list : dictionary for annotation}``, the annotation of all images in ``imgs_file_list``,
         format from `TensorFlow/Models/object-detection <https://github.com/tensorflow/models/blob/master/object_detection/create_pascal_tf_record.py>`_.
 
+    Examples
+    ----------
+    >>> imgs_file_list, imgs_semseg_file_list, imgs_insseg_file_list, imgs_ann_file_list, \
+    ... classes, classes_in_person, classes_dict,\
+    ... n_objs_list, objs_info_list, objs_info_dicts = tl.files.load_voc_dataset(dataset="2012", contain_classes_in_person=False)
+    >>> idx = 26
+    >>> print(classes)
+    ... ['aeroplane', 'bicycle', 'bird', 'boat', 'bottle', 'bus', 'car', 'cat', 'chair', 'cow', 'diningtable', 'dog', 'horse', 'motorbike', 'person', 'pottedplant', 'sheep', 'sofa', 'train', 'tvmonitor']
+    >>> print(classes_dict)
+    ... {'sheep': 16, 'horse': 12, 'bicycle': 1, 'bottle': 4, 'cow': 9, 'sofa': 17, 'car': 6, 'dog': 11, 'cat': 7, 'person': 14, 'train': 18, 'diningtable': 10, 'aeroplane': 0, 'bus': 5, 'pottedplant': 15, 'tvmonitor': 19, 'chair': 8, 'bird': 2, 'boat': 3, 'motorbike': 13}
+    >>> print(imgs_file_list[idx])
+    ... data/VOC/VOC2012/JPEGImages/2007_000423.jpg
+    >>> print(n_objs_list[idx])
+    ... 2
+    >>> print(imgs_ann_file_list[idx])
+    ... data/VOC/VOC2012/Annotations/2007_000423.xml
+    >>> print(objs_info_list[idx])
+    ... 14 0.173 0.461333333333 0.142 0.496
+    ... 14 0.828 0.542666666667 0.188 0.594666666667
+    >>> ann = tl.prepro.parse_darknet_ann_str_to_list(objs_info_list[idx])
+    >>> print(ann)
+    ... [[14, 0.173, 0.461333333333, 0.142, 0.496], [14, 0.828, 0.542666666667, 0.188, 0.594666666667]]
+    >>> c, b = tl.prepro.parse_darknet_ann_list_to_cls_box(ann)
+    >>> print(c, b)
+    ... [14, 14] [[0.173, 0.461333333333, 0.142, 0.496], [0.828, 0.542666666667, 0.188, 0.594666666667]]
+
     References
     -------------
     - `Pascal VOC2012 Website <http://host.robots.ox.ac.uk/pascal/VOC/voc2012/#devkit>`_.