Extend image blending module

.travis.yml

@@ -54,8 +54,8 @@ before_script:
   #- flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
 
 script:
-  - python -m pytest --verbose --xdoctest-modules --ignore="test/run_all.py" -s --durations=50
-  - coverage run --source imgaug -m pytest --verbose --xdoctest-modules --ignore="test/run_all.py"
+  - python -m pytest --verbose --xdoctest-modules --ignore="test/run_all.py" -s --durations=50 -Walways
+  - coverage run --source imgaug -m pytest --verbose --xdoctest-modules --ignore="test/run_all.py" -Walways
 
 
 after_success:

changelogs/master/20200107_improved_blending.md

@@ -0,0 +1,96 @@
+# More Choices for Image Blending #462 #556
+
+The available augmenters for alpha-blending of images were
+significantly extended. There are now new blending
+augmenters available to alpha-blend acoording to:
+* Some randomly chosen colors. (`BlendAlphaSomeColors`)
+* Linear gradients. (`BlendAlphaHorizontalLinearGradient`,
+  `BlendAlphaVerticalLinearGradient`)
+* Regular grids and checkerboard patterns. (`BlendAlphaRegularGrid`,
+  `BlendAlphaCheckerboard`)
+* Only at locations that overlap with specific segmentation class
+  IDs (or the inverse of that). (`BlendAlphaSegMapClassIds`)
+* Only within bounding boxes with specific labels (or the inverse
+  of that). (`BlendAlphaBoundingBoxes`)
+
+This allows to e.g. randomly remove some colors while leaving
+other colors unchanged (`BlendAlphaSomeColors(Grayscale(1.0))`),
+to change the color of some objects
+(`BlendAlphaSegMapClassIds(AddToHue((-256, 256)))`), to add
+cloud-patterns only to the top of images
+(`BlendAlphaVerticalLinearGradient(Clouds())`) or to apply
+augmenters in some coarse rectangular areas (e.g.
+`BlendAlphaRegularGrid(Multiply(0.0))` to achieve a similar
+effect to `CoarseDropout` or
+`BlendAlphaRegularGrid(AveragePooling(8))` to pool in equally
+coarse image sub-regions).
+
+Other mask-based alpha blending techniques can be achieved by
+subclassing `IBatchwiseMaskGenerator` and providing an
+instance of such a class to `BlendAlphaMask`.
+
+This patch also changes the naming of the blending augmenters
+as follows:
+* `Alpha` -> `BlendAlpha`
+* `AlphaElementwise` -> `BlendAlphaElementwise`
+* `SimplexNoiseAlpha` -> `BlendAlphaSimplexNoise`
+* `FrequencyNoiseAlpha` -> `BlendAlphaFrequencyNoise`
+The old names are now deprecated.
+Furthermore, the parameters `first` and `second`, which were
+used by all blending augmenters, have now the names `foreground`
+and `background`.
+
+List of changes:
+* Added `imgaug.augmenters.blend.BlendAlphaMask`, which uses
+  a mask generator instance to generate per batch alpha masks and
+  then alpha-blends using these masks.
+* Added `imgaug.augmenters.blend.BlendAlphaSomeColors`.
+* Added `imgaug.augmenters.blend.BlendAlphaHorizontalLinearGradient`.
+* Added `imgaug.augmenters.blend.BlendAlphaVerticalLinearGradient`.
+* Added `imgaug.augmenters.blend.BlendAlphaRegularGrid`.
+* Added `imgaug.augmenters.blend.BlendAlphaCheckerboard`.
+* Added `imgaug.augmenters.blend.BlendAlphaSegMapClassIds`.
+* Added `imgaug.augmenters.blend.BlendAlphaBoundingBoxes`.
+* Added `imgaug.augmenters.blend.IBatchwiseMaskGenerator`,
+  an interface for classes generating masks on a batch-by-batch
+  basis.
+* Added `imgaug.augmenters.blend.StochasticParameterMaskGen`,
+  a helper to generate masks from `StochasticParameter` instances.
+* Added `imgaug.augmenters.blend.SomeColorsMaskGen`, a generator
+  that produces masks marking randomly chosen colors in images.
+* Added `imgaug.augmenters.blend.HorizontalLinearGradientMaskGen`,
+  a linear gradient mask generator.
+* Added `imgaug.augmenters.blend.VerticalLinearGradientMaskGen`,
+  a linear gradient mask generator.
+* Added `imgaug.augmenters.blend.RegularGridMaskGen`,
+  a checkerboard-like mask generator where every grid cell has
+  a random alpha value.
+* Added `imgaug.augmenters.blend.CheckerboardMaskGen`,
+  a checkerboard-like mask generator where every grid cell has
+  the opposite alpha value of its 4-neighbours.
+* Added `imgaug.augmenters.blend.SegMapClassIdsMaskGen`, a
+  segmentation map-based mask generator.
+* Added `imgaug.augmenters.blend.BoundingBoxesMaskGen`, a bounding
+  box-based mask generator.
+* Added `imgaug.augmenters.blend.InvertMaskGen`, an mask generator
+  that inverts masks produces by child generators.
+* Changed `imgaug.parameters.SimplexNoise` and
+  `imgaug.parameters.FrequencyNoise` to also accept `(H, W, C)`
+  sampling shapes, instead of only `(H, W)`.
+* Refactored `AlphaElementwise` to be a wrapper around
+  `BlendAlphaMask`.
+* Renamed `Alpha` to `BlendAlpha`.
+  `Alpha` is now deprecated.
+* Renamed `AlphaElementwise` to `BlendAlphaElementwise`.
+  `AlphaElementwise` is now deprecated.
+* Renamed `SimplexNoiseAlpha` to `BlendAlphaSimplexNoise`.
+  `SimplexNoiseAlpha` is now deprecated.
+* Renamed `FrequencyNoiseAlpha` to `BlendAlphaFrequencyNoise`.
+  `FrequencyNoiseAlpha` is now deprecated.
+* Renamed arguments `first` and `second` to `foreground` and `background`
+  in `BlendAlpha`, `BlendAlphaElementwise`, `BlendAlphaSimplexNoise` and
+  `BlendAlphaFrequencyNoise`.
+* Changed `imgaug.parameters.handle_categorical_string_param()` to allow
+  parameter `valid_values` to be `None`.
+* Fixed a wrong error message in
+  `imgaug.augmenters.color.change_colorspace_()`.

changelogs/master/added/20191019_colorwise_grayscaling.md

@@ -1,8 +1,4 @@
-# Colorwise Grayscaling #462
+# Added `RemoveSaturation` #462
 
 * Added `RemoveSaturation`, a shortcut for `MultiplySaturation((0.0, 1.0))`
   with outputs similar to `Grayscale((0.0, 1.0))`.
-* Added `GrayscaleColorwise`, which applies grayscaling to randomly
-  picked colors in the image.
-* Added `RemoveSaturationColorwise`, which applies color saturation removal
-  to randomy picked colors in the image.

checks/check_blendalphasegmapclassids.py

@@ -0,0 +1,35 @@
+from __future__ import print_function, division, absolute_import
+import imageio
+import imgaug as ia
+import imgaug.augmenters as iaa
+
+
+def main():
+    aug = iaa.BlendAlphaMask(
+        iaa.SegMapClassIdsMaskGen(1),
+        iaa.OneOf([
+            iaa.TotalDropout(1.0),
+            iaa.AveragePooling(8)
+        ])
+    )
+
+    aug2 = iaa.BlendAlphaSegMapClassIds(
+        1, iaa.OneOf([
+            iaa.TotalDropout(1.0),
+            iaa.AveragePooling(8)
+        ])
+    )
+
+    image = ia.quokka(0.25)
+    segmap = ia.quokka_segmentation_map(0.25)
+
+    images_aug, segmaps_aug = aug(images=[image]*25,
+                                  segmentation_maps=[segmap]*25)
+    ia.imshow(ia.draw_grid(images_aug, cols=5, rows=5))
+
+    images_aug, segmaps_aug = aug2(images=[image]*25,
+                                  segmentation_maps=[segmap]*25)
+    ia.imshow(ia.draw_grid(images_aug, cols=5, rows=5))
+
+if __name__ == "__main__":
+    main()

checks/check_grayscale_colorwise.py → checks/check_blendalphasomecolors.py

@@ -1,9 +1,23 @@
+from __future__ import print_function, division, absolute_import
+import imageio
 import imgaug as ia
 import imgaug.augmenters as iaa
-import imageio
 
 
 def main():
+    aug = iaa.BlendAlphaMask(
+        iaa.SomeColorsMaskGen(),
+        iaa.OneOf([
+            iaa.TotalDropout(1.0),
+            iaa.AveragePooling(8)
+        ])
+    )
+
+    aug2 = iaa.BlendAlphaSomeColors(iaa.OneOf([
+            iaa.TotalDropout(1.0),
+            iaa.AveragePooling(8)
+    ]))
+
     urls = [
         ("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/"
          "Sarcophilus_harrisii_taranna.jpg/"
@@ -21,12 +35,10 @@ def main():
          "Dutch_-_Flower_Still_Life_-_Google_Art_Project.jpg")
     ]
 
-    image = imageio.imread(urls[1])
-
-    aug = iaa.GrayscaleColorwise(10, 0.1, alpha=[0.0, 1.0])
-    images_aug = aug(images=[image] * (5*5))
-
-    ia.imshow(ia.draw_grid(images_aug))
+    for url in urls:
+        img = imageio.imread(url)
+        ia.imshow(ia.draw_grid(aug(images=[img]*25), cols=5, rows=5))
+        ia.imshow(ia.draw_grid(aug2(images=[img]*25), cols=5, rows=5))
 
 
 if __name__ == "__main__":