dataset API docstring: Update transforms and vision desc and examples.

Add ImageBatchFormat to init.

mindspore/dataset/transforms/c_transforms.py

@@ -36,6 +36,16 @@ class OneHot(cde.OneHotOp):
 
     Raises:
         RuntimeError: feature size is bigger than num_classes.
+
+    Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>> import mindspore.dataset.vision.c_transforms as c_vision
+        >>>
+        >>> onehot_op = c_transforms.OneHot(num_classes=10)
+        >>> data1 = data1.map(operations=onehot_op, input_columns=["label"])
+        >>> mixup_batch_op = c_vision.MixUpBatch(alpha=0.8)
+        >>> data1 = data1.batch(4)
+        >>> data1 = data1.map(operations=mixup_batch_op, input_columns=["image", "label"])
     """
 
     @check_num_classes
@@ -46,12 +56,17 @@ class OneHot(cde.OneHotOp):
 
 class Fill(cde.FillOp):
     """
-    Tensor operation to create a tensor filled with passed scalar value.
+    Tensor operation to create a tensor filled with input scalar value.
     The output tensor will have the same shape and type as the input tensor.
 
     Args:
         fill_value (Union[str, bytes, int, float, bool])) : scalar value
             to fill created tensor with.
+
+    Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
+        >>> fill_op = c_transforms.Fill(3)
     """
 
     @check_fill_value
@@ -64,7 +79,12 @@ class TypeCast(cde.TypeCastOp):
     Tensor operation to cast to a given MindSpore data type.
 
     Args:
-        data_type (mindspore.dtype): mindspore.dtype to be casted to.
+        data_type (mindspore.dtype): mindspore.dtype to be cast to.
+
+    Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
+        >>> type_cast_op = c_transforms.TypeCast(mstype.int32)
     """
 
     @check_de_type
@@ -78,7 +98,7 @@ class Slice(cde.SliceOp):
     """
     Slice operation to extract a tensor out using the given n slices.
 
-    The functionality of Slice is similar to NumPy indexing feature.
+    The functionality of Slice is similar to NumPy's indexing feature.
     (Currently only rank-1 tensors are supported).
 
     Args:
@@ -93,17 +113,19 @@ class Slice(cde.SliceOp):
             5.  :py:obj:`Ellipses`: Slice all dimensions between the two slices. Similar to `...` in Python indexing.
 
     Examples:
-     >>> # Data before
-     >>> # |   col   |
-     >>> # +---------+
-     >>> # | [1,2,3] |
-     >>> # +---------|
-     >>> data = data.map(operations=Slice(slice(1,3))) # slice indices 1 and 2 only
-     >>> # Data after
-     >>> # |   col   |
-     >>> # +---------+
-     >>> # |  [2,3]  |
-     >>> # +---------|
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
+        >>> # Data before
+        >>> # |   col   |
+        >>> # +---------+
+        >>> # | [1,2,3] |
+        >>> # +---------|
+        >>> data1 = data1.map(operations=c_transforms.Slice(slice(1,3))) # slice indices 1 and 2 only
+        >>> # Data after
+        >>> # |   col   |
+        >>> # +---------+
+        >>> # |  [2,3]  |
+        >>> # +---------|
     """
 
     @check_slice_op
@@ -143,18 +165,20 @@ class Mask(cde.MaskOp):
     Any element of the tensor that matches the predicate will be evaluated to True, otherwise False.
 
     Args:
-        operator (Relational): One of the relational operator EQ, NE LT, GT, LE or GE
-        constant (Union[str, int, float, bool]): constant to be compared to.
-            Constant will be casted to the type of the input tensor
-        dtype (mindspore.dtype, optional): type of the generated mask. Default to bool
+        operator (Relational): One of the relational operators EQ, NE LT, GT, LE or GE
+        constant (Union[str, int, float, bool]): Constant to be compared to.
+            Constant will be cast to the type of the input tensor.
+        dtype (mindspore.dtype, optional): Type of the generated mask (Default to bool).
 
     Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
         >>> # Data before
         >>> # |  col1   |
         >>> # +---------+
         >>> # | [1,2,3] |
         >>> # +---------+
-        >>> data = data.map(operations=Mask(Relational.EQ, 2))
+        >>> data1 = data1.map(operations=c_transforms.Mask(Relational.EQ, 2))
         >>> # Data after
         >>> # |       col1         |
         >>> # +--------------------+
@@ -174,18 +198,20 @@ class PadEnd(cde.PadEndOp):
     Pad input tensor according to `pad_shape`, need to have same rank.
 
     Args:
-        pad_shape (list(int)): list on integers representing the shape needed. Dimensions that set to `None` will
+        pad_shape (list(int)): List of integers representing the shape needed. Dimensions that set to `None` will
             not be padded (i.e., original dim will be used). Shorter dimensions will truncate the values.
-        pad_value (Union[str, bytes, int, float, bool]), optional): value used to pad. Default to 0 or empty
-            string in case of Tensors of strings.
+        pad_value (Union[str, bytes, int, float, bool]), optional): Value used to pad. Default to 0 or empty
+            string in case of tensors of strings.
 
     Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
         >>> # Data before
         >>> # |   col   |
         >>> # +---------+
         >>> # | [1,2,3] |
         >>> # +---------|
-        >>> data = data.map(operations=PadEnd(pad_shape=[4], pad_value=10))
+        >>> data1 = data1.map(operations=c_transforms.PadEnd(pad_shape=[4], pad_value=10))
         >>> # Data after
         >>> # |    col     |
         >>> # +------------+
@@ -205,9 +231,17 @@ class Concatenate(cde.ConcatenateOp):
     Tensor operation that concatenates all columns into a single tensor.
 
     Args:
-        axis (int, optional): concatenate the tensors along given axis (Default=0).
+        axis (int, optional): Concatenate the tensors along given axis (Default=0).
         prepend (numpy.array, optional): NumPy array to be prepended to the already concatenated tensors (Default=None).
         append (numpy.array, optional): NumPy array to be appended to the already concatenated tensors (Default=None).
+
+    Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
+        >>> # concatenate string
+        >>> prepend_tensor = np.array(["dw", "df"], dtype='S')
+        >>> append_tensor = np.array(["dwsdf", "df"], dtype='S')
+        >>> concatenate_op = c_transforms.Concatenate(0, prepend_tensor, append_tensor)
     """
 
     @check_concat_type
@@ -224,12 +258,14 @@ class Duplicate(cde.DuplicateOp):
     Duplicate the input tensor to a new output tensor. The input tensor is carried over to the output list.
 
     Examples:
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>>
         >>> # Data before
         >>> # |  x      |
         >>> # +---------+
         >>> # | [1,2,3] |
         >>> # +---------+
-        >>> data = data.map(operations=Duplicate(), input_columns=["x"],
+        >>> data1 = data1.map(operations=c_transforms.Duplicate(), input_columns=["x"],
         >>>         output_columns=["x", "y"], column_order=["x", "y"])
         >>> # Data after
         >>> # |  x      |  y      |
@@ -247,8 +283,11 @@ class Compose(cde.ComposeOp):
         transforms (list): List of transformations to be applied.
 
     Examples:
-        >>> compose = Compose([vision.Decode(), vision.RandomCrop()])
-        >>> dataset = ds.map(operations=compose)
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>> import mindspore.dataset.vision.c_transforms as c_vision
+        >>>
+        >>> compose = c_transforms.Compose([c_vision.Decode(), c_vision.RandomCrop()])
+        >>> data1 = data1.map(operations=compose)
     """
 
     @check_random_transform_ops
@@ -258,15 +297,18 @@ class Compose(cde.ComposeOp):
 
 class RandomApply(cde.RandomApplyOp):
     """
-    Randomly performs a series of transforms with a given probability.
+    Randomly perform a series of transforms with a given probability.
 
     Args:
         transforms (list): List of transformations to be applied.
         prob (float, optional): The probability to apply the transformation list (default=0.5)
 
     Examples:
-        >>> rand_apply = RandomApply([vision.RandomCrop()])
-        >>> dataset = ds.map(operations=rand_apply)
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>> import mindspore.dataset.vision.c_transforms as c_vision
+        >>>
+        >>> rand_apply = c_transforms.RandomApply([c_vision.RandomCrop()])
+        >>> data1 = data1.map(operations=rand_apply)
     """
 
     @check_random_transform_ops
@@ -282,8 +324,11 @@ class RandomChoice(cde.RandomChoiceOp):
         transforms (list): List of transformations to be chosen from to apply.
 
     Examples:
-        >>> rand_choice = RandomChoice([vision.CenterCrop(), vision.RandomCrop()])
-        >>> dataset = ds.map(operations=rand_choice)
+        >>> import mindspore.dataset.transforms.c_transforms as c_transforms
+        >>> import mindspore.dataset.vision.c_transforms as c_vision
+        >>>
+        >>> rand_choice = c_transforms.RandomChoice([c_vision.CenterCrop(), c_vision.RandomCrop()])
+        >>> data1 = data1.map(operations=rand_choice)
     """
 
     @check_random_transform_ops

mindspore/dataset/transforms/py_transforms.py

@@ -29,6 +29,13 @@ class OneHotOp:
         num_classes (int): Number of classes of objects in dataset. Value must be larger than 0.
         smoothing_rate (float, optional): Adjustable hyperparameter for label smoothing level.
             (Default=0.0 means no smoothing is applied.)
+
+    Examples:
+        >>> import mindspore.dataset.transforms as py_transforms
+        >>>
+        >>> transforms_list = [py_transforms.OneHotOp(num_classes=10, smoothing_rate=0.1)]
+        >>> transform = py_transforms.Compose(transforms_list)
+        >>> data1 = data1.map(input_columns=["label"], operations=transform())
     """
 
     @check_one_hot_op
@@ -65,17 +72,18 @@ class Compose:
 
     Examples:
         >>> import mindspore.dataset as ds
-        >>> import mindspore.dataset.vision.py_transforms as py_transforms
-        >>> from mindspore.dataset.transforms.py_transforms import Compose
+        >>> import mindspore.dataset.vision.py_transforms as py_vision
+        >>> import mindspore.dataset.transforms.py_transforms as py_transforms
+        >>>
         >>> dataset_dir = "path/to/imagefolder_directory"
         >>> # create a dataset that reads all files in dataset_dir with 8 threads
         >>> dataset = ds.ImageFolderDataset(dataset_dir, num_parallel_workers=8)
         >>> # create a list of transformations to be applied to the image data
-        >>> transform = Compose([py_transforms.Decode(),
-        >>>                      py_transforms.RandomHorizontalFlip(0.5),
-        >>>                      py_transforms.ToTensor(),
-        >>>                      py_transforms.Normalize((0.491, 0.482, 0.447), (0.247, 0.243, 0.262)),
-        >>>                      py_transforms.RandomErasing()])
+        >>> transform = py_transform.Compose([py_vision.Decode(),
+        >>>                                  py_vision.RandomHorizontalFlip(0.5),
+        >>>                                  py_vision.ToTensor(),
+        >>>                                  py_vision.Normalize((0.491, 0.482, 0.447), (0.247, 0.243, 0.262)),
+        >>>                                  py_vision.RandomErasing()])
         >>> # apply the transform to the dataset through dataset.map()
         >>> dataset = dataset.map(operations=transform, input_columns="image")
     """

mindspore/dataset/vision/__init__.py

@@ -19,4 +19,4 @@ provide more kinds of image augmentations which is developed with Python PIL.
 """
 from . import c_transforms
 from . import py_transforms
-from .utils import Inter, Border
+from .utils import Inter, Border, ImageBatchFormat

mindspore/dataset/vision/py_transforms_util.py

@@ -580,7 +580,7 @@ def rotate(img, angle, resample, expand, center, fill_value):
             Origin is the top left corner.
         fill_value (Union[int, tuple]): Optional fill color for the area outside the rotated image.
             If it is a 3-tuple, it is used for R, G, B channels respectively.
-            If it is an int, it is used for all RGB channels.
+            If it is an integer, it is used for all RGB channels.
 
     Returns:
         img (PIL image), Rotated image.
@@ -677,7 +677,7 @@ def random_rotation(img, degrees, resample, expand, center, fill_value):
             Origin is the top left corner.
         fill_value (Union[int, tuple]): Optional fill color for the area outside the rotated image.
             If it is a 3-tuple, it is used for R, G, B channels respectively.
-            If it is an int, it is used for all RGB channels.
+            If it is an integer, it is used for all RGB channels.
 
     Returns:
         img (PIL image), Rotated image.
@@ -1108,7 +1108,7 @@ def random_affine(img, angle, translations, scale, shear, resample, fill_value=0
         angle (Union[int, float]): Rotation angle in degrees, clockwise.
         translations (sequence): Translations in horizontal and vertical axis.
         scale (float): Scale parameter, a single number.
-        shear (Union[float, sequence]): Shear amount parallel to x and y axis.
+        shear (Union[float, sequence]): Shear amount parallel to X axis and Y axis.
         resample (Union[Inter.NEAREST, Inter.BILINEAR, Inter.BICUBIC], optional): An optional resampling filter.
         fill_value (Union[tuple int], optional): Optional fill_value to fill the area outside the transform
             in the output image. Used only in Pillow versions > 5.0.0.
@@ -1294,7 +1294,7 @@ def rgb_to_hsvs(np_rgb_imgs, is_hwc):
     shape_size = len(np_rgb_imgs.shape)
 
     if not shape_size in (3, 4):
-        raise TypeError('img shape should be (H, W, C)/(N, H, W, C)/(C,H,W)/(N,C,H,W). \
+        raise TypeError('img shape should be (H, W, C)/(N, H, W, C)/(C ,H, W)/(N, C, H, W). \
                          Got {}'.format(np_rgb_imgs.shape))
 
     if shape_size == 3:
@@ -1362,7 +1362,7 @@ def hsv_to_rgbs(np_hsv_imgs, is_hwc):
     shape_size = len(np_hsv_imgs.shape)
 
     if not shape_size in (3, 4):
-        raise TypeError('img shape should be (H, W, C)/(N, H, W, C)/(C,H,W)/(N,C,H,W). \
+        raise TypeError('img shape should be (H, W, C)/(N, H, W, C)/(C, H, W)/(N, C, H, W). \
                          Got {}'.format(np_hsv_imgs.shape))
 
     if shape_size == 3: