update docs about augmentor and tfutils

docs/modules/dataflow.imgaug.rst

@@ -2,11 +2,37 @@ tensorpack.dataflow.imgaug package
 ==================================
 
 This package contains Tensorpack's augmentors.
+The imgaug module is designed to allow the following usage:
+
+1. Factor out randomness and determinism.
+   An augmentor may be randomized, but you can call
+   `augment_return_params <#tensorpack.dataflow.imgaug.Augmentor.augment_return_params>`_
+   to obtain the randomized parameters and then call
+   `augment_with_params <#tensorpack.dataflow.imgaug.Augmentor.augment_with_params>`_
+   on other data with the same randomized parameters.
+
+2. Because of (1), tensorpack's augmentor can augment multiple images together
+   easily. This is commonly used for augmenting an image together with its masks.
+
+3. An image augmentor (e.g. flip) may also augment a coordinate, with
+   `augment_coords <#tensorpack.dataflow.imgaug.ImageAugmentor.augment_coords>`_.
+   In this way, images can be augmented together with
+   boxes, polygons, keypoints, etc.
+   Coordinate augmentation enforces floating points coordinates
+   to avoid quantization error.
+
+4. Reset random seed. Random seed can be reset by
+   `reset_state <#tensorpack.dataflow.imgaug.Augmentor.reset_state>`_.
+   This is important for multi-process data loading, and
+   it is called automatically if you use tensorpack's
+   `image augmentation dataflow <dataflow.html#tensorpack.dataflow.AugmentImageComponent>`_.
+
 Note that other image augmentation libraries can be wrapped into Tensorpack's interface as well.
 For example, `imgaug.IAAugmentor <#tensorpack.dataflow.imgaug.IAAugmentor>`_
 and `imgaug.Albumentations <#tensorpack.dataflow.imgaug.Albumentations>`_
 wrap two popular image augmentation libraries.
 
+
 .. container:: custom-index
 
     .. raw:: html

docs/modules/tfutils.rst

@@ -7,6 +7,14 @@ tensorpack.tfutils package
 
         <script type="text/javascript" src='../_static/build_toc_group.js'></script>
 
+tensorpack.tfutils.argscope module
+------------------------------------
+
+.. automodule:: tensorpack.tfutils.argscope
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 tensorpack.tfutils.collection module
 ------------------------------------
 
@@ -87,11 +95,18 @@ tensorpack.tfutils.varreplace module
     :undoc-members:
     :show-inheritance:
 
+tensorpack.tfutils.export module
+------------------------------------
+
+.. automodule:: tensorpack.tfutils.export
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Other functions in tensorpack.tfutils module
 ---------------------------------------------
 
 .. automethod:: tensorpack.tfutils.get_default_sess_config
 .. automethod:: tensorpack.tfutils.get_global_step_var
 .. automethod:: tensorpack.tfutils.get_global_step_value
-.. automethod:: tensorpack.tfutils.argscope
-.. automethod:: tensorpack.tfutils.get_arg_scope
+.. automethod:: tensorpack.tfutils.get_tf_version_tuple

docs/tutorial/extend/augmentor.md

+### Design of Tensorpack's imgaug Module
+
+The [imgaug module](../../modules/dataflow.imgaug.html) is designed to allow the following usage:
+
+1. Factor out randomness and determinism.
+   An augmentor may be randomized, but you can call
+   [augment_return_params](../../modules/dataflow.imgaug.html#tensorpack.dataflow.imgaug.Augmentor.augment_return_params)
+   to obtain the randomized parameters and then call
+   [augment_with_params](../../modules/dataflow.imgaug.html#tensorpack.dataflow.imgaug.Augmentor.augment_with_params)
+   on other data with the same randomized parameters.
+
+2. Because of (1), tensorpack's augmentor can augment multiple images together
+   easily. This is commonly used for augmenting an image together with its masks.
+
+3. An image augmentor (e.g. flip) may also augment a coordinate, with
+   [augment_coords](../../modules/dataflow.imgaug.html#tensorpack.dataflow.imgaug.ImageAugmentor.augment_coords).
+   In this way, images can be augmented together with
+   boxes, polygons, keypoints, etc.
+   Coordinate augmentation enforces floating points coordinates
+   to avoid quantization error.
+
+4. Reset random seed. Random seed can be reset by
+   [reset_state](../../modules/dataflow.imgaug.html#tensorpack.dataflow.imgaug.Augmentor.reset_state).
+   This is important for multi-process data loading, and
+   it is called automatically if you use tensorpack's 
+   [image augmentation dataflow](../../modules/dataflow.html#tensorpack.dataflow.AugmentImageComponent).
 
 ### Write an Image Augmentor
 
@@ -8,17 +34,20 @@ to do whatever operations to your data, rather than writing an augmentor.
 Augmentors just sometimes make things easier.
 
 An image augmentor maps an image to an image.
-If you have such a mapping function `f` already, you can simply use `imgaug.MapImage(f)` as the
-augmentor, or use `MapDataComponent(dataflow, f, index)` as the DataFlow.
+If you have such a mapping function `f` already, you can simply use
+[imgaug.MapImage(f)](../../modules/dataflow.imgaug.html#tensorpack.dataflow.imgaug.MapImage)
+as the augmentor, or use
+[MapDataComponent(dataflow, f, index)](../../modules/dataflow.html#tensorpack.dataflow.MapDataComponent)
+as the DataFlow.
 In other words, for simple mapping you do not need to write an augmentor.
 
 An augmentor may do something more than just applying a mapping.
-The interface you will need to implement is:
+To do complicated augmentation, the interface you will need to implement is:
 
 ```python
 class MyAug(imgaug.ImageAugmentor):
   def _get_augment_params(self, img):
-    # generated random params with self.rng
+    # Generated random params with self.rng
     return params
 
   def _augment(self, img, params):
@@ -29,16 +58,3 @@ class MyAug(imgaug.ImageAugmentor):
     # coords is a Nx2 floating point array, each row is (x, y)
     return augmented_coords
 ```
-
-It does the following extra things for you:
-
-1. `self.rng` is a `np.random.RandomState` object,
-  guaranteed to have different seeds when you use multiprocess prefetch.
-  In multiprocess settings, you have to use this rng to generate random numbers.
-
-2. The logic of random parameter generation and the actual augmentation is separated in different methods.
-  This allows you to apply the
-  same transformation to several images together (with `AugmentImageComponents`),
-  which is essential to tasks such as segmentation.
-  Or apply the same transformations to images plus coordinate labels (with `AugmentImageCoordinates`),
-  which is essential to tasks such as detection and localization.

examples/FasterRCNN/eval.py

@@ -15,7 +15,7 @@ import tqdm
 import tensorflow as tf
 
 from tensorpack.callbacks import Callback
-from tensorpack.tfutils import get_tf_version_tuple
+from tensorpack.tfutils.common import get_tf_version_tuple
 from tensorpack.utils import logger
 from tensorpack.utils.utils import get_tqdm
 

tensorpack/dataflow/imgaug/base.py

@@ -36,6 +36,9 @@ class Augmentor(object):
         """
         Perform augmentation on the data.
 
+        Args:
+            d: input data
+
         Returns:
             augmented data
         """
@@ -45,8 +48,10 @@ class Augmentor(object):
     def augment_return_params(self, d):
         """
         Augment the data and return the augmentation parameters.
-        The returned parameters can be used to augment another data with identical transformation.
-        This can be used in, e.g. augmentation for image, masks, keypoints altogether.
+        If the augmentation is non-deterministic (random),
+        the returned parameters can be used to augment another data with the identical transformation.
+        This can be used for, e.g. augmenting image, masks, keypoints altogether with the
+        same transformation.
 
         Returns:
             (augmented data, augmentation params)
@@ -64,6 +69,10 @@ class Augmentor(object):
         """
         Augment the data with the given param.
 
+        Args:
+            d: input data
+            param: augmentation params returned by :meth:`augment_return_params`
+
         Returns:
             augmented data
         """
@@ -137,6 +146,8 @@ class ImageAugmentor(Augmentor):
 
         Args:
             coords: Nx2 floating point numpy array where each row is (x, y)
+            param: augmentation params returned by :meth:`augment_return_params`
+
         Returns:
             new coords
         """

tensorpack/dataflow/imgaug/meta.py

@@ -145,6 +145,8 @@ class MapImage(ImageAugmentor):
         """
         Args:
             func: a function which takes an image array and return an augmented one
+            coord_func: optional. A function which takes coordinates and return augmented ones.
+                Coordinates have the same format as :func:`ImageAugmentor.augment_coords`.
         """
         super(MapImage, self).__init__()
         self.func = func

tensorpack/tfutils/argscope.py

@@ -72,7 +72,9 @@ def enable_argscope_for_function(func, log_shape=True):
     """Decorator for function to support argscope
 
     Example:
+
         .. code-block:: python
+
             from mylib import myfunc
             myfunc = enable_argscope_for_function(myfunc)
 
@@ -113,7 +115,9 @@ def enable_argscope_for_module(module, log_shape=True):
     It has been only tested to work well with `tf.layers` module.
 
     Example:
+
         .. code-block:: python
+
             import tensorflow as tf
             enable_argscope_for_module(tf.layers)
 

tensorpack/tfutils/export.py

@@ -87,10 +87,18 @@ class ModelExporter(object):
                        signature_name='prediction_pipeline'):
         """
         Converts a checkpoint and graph to a servable for TensorFlow Serving.
-        Use SavedModelBuilder to export a trained model without tensorpack dependency.
+        Use TF's `SavedModelBuilder` to export a trained model without tensorpack dependency.
 
-        Remarks:
+        Args:
+            filename (str): path for export directory
+            tags (list): list of user specified tags
+            signature_name (str): name of signature for prediction
+
+        Note:
             This produces
+
+            .. code-block:: none
+
                 variables/       # output from the vanilla Saver
                     variables.data-?????-of-?????
                     variables.index
@@ -98,11 +106,6 @@ class ModelExporter(object):
 
             Currently, we only support a single signature, which is the general PredictSignatureDef:
             https://github.com/tensorflow/serving/blob/master/tensorflow_serving/g3doc/signature_defs.md
-
-        Args:
-            filename (str): path for export directory
-            tags (list): list of user specified tags
-            signature_name (str): name of signature for prediction
         """
 
         self.graph = self.config._maybe_create_graph()

tensorpack/tfutils/sessinit.py

@@ -219,7 +219,8 @@ class DictRestore(SessionInit):
 
 
 class ChainInit(SessionInit):
-    """ Initialize a session by a list of :class:`SessionInit` instance, executed one by one.
+    """
+    Initialize a session by a list of :class:`SessionInit` instance, executed one by one.
     This can be useful for, e.g., loading several models from different files
     to form a composition of models.
     """