Add sphinx docs

albumentations-team · Jun 19, 2018 · 778ce0e · 778ce0e
1 parent 528f1a0
commit 778ce0e
Show file tree

Hide file tree

Showing 16 changed files with 447 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -79,6 +79,24 @@ pip install -e .[tests]
 pytest
 ```
 
+## Building the documentation
+1. Go to `docs/` directory
+```
+cd docs
+```
+2. Install required libraries
+```
+pip install -r requirements.txt
+```
+3. Build html files
+```
+make html
+```
+4. Open `_build/html/index.html` in browser.
+
+Alternatively, you can start a web server that rebuilds the documentation
+automatically when a change is detected by running `make livehtml`
+
 
 ### Roadmap:
  - [ ] add tests

diff --git a/albumentations/augmentations/functional.py b/albumentations/augmentations/functional.py
@@ -158,13 +158,13 @@ def motion_blur(img, ksize):
 
 
 def optical_distortion(img, k=0, dx=0, dy=0, interpolation=cv2.INTER_LINEAR, border_mode=cv2.BORDER_REFLECT_101):
-    """
-    unconventional augment
-    https://stackoverflow.com/questions/6199636/formulas-for-barrel-pincushion-distortion
-    https://stackoverflow.com/questions/10364201/image-transformation-in-opencv
-    https://stackoverflow.com/questions/2477774/correcting-fisheye-distortion-programmatically
-    http://www.coldvision.io/2017/03/02/advanced-lane-finding-using-opencv/
-    barrel\pincushion distortion
+    """Barrel / pincushion distortion. Unconventional augment.
+
+    Reference:
+        |  https://stackoverflow.com/questions/6199636/formulas-for-barrel-pincushion-distortion
+        |  https://stackoverflow.com/questions/10364201/image-transformation-in-opencv
+        |  https://stackoverflow.com/questions/2477774/correcting-fisheye-distortion-programmatically
+        |  http://www.coldvision.io/2017/03/02/advanced-lane-finding-using-opencv/
     """
     height, width = img.shape[:2]
     k = k * 0.00001
@@ -186,8 +186,8 @@ def optical_distortion(img, k=0, dx=0, dy=0, interpolation=cv2.INTER_LINEAR, bor
 def grid_distortion(img, num_steps=10, xsteps=[], ysteps=[], interpolation=cv2.INTER_LINEAR,
                     border_mode=cv2.BORDER_REFLECT_101):
     """
-    http://pythology.blogspot.sg/2014/03/interpolation-on-regular-distorted-grid.html
-    grid distortion
+    Reference:
+        http://pythology.blogspot.sg/2014/03/interpolation-on-regular-distorted-grid.html
     """
     height, width = img.shape[:2]
 
@@ -231,12 +231,12 @@ def grid_distortion(img, num_steps=10, xsteps=[], ysteps=[], interpolation=cv2.I
 def elastic_transform_fast(image, alpha, sigma, alpha_affine, interpolation=cv2.INTER_LINEAR,
                            border_mode=cv2.BORDER_REFLECT_101, random_state=None):
     """Elastic deformation of images as described in [Simard2003]_ (with modifications).
+    Based on https://gist.github.com/erniejunior/601cdf56d2b424757de5
+
     .. [Simard2003] Simard, Steinkraus and Platt, "Best Practices for
          Convolutional Neural Networks applied to Visual Document Analysis", in
          Proc. of the International Conference on Document Analysis and
          Recognition, 2003.
-
-     Based on https://gist.github.com/erniejunior/601cdf56d2b424757de5
     """
     if random_state is None:
         random_state = np.random.RandomState(1234)

diff --git a/albumentations/augmentations/transforms.py b/albumentations/augmentations/transforms.py
@@ -16,7 +16,8 @@ class VerticalFlip(DualTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask, bboxes.
+    Targets:
+        image, mask, bboxes
     """
 
     def apply(self, img, **params):
@@ -32,7 +33,8 @@ class HorizontalFlip(DualTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask, bboxes.
+    Targets:
+        image, mask, bboxes
     """
 
     def apply(self, img, **params):
@@ -48,7 +50,8 @@ class Flip(DualTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def apply(self, img, d=0, **params):
@@ -72,7 +75,8 @@ class Transpose(DualTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def apply(self, img, **params):
@@ -85,7 +89,8 @@ class RandomRotate90(DualTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def apply(self, img, factor=0, **params):
@@ -115,7 +120,8 @@ class Rotate(DualTransform):
             Default: cv2.BORDER_REFLECT_101
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def __init__(self, limit=90, interpolation=cv2.INTER_LINEAR, border_mode=cv2.BORDER_REFLECT_101, p=.5):
@@ -150,7 +156,8 @@ class ShiftScaleRotate(DualTransform):
             Default: cv2.BORDER_REFLECT_101
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def __init__(self, shift_limit=0.0625, scale_limit=0.1, rotate_limit=45, interpolation=cv2.INTER_LINEAR,
@@ -180,7 +187,8 @@ class CenterCrop(DualTransform):
         width (int): width of the crop.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def __init__(self, height, width, p=0.5):
@@ -277,7 +285,8 @@ class HueSaturationValue(ImageOnlyTransform):
             will be (-val_shift_limit, val_shift_limit). Default: 20.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, hue_shift_limit=20, sat_shift_limit=30, val_shift_limit=20, p=0.5):
@@ -297,9 +306,9 @@ def get_params(self):
 
 
 class RGBShift(ImageOnlyTransform):
-    """"Randomly shifts values for each channel of the input RGB image.
+    """Randomly shifts values for each channel of the input RGB image.
 
-     Args:
+    Args:
         r_shift_limit ((int, int) or int): range for changing values for the red channel. If r_shift_limit is a single
             int, the range will be (-r_shift_limit, r_shift_limit). Default: 20.
         g_shift_limit ((int, int) or int): range for changing values for the green channel. If g_shift_limit is a
@@ -308,7 +317,8 @@ class RGBShift(ImageOnlyTransform):
             int, the range will be (-b_shift_limit, b_shift_limit). Default: 20.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, r_shift_limit=20, g_shift_limit=20, b_shift_limit=20, p=0.5):
@@ -329,12 +339,13 @@ def get_params(self):
 class RandomBrightness(ImageOnlyTransform):
     """Randomly changes brightness of the input image.
 
-     Args:
+    Args:
         limit ((float, float) or float): factor range for changing brightness. If limit is a single float, the range
             will be (-limit, limit). Default: 0.2.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, limit=0.2, p=0.5):
@@ -351,12 +362,13 @@ def get_params(self):
 class RandomContrast(ImageOnlyTransform):
     """Randomly changes contrast of the input image.
 
-     Args:
+    Args:
         limit ((float, float) or float): factor range for changing contrast. If limit is a single float, the range
             will be (-limit, limit). Default: 0.2.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, limit=.2, p=.5):
@@ -373,11 +385,12 @@ def get_params(self):
 class Blur(ImageOnlyTransform):
     """Blurs the input image using a random-sized kernel.
 
-     Args:
+    Args:
         blur_limit (int): maximum kernel size for blurring the input image. Default: 7.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, blur_limit=7, p=.5):
@@ -396,11 +409,12 @@ def get_params(self):
 class MotionBlur(Blur):
     """Applies motion blur to the input image using a random-sized kernel.
 
-     Args:
+    Args:
         blur_limit (int): maximum kernel size for blurring the input image. Default: 7.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def apply(self, img, ksize=9, **params):
@@ -410,11 +424,12 @@ def apply(self, img, ksize=9, **params):
 class MedianBlur(Blur):
     """Blurs the input image using using a median filter with a random aperture linear size.
 
-     Args:
+    Args:
         blur_limit (int): maximum aperture linear size for blurring the input image. Default: 7.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def apply(self, image, ksize=3, **params):
@@ -429,7 +444,8 @@ class GaussNoise(ImageOnlyTransform):
             will be (-var_limit, var_limit). Default: (10, 50).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, var_limit=(10, 50), p=.5):
@@ -450,10 +466,11 @@ class CLAHE(ImageOnlyTransform):
 
     Args:
         clip_limit (float): upper threshold value for contrast limiting. Default: 4.0.
-        tile_grid_size ((int, int)): size of grid for histogram equalization. Default: (8, 8).
+            tile_grid_size ((int, int)): size of grid for histogram equalization. Default: (8, 8).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, clip_limit=4.0, tile_grid_size=(8, 8), p=0.5):
@@ -474,7 +491,8 @@ class ChannelShuffle(ImageOnlyTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def apply(self, img, **params):
@@ -487,7 +505,8 @@ class InvertImg(ImageOnlyTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def apply(self, img, **params):
@@ -501,7 +520,8 @@ class ToGray(ImageOnlyTransform):
     Args:
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def apply(self, img, **params):

diff --git a/albumentations/imgaug/transforms.py b/albumentations/imgaug/transforms.py
@@ -37,7 +37,8 @@ class IAAEmboss(ImageOnlyIAATransform):
         strength ((float, float)): strength range of the embossing. Default: (0.2, 0.7).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, alpha=(0.2, 0.5), strength=(0.2, 0.7), p=0.5):
@@ -55,7 +56,8 @@ class IAASuperpixels(ImageOnlyIAATransform):
         n_segments (int): target number of superpixels to generate. Default: 100.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, p_replace=0.1, n_segments=100, p=0.5):
@@ -72,7 +74,8 @@ class IAASharpen(ImageOnlyIAATransform):
         lightness ((float, float)): range to choose the lightness of the sharpened image. Default: (0.5, 1.0).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, alpha=(0.2, 0.5), lightness=(0.5, 1.), p=0.5):
@@ -89,7 +92,8 @@ class IAAAdditiveGaussianNoise(ImageOnlyIAATransform):
             Default: (0.01 * 255, 0.05 * 255).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image.
+    Targets:
+        image
     """
 
     def __init__(self, loc=0, scale=(0.01 * 255, 0.05 * 255), p=0.5):
@@ -107,7 +111,8 @@ class IAAPiecewiseAffine(DualIAATransform):
         nb_columns (int): number of columns of points that the regular grid should have. Default: 4.
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def __init__(self, scale=(0.03, 0.05), nb_rows=4, nb_cols=4, p=.5):
@@ -123,7 +128,8 @@ class IAAPerspective(DualIAATransform):
             the random distances of the subimage's corners from the full image's corners. Default: (0.05, 0.1).
         p (float): probability of applying the transform. Default: 0.5.
 
-    Targets: image, mask.
+    Targets:
+        image, mask
     """
 
     def __init__(self, scale=(0.05, 0.1), p=.5):

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = albumentations
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+livehtml:
+	sphinx-autobuild -b html --ignore "*.text" "$(SOURCEDIR)" "$(BUILDDIR)"
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)