beautifier image doc (#2101)

Author: WindQAQ

tensorflow_addons/image/color_ops.py

@@ -86,11 +86,11 @@ def equalize(
 
     Args:
       images: A tensor of shape
-          (num_images, num_rows, num_columns, num_channels) (NHWC), or
-          (num_images, num_channels, num_rows, num_columns) (NCHW), or
-          (num_rows, num_columns, num_channels) (HWC), or
-          (num_channels, num_rows, num_columns) (CHW), or
-          (num_rows, num_columns) (HW). The rank must be statically known (the
+          `(num_images, num_rows, num_columns, num_channels)` (NHWC), or
+          `(num_images, num_channels, num_rows, num_columns)` (NCHW), or
+          `(num_rows, num_columns, num_channels)` (HWC), or
+          `(num_channels, num_rows, num_columns)` (CHW), or
+          `(num_rows, num_columns)` (HW). The rank must be statically known (the
           shape is not `TensorShape(None)`).
       data_format: Either 'channels_first' or 'channels_last'
       name: The name of the op.
@@ -149,8 +149,8 @@ def sharpness(image: TensorLike, factor: Number) -> tf.Tensor:
 
     Args:
       images: A tensor of shape
-          (num_images, num_rows, num_columns, num_channels) (NHWC), or
-          (num_rows, num_columns, num_channels) (HWC)
+          `(num_images, num_rows, num_columns, num_channels)` (NHWC), or
+          `(num_rows, num_columns, num_channels)` (HWC)
       factor: A floating point value or Tensor above 0.0.
     Returns:
       Image(s) with the same type and shape as `images`, sharper.

tensorflow_addons/image/compose_ops.py

@@ -20,26 +20,28 @@
 
 
 def blend(image1: TensorLike, image2: TensorLike, factor: Number) -> tf.Tensor:
-    """Blend image1 and image2 using 'factor'.
+    """Blend `image1` and `image2` using `factor`.
 
-  Factor can be above 0.0.  A value of 0.0 means only image1 is used.
-  A value of 1.0 means only image2 is used.  A value between 0.0 and
-  1.0 means we linearly interpolate the pixel values between the two
-  images.  A value greater than 1.0 "extrapolates" the difference
-  between the two pixel values, and we clip the results to values
-  between 0 and 255.
+    Factor can be above 0.0.  A value of 0.0 means only `image1` is used.
+    A value of 1.0 means only `image2` is used.  A value between 0.0 and
+    1.0 means we linearly interpolate the pixel values between the two
+    images.  A value greater than 1.0 "extrapolates" the difference
+    between the two pixel values, and we clip the results to values
+    between 0 and 255.
 
-  Args:
-    image1: An image Tensor of shape (num_rows, num_columns,
-        num_channels) (HWC), or (num_rows, num_columns) (HW),
-        or (num_channels, num_rows, num_columns).
-    image2: An image Tensor of shape (num_rows, num_columns,
-        num_channels) (HWC), or (num_rows, num_columns) (HW),
-        or (num_channels, num_rows, num_columns).
-    factor: A floating point value or Tensor of type tf.float32 above 0.0.
+    Args:
+      image1: An image Tensor of shape
+          `(num_rows, num_columns, num_channels)` (HWC), or
+          `(num_rows, num_columns)` (HW), or
+          `(num_channels, num_rows, num_columns)` (CHW).
+      image2: An image Tensor of shape
+          `(num_rows, num_columns, num_channels)` (HWC), or
+          `(num_rows, num_columns)` (HW), or
+          `(num_channels, num_rows, num_columns)`.
+      factor: A floating point value or Tensor of type `tf.float32` above 0.0.
 
-  Returns:
-    A blended image Tensor of tf.float32.
+    Returns:
+      A blended image Tensor of `tf.float32`.
 
   """
     with tf.name_scope("blend"):

tensorflow_addons/image/connected_components.py

@@ -44,7 +44,7 @@ def connected_components(
     (which is the connectivity used here).
 
     Args:
-      images: A 2D (H, W) or 3D (N, H, W) Tensor of image (integer,
+      images: A 2D (H, W) or 3D (N, H, W) `Tensor` of image (integer,
       floating point and boolean types are supported).
       name: The name of the op.
 

tensorflow_addons/image/cutout_ops.py

@@ -54,18 +54,18 @@ def random_cutout(
 ) -> tf.Tensor:
     """Apply cutout (https://arxiv.org/abs/1708.04552) to images.
 
-    This operation applies a (mask_height x mask_width) mask of zeros to
-    a random location within `img`. The pixel values filled in will be of the
-    value `replace`. The located where the mask will be applied is randomly
-    chosen uniformly over the whole images.
+    This operation applies a `(mask_height x mask_width)` mask of zeros to
+    a random location within `images`. The pixel values filled in will be of
+    the value `replace`. The located where the mask will be applied is
+    randomly chosen uniformly over the whole images.
 
     Args:
       images: A tensor of shape
-        (batch_size, height, width, channels)
-        (NHWC), (batch_size, channels, height, width)(NCHW).
+        `(batch_size, height, width, channels)`
+        (NHWC), `(batch_size, channels, height, width)` (NCHW).
       mask_size: Specifies how big the zero mask that will be generated is that
         is applied to the images. The mask will be of size
-        (mask_height x mask_width). Note: mask_size should be divisible by 2.
+        `(mask_height x mask_width)`. Note: mask_size should be divisible by 2.
       constant_values: What pixel value to fill in the images in the area that has
         the cutout mask applied to it.
       seed: A Python integer. Used in combination with `tf.random.set_seed` to
@@ -76,9 +76,9 @@ def random_cutout(
         `(batch_size, ..., channels)` while `channels_first` corresponds to
         inputs with shape `(batch_size, channels, ...)`.
     Returns:
-      An image Tensor.
+      An image `Tensor`.
     Raises:
-      InvalidArgumentError: if mask_size can't be divisible by 2.
+      InvalidArgumentError: if `mask_size` can't be divisible by 2.
     """
     if data_format == "channels_first":
         warnings.warn(
@@ -112,18 +112,19 @@ def cutout(
 ) -> tf.Tensor:
     """Apply cutout (https://arxiv.org/abs/1708.04552) to images.
 
-    This operation applies a (mask_height x mask_width) mask of zeros to
-    a location within `img` specified by the offset. The pixel values filled in will be of the
-    value `replace`. The located where the mask will be applied is randomly
+    This operation applies a `(mask_height x mask_width)` mask of zeros to
+    a location within `images` specified by the offset.
+    The pixel values filled in will be of the value `replace`.
+    The located where the mask will be applied is randomly
     chosen uniformly over the whole images.
 
     Args:
-      images: A tensor of shape (batch_size, height, width, channels)
-        (NHWC), (batch_size, channels, height, width)(NCHW).
+      images: A tensor of shape `(batch_size, height, width, channels)`
+        (NHWC), `(batch_size, channels, height, width)` (NCHW).
       mask_size: Specifies how big the zero mask that will be generated is that
         is applied to the images. The mask will be of size
-        (mask_height x mask_width). Note: mask_size should be divisible by 2.
-      offset: A tuple of (height, width) or (batch_size, 2)
+        `(mask_height x mask_width)`. Note: mask_size should be divisible by 2.
+      offset: A tuple of `(height, width)` or `(batch_size, 2)`
       constant_values: What pixel value to fill in the images in the area that has
         the cutout mask applied to it.
       data_format: A string, one of `channels_last` (default) or `channels_first`.
@@ -134,7 +135,7 @@ def cutout(
     Returns:
       An image Tensor.
     Raises:
-      InvalidArgumentError: if mask_size can't be divisible by 2.
+      InvalidArgumentError: if `mask_size` can't be divisible by 2.
     """
     if data_format == "channels_first":
         warnings.warn(

tensorflow_addons/image/dense_image_warp.py

@@ -210,7 +210,7 @@ def dense_image_warp(
     `(b, j - flow[b, j, i, 0], i - flow[b, j, i, 1])`. For locations outside
     of the image, we use the nearest pixel values at the image boundary.
 
-    PLEASE NOTE: The definition of the flow field above is different from that
+    NOTE: The definition of the flow field above is different from that
     of optical flow. This function expects the negative forward flow from
     output image to source image. Given two images `I_1` and `I_2` and the
     optical flow `F_12` from `I_1` to `I_2`, the image `I_1` can be
@@ -221,15 +221,15 @@ def dense_image_warp(
       flow: A 4-D float `Tensor` with shape `[batch, height, width, 2]`.
       name: A name for the operation (optional).
 
-      Note that image and flow can be of type tf.half, tf.float32, or
-      tf.float64, and do not necessarily have to be the same type.
+      Note that image and flow can be of type `tf.half`, `tf.float32`, or
+      `tf.float64`, and do not necessarily have to be the same type.
 
     Returns:
       A 4-D float `Tensor` with shape`[batch, height, width, channels]`
         and same type as input image.
 
     Raises:
-      ValueError: if height < 2 or width < 2 or the inputs have the wrong
+      ValueError: if `height < 2` or `width < 2` or the inputs have the wrong
         number of dimensions.
     """
     with tf.name_scope(name or "dense_image_warp"):

tensorflow_addons/image/distance_transform.py

@@ -34,9 +34,10 @@ def euclidean_dist_transform(
     """Applies euclidean distance transform(s) to the image(s).
 
     Args:
-      images: A tensor of shape (num_images, num_rows, num_columns, 1) (NHWC),
-        or (num_rows, num_columns, 1) (HWC) or (num_rows, num_columns) (HW).
-      dtype: DType of the output tensor.
+      images: A tensor of shape `(num_images, num_rows, num_columns, 1)`
+        (NHWC), or `(num_rows, num_columns, 1)` (HWC) or
+        `(num_rows, num_columns)` (HW).
+      dtype: `tf.dtypes.DType` of the output tensor.
       name: The name of the op.
 
     Returns:

tensorflow_addons/image/distort_image_ops.py

@@ -43,20 +43,20 @@ def random_hsv_in_yiq(
 
     Args:
       image: RGB image or images. Size of the last dimension must be 3.
-      max_delta_hue: float. Maximum value for the random delta_hue. Passing 0
+      max_delta_hue: `float`. Maximum value for the random delta_hue. Passing 0
         disables adjusting hue.
-      lower_saturation: float. Lower bound for the random scale_saturation.
-      upper_saturation: float. Upper bound for the random scale_saturation.
-      lower_value: float. Lower bound for the random scale_value.
-      upper_value: float. Upper bound for the random scale_value.
+      lower_saturation: `float`. Lower bound for the random scale_saturation.
+      upper_saturation: `float`. Upper bound for the random scale_saturation.
+      lower_value: `float`. Lower bound for the random scale_value.
+      upper_value: `float`. Upper bound for the random scale_value.
       seed: An operation-specific seed. It will be used in conjunction
         with the graph-level seed to determine the real seeds that will be
         used in this operation. Please see the documentation of
         set_random_seed for its interaction with the graph-level random seed.
       name: A name for this operation (optional).
 
     Returns:
-      3-D float tensor of shape `[height, width, channels]`.
+      3-D float `Tensor` of shape `[height, width, channels]`.
 
     Raises:
       ValueError: if `max_delta`, `lower_saturation`, `upper_saturation`,
@@ -122,9 +122,9 @@ def adjust_hsv_in_yiq(
 
     Args:
       image: RGB image or images. Size of the last dimension must be 3.
-      delta_hue: float, the hue rotation amount, in radians.
-      scale_saturation: float, factor to multiply the saturation by.
-      scale_value: float, factor to multiply the value by.
+      delta_hue: `float`, the hue rotation amount, in radians.
+      scale_saturation: `float`, factor to multiply the saturation by.
+      scale_value: `float`, factor to multiply the value by.
       name: A name for this operation (optional).
 
     Returns:

tensorflow_addons/image/interpolate_spline.py

@@ -23,14 +23,15 @@
 def _cross_squared_distance_matrix(x: TensorLike, y: TensorLike) -> tf.Tensor:
     """Pairwise squared distance between two (batch) matrices' rows (2nd dim).
 
-    Computes the pairwise distances between rows of x and rows of y
+    Computes the pairwise distances between rows of x and rows of y.
+
     Args:
-      x: [batch_size, n, d] float `Tensor`
-      y: [batch_size, m, d] float `Tensor`
+      x: `[batch_size, n, d]` float `Tensor`.
+      y: `[batch_size, m, d]` float `Tensor`.
 
     Returns:
-      squared_dists: [batch_size, n, m] float `Tensor`, where
-      squared_dists[b,i,j] = ||x[b,i,:] - y[b,j,:]||^2
+      squared_dists: `[batch_size, n, m]` float `Tensor`, where
+      `squared_dists[b,i,j] = ||x[b,i,:] - y[b,j,:]||^2`.
     """
     x_norm_squared = tf.reduce_sum(tf.square(x), 2)
     y_norm_squared = tf.reduce_sum(tf.square(y), 2)
@@ -52,14 +53,14 @@ def _pairwise_squared_distance_matrix(x: TensorLike) -> tf.Tensor:
     """Pairwise squared distance among a (batch) matrix's rows (2nd dim).
 
     This saves a bit of computation vs. using
-    _cross_squared_distance_matrix(x,x)
+    `_cross_squared_distance_matrix(x, x)`
 
     Args:
-      x: `[batch_size, n, d]` float `Tensor`
+      x: `[batch_size, n, d]` float `Tensor`.
 
     Returns:
       squared_dists: `[batch_size, n, n]` float `Tensor`, where
-      squared_dists[b,i,j] = ||x[b,i,:] - x[b,j,:]||^2
+      `squared_dists[b,i,j] = ||x[b,i,:] - x[b,j,:]||^2`.
     """
 
     x_x_transpose = tf.matmul(x, x, adjoint_b=True)
@@ -83,17 +84,17 @@ def _solve_interpolation(
     order: int,
     regularization_weight: FloatTensorLike,
 ) -> TensorLike:
-    """Solve for interpolation coefficients.
+    r"""Solve for interpolation coefficients.
 
     Computes the coefficients of the polyharmonic interpolant for the
-    'training' data defined by (train_points, train_values) using the kernel
-    phi.
+    'training' data defined by `(train_points, train_values)` using the kernel
+    $\phi$.
 
     Args:
-      train_points: `[b, n, d]` interpolation centers
-      train_values: `[b, n, k]` function values
-      order: order of the interpolation
-      regularization_weight: weight to place on smoothness regularization term
+      train_points: `[b, n, d]` interpolation centers.
+      train_values: `[b, n, k]` function values.
+      order: order of the interpolation.
+      regularization_weight: weight to place on smoothness regularization term.
 
     Returns:
       w: `[b, n, k]` weights on each interpolation center
@@ -173,15 +174,15 @@ def _apply_interpolation(
     interpolated function values at query_points.
 
     Args:
-      query_points: `[b, m, d]` x values to evaluate the interpolation at
+      query_points: `[b, m, d]` x values to evaluate the interpolation at.
       train_points: `[b, n, d]` x values that act as the interpolation centers
-                      ( the c variables in the wikipedia article)
-      w: `[b, n, k]` weights on each interpolation center
-      v: `[b, d, k]` weights on each input dimension
-      order: order of the interpolation
+          (the c variables in the wikipedia article).
+      w: `[b, n, k]` weights on each interpolation center.
+      v: `[b, d, k]` weights on each input dimension.
+      order: order of the interpolation.
 
     Returns:
-      Polyharmonic interpolation evaluated at points defined in query_points.
+      Polyharmonic interpolation evaluated at points defined in `query_points`.
     """
 
     # First, compute the contribution from the rbf term.
@@ -207,11 +208,11 @@ def _phi(r: FloatTensorLike, order: int) -> FloatTensorLike:
     See https://en.wikipedia.org/wiki/Polyharmonic_spline for the definition.
 
     Args:
-      r: input op
-      order: interpolation order
+      r: input op.
+      order: interpolation order.
 
     Returns:
-      phi_k evaluated coordinate-wise on r, for k = r
+      `phi_k` evaluated coordinate-wise on `r`, for `k = r`.
     """
 
     # using EPSILON prevents log(0), sqrt0), etc.

tensorflow_addons/image/resampler_ops.py

@@ -33,13 +33,13 @@ def resampler(
     The resampler currently only supports bilinear interpolation of 2D data.
 
     Args:
-      data: Tensor of shape `[batch_size, data_height, data_width,
+      data: `Tensor` of shape `[batch_size, data_height, data_width,
         data_num_channels]` containing 2D data that will be resampled.
       warp: Tensor of minimum rank 2 containing the coordinates at
       which resampling will be performed. Since only bilinear
       interpolation is currently supported, the last dimension of the
-      `warp` tensor must be 2, representing the (x, y) coordinate where
-      x is the index for width and y is the index for height.
+      `warp` tensor must be 2, representing the `(x, y)` coordinate where
+      `x` is the index for width and `y` is the index for height.
       name: Optional name of the op.
     Returns:
       Tensor of resampled values from `data`. The output tensor shape