Barrel and Pincushion distortions are added.

augly/image/__init__.py

@@ -13,6 +13,8 @@
     contrast,
     convert_color,
     crop,
+    distort_barrel,
+    distort_pincushion,
     encoding_quality,
     grayscale,
     hflip,
@@ -50,6 +52,8 @@
     contrast_intensity,
     convert_color_intensity,
     crop_intensity,
+    distort_barrel_intensity,
+    distort_pincushion_intensity,
     encoding_quality_intensity,
     grayscale_intensity,
     hflip_intensity,
@@ -86,6 +90,8 @@
     Contrast,
     ConvertColor,
     Crop,
+    DistortBarrel,
+    DistortPincushion,
     EncodingQuality,
     Grayscale,
     HFlip,
@@ -131,6 +137,8 @@
     "Contrast",
     "ConvertColor",
     "Crop",
+    "DistortBarrel",
+    "DistortPincushion",
     "EncodingQuality",
     "Grayscale",
     "HFlip",
@@ -173,6 +181,8 @@
     "contrast",
     "convert_color",
     "crop",
+    "distort_barrel",
+    "distort_pincushion",
     "encoding_quality",
     "grayscale",
     "hflip",
@@ -207,6 +217,8 @@
     "contrast_intensity",
     "convert_color_intensity",
     "crop_intensity",
+    "distort_barrel_intensity",
+    "distort_pincushion_intensity",
     "encoding_quality_intensity",
     "grayscale_intensity",
     "hflip_intensity",

augly/image/functional.py

@@ -621,6 +621,172 @@ def crop(
     return imutils.ret_and_save_image(aug_image, output_path)
 
 
+def distort_barrel(
+    image: Union[str, Image.Image],
+    output_path: Optional[str] = None,
+    a: float = 0.0,
+    b: float = 0.0,
+    c: float = 0.0,
+    d: float = 1.0,
+    metadata: Optional[List[Dict[str, Any]]] = None,
+    bboxes: Optional[List[Tuple]] = None,
+    bbox_format: Optional[str] = None,
+) -> Image.Image:
+    """
+    Applies barrel distortion to the image with the following equation.
+
+    To see effects of the coefficients in detail refer to
+    https://legacy.imagemagick.org/Usage/distorts/#barrel.
+    Below is a direct quotation from the document describing how barrel distortion
+    parameter works.
+
+    >   The values basically form a distortion equation such that...
+
+            Rsrc = r * ( A*r3 + B*r2 + C*r + D )
+
+        Where "r" is the destination radius and "Rsrc" is the source pixel to get the
+        pixel color from. the radii are normalized so that radius = '1.0' for the half
+        minimum width or height of the input image. This may seem reversed but that is
+        because the Reverse Pixel Mapping technique is used to ensure complete coverage
+        of the resulting image.
+
+    Setting A = B = C = 0 and D = 1 results in no change in the input image. Negative
+    values of A, B and C will result in reverse barrel effect closer to pincushion
+    effect.
+
+    @param image: the path to an image or a variable of type PIL.Image.Image
+        to be augmented
+
+    @param output_path: the path in which the resulting image will be stored.
+        If None, the resulting PIL Image will still be returned
+
+    @param a: Coefficient A in the equation Rsrc(r). Larger values results in more
+        barrel effect, has higher effect than b and c.
+
+    @param b: Coefficient B in the equation Rsrc(r). Larger values results in more
+        barrel effect, has lower effect than a and higher effect than c.
+
+    @param c: Coefficient C in the equation Rsrc(r). Larger values results in more
+        barrel effect, has lower effect than a and b.
+
+    @param d: Coefficient D in the equation Rsrc(r). Controls the overall scaling of the
+        image. In a positive domain, values larger than 1 will shrink the image. Negative
+        values would result in both vertically and horizontally flipped image scaled in a
+        mirrored way of positive domain.
+
+    @param metadata: if set to be a list, metadata about the function execution
+        including its name, the source & dest width, height, etc. will be appended
+        to the inputted list. If set to None, no metadata will be appended or returned
+
+    @param bboxes: a list of bounding boxes can be passed in here if desired. If
+        provided, this list will be modified in place such that each bounding box is
+        transformed according to this function
+
+    @param bbox_format: signifies what bounding box format was used in `bboxes`. Must
+        specify `bbox_format` if `bboxes` is provided. Supported bbox_format values are
+        "pascal_voc", "pascal_voc_norm", "coco", and "yolo"
+
+    @returns: the augmented PIL Image
+    """
+    image = imutils.validate_and_load_image(image).convert("RGB")
+    func_kwargs = imutils.get_func_kwargs(metadata, locals())
+
+    aug_image = imutils.distort(
+        image=image,
+        method="barrel",
+        distortion_args=(a, b, c, d),
+    )
+
+    imutils.get_metadata(
+        metadata=metadata,
+        function_name="distort_barrel",
+        aug_image=aug_image,
+        **func_kwargs,
+    )
+
+    return imutils.ret_and_save_image(aug_image, output_path)
+
+
+def distort_pincushion(
+    image: Union[str, Image.Image],
+    output_path: Optional[str] = None,
+    a: float = 0.0,
+    b: float = 0.0,
+    c: float = 0.0,
+    d: float = 1.0,
+    metadata: Optional[List[Dict[str, Any]]] = None,
+    bboxes: Optional[List[Tuple]] = None,
+    bbox_format: Optional[str] = None,
+) -> Image.Image:
+    """
+    To see effects of the coefficients in detail refer to
+    https://legacy.imagemagick.org/Usage/distorts/#barrelinverse. Below is a direct
+    quotation from the document describing how pincushion (barrel inverse)
+    distortion parameter works.
+
+    >   The 'BarrelInverse' distortion method is very similar to the previous
+    Barrel Distortion distortion method, and in fact takes the same set of arguments.
+    However the formula that is applied is slightly different, with the main part of
+    the equation dividing the radius. that is the Equation has been inverted.
+
+        Rsrc = r / ( A*r3 + B*r2 + C*r + D )
+
+        NOTE: This equation does NOT produce the 'reverse' the 'Barrel' distortion.
+        You can NOT use it to 'undo' the previous distortion.
+
+    @param image: the path to an image or a variable of type PIL.Image.Image
+        to be augmented
+
+    @param output_path: the path in which the resulting image will be stored.
+        If None, the resulting PIL Image will still be returned
+
+    @param a: Coefficient A in the equation Rsrc(r). Larger values results in more
+        pincushion effect, has higher effect than b and c.
+
+    @param b: Coefficient B in the equation Rsrc(r). Larger values results in more
+        pincushion effect, has lower effect than a and higher effect than c.
+
+    @param c: Coefficient C in the equation Rsrc(r). Larger values results in more
+        pincushion effect, has lower effect than a and b.
+
+    @param d: Coefficient D in the equation Rsrc(r). Controls the overall scaling of
+        the image. In a positive domain, values larger than 1 will enlarge the image
+        (zoomed in). Negative values would result in both vertically and horizontally
+        flipped image scaled in a mirrored way of positive domain.
+
+    @param metadata: if set to be a list, metadata about the function execution
+        including its name, the source & dest width, height, etc. will be appended
+        to the inputted list. If set to None, no metadata will be appended or returned
+
+    @param bboxes: a list of bounding boxes can be passed in here if desired. If
+        provided, this list will be modified in place such that each bounding box is
+        transformed according to this function
+
+    @param bbox_format: signifies what bounding box format was used in `bboxes`. Must
+        specify `bbox_format` if `bboxes` is provided. Supported bbox_format values are
+        "pascal_voc", "pascal_voc_norm", "coco", and "yolo"
+
+    @returns: the augmented PIL Image
+    """
+    image = imutils.validate_and_load_image(image).convert("RGB")
+    func_kwargs = imutils.get_func_kwargs(metadata, locals())
+
+    aug_image = imutils.distort(
+        image=image,
+        method="barrel_inverse",
+        distortion_args=(a, b, c, d),
+    )
+
+    imutils.get_metadata(
+        metadata=metadata,
+        function_name="distort_pincushion",
+        aug_image=aug_image,
+        **func_kwargs,
+    )
+
+    return imutils.ret_and_save_image(aug_image, output_path)
+
+
 def encoding_quality(
     image: Union[str, Image.Image],
     output_path: Optional[str] = None,

augly/image/intensity.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # Copyright (c) Facebook, Inc. and its affiliates.
 
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional, Union, Tuple
 
 import augly.image.utils as imutils
 import numpy as np
@@ -100,6 +100,14 @@ def crop_intensity(metadata: Dict[str, Any], **kwargs) -> float:
     return resize_intensity_helper(metadata)
 
 
+def distort_barrel_intensity(a: float, b: float, c: float, d: float, **kwargs) -> float:
+    return distort_intensity_helper(coefficients=(a, b, c), scale=d)
+
+
+def distort_pincushion_intensity(a: float, b: float, c: float, d: float, **kwargs) -> float:
+    return distort_intensity_helper(coefficients=(a, b, c), scale=d)
+
+
 def encoding_quality_intensity(quality: int, **kwargs):
     assert (
         isinstance(quality, int) and 0 <= quality <= 100
@@ -320,6 +328,13 @@ def normalize_mult_factor(factor: float) -> float:
     return factor if factor >= 1 else 1 / factor
 
 
+def distort_intensity_helper(coefficients: Tuple[float, float, float], scale: float) -> float:
+    coefficients_magnitude = np.abs(coefficients).sum()
+    adjusted_scale = np.exp(-(scale-1)**2)
+    intensity = 100 * (coefficients_magnitude / adjusted_scale)
+    return float(np.clip(intensity, 0, 100))
+
+
 def mult_factor_intensity_helper(factor: float) -> float:
     factor = normalize_mult_factor(factor)
     max_factor = 10