add chinese version api of natural robustness

docs/api/api_python/mindarmour.natural_robustness.transform.image.rst

@@ -0,0 +1,143 @@
+mindarmour.natural_robustness.transform.image
+=============================================
+
+本模块包含图像的自然扰动方法。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Contrast(alpha=1, beta=0, auto_param=False)
+
+    图像的对比度。
+
+    参数：
+        - **alpha** (Union[float, int]) - 控制图像的对比度。:math:`out\_image = in\_image*alpha+beta`。建议值范围[0.2, 2]。
+        - **beta** (Union[float, int]) - 补充alpha的增量。默认值：0。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.GradientLuminance(color_start=(0, 0, 0), color_end=(255, 255, 255), start_point=(10, 10), scope=0.5, pattern='light', bright_rate=0.3, mode='circle', auto_param=False)
+
+    渐变调整图片的亮度。
+
+    参数：
+        - **color_start** (union[tuple, list]) - 渐变中心的颜色。默认值：（0,0,0）。
+        - **color_end** (union[tuple, list]) - 渐变边缘的颜色。默认值：（255,255,255）。
+        - **start_point** (union[tuple, list]) - 渐变中心的二维坐标。
+        - **scope** (float) - 渐变的范围。值越大，渐变范围越大。默认值：0.3。
+        - **pattern** (str) - 深色或浅色，此值必须在['light', 'dark']中。
+        - **bright_rate** (float) - 控制亮度。值越大，梯度范围越大。如果参数`pattern`为'light'，建议值范围为[0.1, 0.7]，如果参数`pattern`为'dark'，建议值范围为[0.1, 0.9]。
+        - **mode** (str) - 渐变模式，值必须在['circle', 'horizontal', 'vertical']中。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.GaussianBlur(ksize=2, auto_param=False)
+
+    使用高斯模糊滤镜模糊图像。
+
+    参数：
+        - **ksize** (int) - 高斯核的大小，必须为非负数。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.MotionBlur(degree=5, angle=45, auto_param=False)
+
+    运动模糊。
+
+    参数：
+        - **degree** (int) - 模糊程度。必须为正值。建议取值范围[1, 15]。
+        - **angle** (union[float, int]) - 运动模糊的方向。angle=0表示上下运动模糊。角度为逆时针方向。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+
+.. py:class:: mindarmour.natural_robustness.transform.image.GradientBlur(point, kernel_num=3, center=True, auto_param=False)
+
+    渐变模糊。
+
+    参数：
+        - **point** (union[tuple, list]) - 模糊中心点的二维坐标。
+        - **kernel_num** (int) - 模糊核的数量。建议取值范围[1, 8]。
+        - **center** (bool) - 指定中心点模糊或指定中心点清晰。默认值：True。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.UniformNoise(factor=0.1, auto_param=False)
+
+    图像添加均匀噪声。
+
+    参数：
+        - **factor** (float) - 噪声密度，单位像素区域添加噪声的比例。建议取值范围：[0.001, 0.15]。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.GaussianNoise(factor=0.1, auto_param=False)
+
+    图像添加高斯噪声。
+
+    参数：
+        - **factor** (float) - 噪声密度，单位像素区域添加噪声的比例。建议取值范围：[0.001, 0.15]。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.SaltAndPepperNoise(factor=0, auto_param=False)
+
+    图像添加椒盐噪声。
+
+    参数：
+        - **factor** (float) - 噪声密度，单位像素区域添加噪声的比例。建议取值范围：[0.001, 0.15]。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.NaturalNoise(ratio=0.0002, k_x_range=(1, 5), k_y_range=(3, 25), auto_param=False)
+
+    图像添加自然噪声。
+
+    参数：
+        - **factor** (float) - 噪声密度，单位像素区域添加噪声的比例。建议取值范围：[0.00001, 0.001]。
+        - **k_x_range** (union[list, tuple]) - 噪声块长度的取值范围。
+        - **k_y_range** (union[list, tuple]) - 噪声块宽度的取值范围。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Translate(x_bias=0, y_bias=0, auto_param=False)
+
+    图像平移。
+
+    参数：
+        - **x_bias** (Union[int, float]) - X方向平移，x = x + x_bias*图像长度。建议取值范围在[-0.1, 0.1]中。
+        - **y_bias** (Union[int, float]) - Y方向平移，y = y + y_bias*图像长度。建议取值范围在[-0.1, 0.1]中。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Scale(factor_x=1, factor_y=1, auto_param=False)
+
+    图像缩放。
+
+    参数：
+        - **factor_x** (Union[float, int]) - 在X方向缩放，x=factor_x*x。建议取值范围在[0.5, 1]且abs(factor_y - factor_x) < 0.5。
+        - **factor_y** (Union[float, int]) - 沿Y方向缩放，y=factor_y*y。建议取值范围在[0.5, 1]且abs(factor_y - factor_x) < 0.5。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Shear(factor=0.2, direction='horizontal', auto_param=False)
+
+    图像错切，错切后图像和原图的映射关系为：(new_x, new_y) = (x+factor_x*y, factor_y*x+y)。错切后图像将重新缩放到原图大小。
+
+    参数：
+        - **factor** (Union[float, int]) - 沿错切方向上的错切比例。建议值范围[0.05, 0.5]。
+        - **direction** (str) - 形变方向。可选值为'vertical'或'horizontal'。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Rotate(angle=20, auto_param=False)
+
+    围绕图像中心点逆时针旋转图像。
+
+    参数：
+        - **angle** (Union[float, int]) - 逆时针旋转的度数。建议值范围[-60, 60]。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Perspective(ori_pos, dst_pos, auto_param=False)
+
+    透视变换。
+
+    参数：
+        - **ori_pos** (list) - 原始图像中的四个点的坐标。
+        - **dst_pos** (list) - 对应的ori_pos中4个点透视变换后的点坐标。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。
+
+.. py:class:: mindarmour.natural_robustness.transform.image.Curve(curves=3, depth=10, mode='vertical', auto_param=False)
+
+    使用Sin函数的曲线变换。
+
+    参数：
+        - **curves** (union[float, int]) - 曲线周期数。建议取值范围[0.1, 5]。
+        - **depth** (union[float, int]) - sin函数的幅度。建议取值不超过图片长度的1/10。
+        - **mode** (str) - 形变方向。可选值'vertical'或'horizontal'。
+        - **auto_param** (bool) - 自动选择参数。在保留图像的语义的范围内自动选择参数。默认值：False。

mindarmour/natural_robustness/transform/image/blur.py

@@ -33,6 +33,7 @@ class GaussianBlur(_NaturalPerturb):
     Args:
         ksize (int): Size of gaussian kernel, this value must be non-negnative.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -77,6 +78,7 @@ class MotionBlur(_NaturalPerturb):
         angle (union[float, int]): Direction of motion blur. Angle=0 means up and down motion blur. Angle is
             counterclockwise.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -131,6 +133,7 @@ class GradientBlur(_NaturalPerturb):
         kernel_num (int): Number of blur kernels. Suggested value range in [1, 8].
         center (bool): Blurred or clear at the center of a specified point.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('xx.png')

mindarmour/natural_robustness/transform/image/corruption.py

@@ -34,6 +34,7 @@ class UniformNoise(_NaturalPerturb):
         factor (float): Noise density, the proportion of noise points per unit pixel area. Suggested value range in
             [0.001, 0.15].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -79,6 +80,7 @@ class GaussianNoise(_NaturalPerturb):
         factor (float): Noise density, the proportion of noise points per unit pixel area. Suggested value range in
             [0.001, 0.15].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -123,6 +125,7 @@ class SaltAndPepperNoise(_NaturalPerturb):
         factor (float): Noise density, the proportion of noise points per unit pixel area. Suggested value range in
             [0.001, 0.15].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -171,6 +174,7 @@ class NaturalNoise(_NaturalPerturb):
         k_x_range (union[list, tuple]): Value range of the noise block length.
         k_y_range (union[list, tuple]): Value range of the noise block width.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('xx.png')

mindarmour/natural_robustness/transform/image/luminance.py

@@ -36,6 +36,7 @@ class Contrast(_NaturalPerturb):
             Suggested value range in [0.2, 2].
         beta (Union[float, int]): Delta added to alpha. Default: 0.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -212,6 +213,7 @@ class GradientLuminance(_NaturalPerturb):
             range in [0.1, 0.9].
         mode (str): Gradient mode, value must be in ['circle', 'horizontal', 'vertical'].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('x.png')

mindarmour/natural_robustness/transform/image/transformation.py

@@ -36,6 +36,7 @@ class Translate(_NaturalPerturb):
         y_bias (Union[int, float]): Y-direction translation,  y = y + y_bias*image_length. Suggested value range
             in [-0.1, 0.1].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -83,6 +84,7 @@ class Scale(_NaturalPerturb):
         factor_y (Union[float, int]): Rescale in Y-direction, y=factor_y*y. Suggested value range in [0.5, 1] and
             abs(factor_y - factor_x) < 0.5.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -123,13 +125,14 @@ class Scale(_NaturalPerturb):
 
 class Shear(_NaturalPerturb):
     """
-    Shear an image, for each pixel (x, y) in the sheared image, the new value is taken from a position
-    (x+factor_x*y, factor_y*x+y) in the origin image. Then the sheared image will be rescaled to fit original size.
+    Shear an image, the mapping between sheared image and origin image is (new_x, new_y) = (x+factor_x*y, factor_y*x+y).
+    Then the sheared image will be rescaled to fit original size.
 
     Args:
         factor (Union[float, int]): Shear rate in shear direction. Suggested value range in [0.05, 0.5].
         direction (str): Direction of deformation. Optional value is 'vertical' or 'horizontal'.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -185,6 +188,7 @@ class Rotate(_NaturalPerturb):
     Args:
         angle (Union[float, int]): Degrees of counter clockwise. Suggested value range in [-60, 60].
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -239,6 +243,7 @@ class Perspective(_NaturalPerturb):
         ori_pos (list): Four points in original image.
         dst_pos (list): The point coordinates of the 4 points in ori_pos after perspective transformation.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('1.png')
@@ -292,12 +297,12 @@ class Curve(_NaturalPerturb):
     Curve picture using sin method.
 
     Args:
-        curves (union[float, int]): Divide width to curves of `2*math.pi`, which means how many curve cycles. Suggested
-            value range in [0.1. 5].
+        curves (union[float, int]): Number of curve cycles. Suggested value range in [0.1, 5].
         depth (union[float, int]): Amplitude of sin method. Suggested value not exceed 1/10 of the length of the
             picture.
         mode (str): Direction of deformation. Optional value is 'vertical' or 'horizontal'.
         auto_param (bool): Auto selected parameters. Selected parameters will preserve semantics of image.
+            Default: False.
 
     Examples:
         >>> img = cv2.imread('x.png')