API improvement for nn.functional.upsample (#61974)

NKNaN · web-flow · commit 269de7f072ef · 2024-02-27T12:08:40.000+08:00
* improve upsample api

* update test

* update

* update

* refine upsample layer

* update docs

* fix test

* udpate docs

* update docs
diff --git a/python/paddle/nn/functional/common.py b/python/paddle/nn/functional/common.py
@@ -182,15 +182,16 @@ def interpolate(
     mode='nearest',
     align_corners=False,
     align_mode=0,
-    data_format='NCHW',
+    data_format=None,
     name=None,
 ):
     """
 
     This API resizes a batch of images.
 
-    The input must be a 3-D Tensor of the shape (num_batches, channels, in_w)
-    or 4-D (num_batches, channels, in_h, in_w), or a 5-D Tensor of the shape
+    The input must be be a 3-D Tensor of the shape (num_batches, channels, in_w)
+    or (num_batches, in_w, channels), or 4-D (num_batches, channels, in_h, in_w) or
+    (num_batches, in_h, in_w, channels), or a 5-D Tensor of the shape
     (num_batches, channels, in_d, in_h, in_w) or (num_batches, in_d, in_h, in_w, channels),
     Where in_w is width of the input tensor, in_h is the height of the input tensor,
     in_d is the depth of the input tensor.
@@ -322,8 +323,9 @@ def interpolate(
     https://en.wikipedia.org/wiki/Bicubic_interpolation
 
     Parameters:
-        x (Tensor): 3-D, 4-D or 5-D Tensor, its data type is float32, float64, or uint8,
-                          its data format is specified by :attr:`data_format`.
+        x (Tensor): 3-D, 4-D or 5-D Tensor, its data type is float32, float64, or uint8, its data format is
+             specified by :attr:`data_format`. If :attr:`data_format` is not provided, the data format will
+             be presumed according to its dimension. See details in :attr:`data_format`.
         size (list|tuple|Tensor|None): Output shape of image resize
              layer, the shape is (out_w, ) when input is a 3-D Tensor, the shape is (out_h, out_w)
              when input is a 4-D Tensor and is (out_d, out_h, out_w) when input is a 5-D Tensor.
@@ -342,18 +344,21 @@ def interpolate(
         align_mode(int)  :  An optional for linear/bilinear/trilinear interpolation. Refer to the formula in the example above,
                             it can be \'0\' for src_idx = scale_factor*(dst_index+0.5)-0.5 , can be \'1\' for
                             src_idx = scale_factor*dst_index.
-        data_format (str, optional): Specify the data format of the input, and the data format of the output
-            will be consistent with that of the input. An optional string from:`NCW`, `NWC`,  `"NCHW"`, `"NHWC"`, `"NCDHW"`,
-            `"NDHWC"`. The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
-            `[batch_size, input_channels, input_height, input_width]`. When it is `"NCHW"`, the data is stored
-            in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
+        data_format (str, optional): Specify the data format of the input, and the data format of
+             the output will be consistent with that of the input. An optional string from:`"NCW"`,
+             `"NWC"`,  `"NCHW"`, `"NHWC"`, `"NCDHW"`, `"NDHWC"`. The default value is None.
+             When :attr:`data_format` is not specified, it will be automatically inferred from the
+             input dimension of :attr:`x`. When :attr:`x` is a 3-D Tensor, :attr:`data_format` will be
+             set to `"NCW"`; When :attr:`x` is a 4-D Tensor, :attr:`data_format` will be set to
+             `"NCHW"`; When :attr:`x` is a 5-D Tensor, :attr:`data_format` will be set to `"NCDHW"`.
+             When it is `"NCHW"`, the data should be stored in the order of:
+             `[batch_size, input_channels, input_height, input_width]`. When it is `"NCDHW"`, the
+             data should be stored in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
         name(str, optional): The default value is None.
                              Normally there is no need for user to set this property.
                              For more information, please refer to :ref:`api_guide_Name`
     Returns:
-        A 3-D Tensor of the shape (num_batches, channels, out_w) or (num_batches, out_w, channels),
-        A 4-D Tensor of the shape (num_batches, channels, out_h, out_w) or (num_batches, out_h, out_w, channels),
-        or 5-D Tensor of the shape (num_batches, channels, out_d, out_h, out_w) or (num_batches, out_d, out_h, out_w, channels).
+        A 3-D, 4-D or 5-D Tensor, with the same data format of the input :attr:`x`.
 
 
     Examples:
@@ -375,6 +380,18 @@ def interpolate(
             >>> print(output_2.shape)
             [2, 3, 12, 10]
     """
+    if data_format is None:
+        dim_size = len(x.shape)
+        if dim_size == 3:
+            data_format = 'NCW'
+        elif dim_size == 4:
+            data_format = 'NCHW'
+        elif dim_size == 5:
+            data_format = 'NCDHW'
+        else:
+            raise ValueError(
+                f"The dimension of the input tensor should only be 3-D, 4-D or 5-D, but the received dimension is {dim_size}."
+            )
     data_format = data_format.upper()
     resample = mode.upper()
     resample_type = mode.lower()
@@ -719,15 +736,16 @@ def upsample(
     mode='nearest',
     align_corners=False,
     align_mode=0,
-    data_format='NCHW',
+    data_format=None,
     name=None,
 ):
     """
 
     This API resizes a batch of images.
 
     The input must be a 3-D Tensor of the shape (num_batches, channels, in_w)
-    or 4-D (num_batches, channels, in_h, in_w), or a 5-D Tensor of the shape
+    or (num_batches, in_w, channels), or 4-D (num_batches, channels, in_h, in_w) or
+    (num_batches, in_h, in_w, channels), or a 5-D Tensor of the shape
     (num_batches, channels, in_d, in_h, in_w) or (num_batches, in_d, in_h, in_w, channels),
     Where in_w is width of the input tensor, in_h is the height of the input tensor,
     in_d is the depth of the input tensor.
@@ -858,8 +876,9 @@ def upsample(
     https://en.wikipedia.org/wiki/Trilinear_interpolation.
 
     Parameters:
-        x (Tensor): 3-D, 4-D or 5-D Tensor, its data type is float32, float64, or uint8,
-                          its data format is specified by :attr:`data_format`.
+        x (Tensor): 3-D, 4-D or 5-D Tensor, its data type is float32, float64, or uint8, its data format is
+             specified by :attr:`data_format`. If :attr:`data_format` is not provided, the data format will
+             be presumed according to its dimension. See details in :attr:`data_format`.
         size (list|tuple|Tensor|None, optional): Output shape of image resize
              layer, the shape is (out_w, ) when input is a 3-D Tensor, the shape is (out_h, out_w)
              when input is a 4-D Tensor and is (out_d, out_h, out_w) when input is a 5-D Tensor.
@@ -879,19 +898,22 @@ def upsample(
         align_mode(int, optional)  :  An optional for linear/bilinear/trilinear interpolation. Refer to the formula in the example above,
                             it can be \'0\' for src_idx = scale_factor*(dst_index+0.5)-0.5 , can be \'1\' for
                             src_idx = scale_factor*dst_index.
-        data_format (str, optional): Specify the data format of the input, and the data format of the output
-            will be consistent with that of the input. An optional string from:`NCW`, `NWC`, `"NCHW"`, `"NHWC"`, `"NCDHW"`,
-            `"NDHWC"`. The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
-            `[batch_size, input_channels, input_height, input_width]`. When it is `"NCHW"`, the data is stored
-            in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
+        data_format (str, optional): Specify the data format of the input, and the data format of
+             the output will be consistent with that of the input. An optional string from:`"NCW"`,
+             `"NWC"`,  `"NCHW"`, `"NHWC"`, `"NCDHW"`, `"NDHWC"`. The default value is None.
+             When :attr:`data_format` is not specified, it will be automatically inferred from the
+             input dimension of :attr:`x`. When :attr:`x` is a 3-D Tensor, :attr:`data_format` will be
+             set to `"NCW"`; When :attr:`x` is a 4-D Tensor, :attr:`data_format` will be set to
+             `"NCHW"`; When :attr:`x` is a 5-D Tensor, :attr:`data_format` will be set to `"NCDHW"`.
+             When it is `"NCHW"`, the data should be stored in the order of:
+             `[batch_size, input_channels, input_height, input_width]`. When it is `"NCDHW"`, the
+             data should be stored in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
         name(str, optional): The default value is None.
                              Normally there is no need for user to set this property.
                              For more information, please refer to :ref:`api_guide_Name`
 
     Returns:
-        A 3-D Tensor of the shape (num_batches, channels, out_w) or (num_batches, out_w, channels),
-        A 4-D Tensor of the shape (num_batches, channels, out_h, out_w) or (num_batches, out_h, out_w, channels),
-        or 5-D Tensor of the shape (num_batches, channels, out_d, out_h, out_w) or (num_batches, out_d, out_h, out_w, channels).
+        A 3-D, 4-D or 5-D Tensor, with the same data format of the input :attr:`x`.
 
     Examples:
         .. code-block:: python
@@ -906,6 +928,7 @@ def upsample(
             [2, 3, 12, 12]
 
     """
+
     return interpolate(
         x, size, scale_factor, mode, align_corners, align_mode, data_format
     )
diff --git a/python/paddle/nn/layer/common.py b/python/paddle/nn/layer/common.py
@@ -199,7 +199,8 @@ class Upsample(Layer):
     This op resizes a batch of images.
 
     The input must be a 3-D Tensor of the shape (num_batches, channels, in_w)
-    or 4-D (num_batches, channels, in_h, in_w), or a 5-D Tensor of the shape
+    or (num_batches, in_w, channels), or 4-D (num_batches, channels, in_h, in_w) or
+    (num_batches, in_h, in_w, channels), or a 5-D Tensor of the shape
     (num_batches, channels, in_d, in_h, in_w) or (num_batches, in_d, in_h, in_w, channels),
     Where in_w is width of the input tensor, in_h is the height of the input tensor,
     in_d is the depth of the input tensor.
@@ -338,8 +339,7 @@ class Upsample(Layer):
     https://en.wikipedia.org/wiki/Trilinear_interpolation.
 
     Parameters:
-        x (Tensor): 3-D, 4-D or 5-D Tensor, its data type is float32, float64, or uint8,
-                          its data format is specified by :attr:`data_format`.
+
         size (list|tuple|Tensor|None): Output shape of image resize
              layer, the shape is (out_w, ) when input is a 3-D Tensor, the shape is (out_h, out_w)
              when input is a 4-D Tensor and is (out_d, out_h, out_w) when input is a 5-D Tensor.
@@ -358,18 +358,21 @@ class Upsample(Layer):
         align_mode(int)  :  An optional for linear/bilinear/trilinear interpolation. Refer to the formula in the example above,
                             it can be \'0\' for src_idx = scale_factor*(dst_indx+0.5)-0.5 , can be \'1\' for
                             src_idx = scale_factor*dst_index.
-        data_format (str, optional): Specify the data format of the input, and the data format of the output
-            will be consistent with that of the input. An optional string from:`NCW`, `NWC`, `"NCHW"`, `"NHWC"`, `"NCDHW"`,
-            `"NDHWC"`. The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
-            `[batch_size, input_channels, input_height, input_width]`. When it is `"NCHW"`, the data is stored
-            in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
+        data_format (str, optional): Specify the data format of the input, and the data format of
+             the output will be consistent with that of the input. An optional string from:`"NCW"`,
+             `"NWC"`,  `"NCHW"`, `"NHWC"`, `"NCDHW"`, `"NDHWC"`. The default value is None.
+             When :attr:`data_format` is not specified, it will be automatically inferred from the
+             input dimension of :attr:`x`. When :attr:`x` is a 3-D Tensor, :attr:`data_format` will be
+             set to `"NCW"`; When :attr:`x` is a 4-D Tensor, :attr:`data_format` will be set to
+             `"NCHW"`; When :attr:`x` is a 5-D Tensor, :attr:`data_format` will be set to `"NCDHW"`.
+             When it is `"NCHW"`, the data should be stored in the order of:
+             `[batch_size, input_channels, input_height, input_width]`. When it is `"NCDHW"`, the
+             data should be stored in the order of: `[batch_size, input_channels, input_depth, input_height, input_width]`.
         name(str, optional): The default value is None.
                              Normally there is no need for user to set this property.
                              For more information, please refer to :ref:`api_guide_Name`
     Returns:
-        A 3-D Tensor of the shape (num_batches, channels, out_w) or (num_batches, out_w, channels),
-        A 4-D Tensor of the shape (num_batches, channels, out_h, out_w) or (num_batches, out_h, out_w, channels),
-        or 5-D Tensor of the shape (num_batches, channels, out_d, out_h, out_w) or (num_batches, out_d, out_h, out_w, channels).
+        A callable object of Upsample.
 
     Examples:
         .. code-block:: python
@@ -392,7 +395,7 @@ def __init__(
         mode='nearest',
         align_corners=False,
         align_mode=0,
-        data_format='NCHW',
+        data_format=None,
         name=None,
     ):
         super().__init__()
@@ -405,6 +408,18 @@ def __init__(
         self.name = name
 
     def forward(self, x):
+        if self.data_format is None:
+            dim_size = len(x.shape)
+            if dim_size == 3:
+                self.data_format = 'NCW'
+            elif dim_size == 4:
+                self.data_format = 'NCHW'
+            elif dim_size == 5:
+                self.data_format = 'NCDHW'
+            else:
+                raise ValueError(
+                    f"The dimension of the input tensor should only be 3-D, 4-D or 5-D, but the received dimension is {dim_size}."
+                )
         out = F.interpolate(
             x,
             size=self.size,
diff --git a/test/legacy_test/test_bilinear_interp_v2_op.py b/test/legacy_test/test_bilinear_interp_v2_op.py
@@ -975,6 +975,29 @@ def test_case(self):
             np.testing.assert_allclose(out.numpy(), expect_res, rtol=1e-05)
 
 
+class TestBilinearInterpOpAPI_dy5(unittest.TestCase):
+    def test_case(self):
+        import paddle
+
+        if core.is_compiled_with_cuda():
+            place = core.CUDAPlace(0)
+        else:
+            place = core.CPUPlace()
+        with base.dygraph.guard(place):
+            input_data = np.random.random((2, 3, 6, 6)).astype("float32")
+            scale_np = np.array([2, 2]).astype("int64")
+            input_x = paddle.to_tensor(input_data)
+            scale = paddle.to_tensor(scale_np)
+            expect_res = bilinear_interp_np(
+                input_data, out_h=12, out_w=12, align_corners=False
+            )
+            up_layer = paddle.nn.Upsample(
+                scale_factor=scale, mode="bilinear", align_corners=False
+            )
+            out = up_layer(input_x)
+            np.testing.assert_allclose(out.numpy(), expect_res, rtol=1e-05)
+
+
 @unittest.skipIf(
     not base.core.is_compiled_with_cuda(), "core is not compiled with CUDA"
 )
diff --git a/test/legacy_test/test_imperative_layers.py b/test/legacy_test/test_imperative_layers.py
@@ -108,7 +108,7 @@ def test_layer_str(self):
         module = nn.Upsample(size=[12, 12])
         self.assertEqual(
             str(module),
-            'Upsample(size=[12, 12], mode=nearest, align_corners=False, align_mode=0, data_format=NCHW)',
+            'Upsample(size=[12, 12], mode=nearest, align_corners=False, align_mode=0, data_format=None)',
         )
 
         module = nn.UpsamplingNearest2D(size=[12, 12])
diff --git a/test/legacy_test/test_linear_interp_v2_op.py b/test/legacy_test/test_linear_interp_v2_op.py
@@ -333,7 +333,6 @@ def test_case(self):
             mode='linear',
             align_mode=1,
             align_corners=False,
-            data_format='NCW',
         )
         with base.dygraph.guard():
             x = paddle.to_tensor(x_data)
@@ -346,6 +345,26 @@ def test_case(self):
             np.testing.assert_allclose(interp.numpy(), expect, rtol=1e-05)
 
 
+class TestLinearInterpOpAPI2_0_case2(unittest.TestCase):
+    def test_case(self):
+        # dygraph
+        x_data = np.random.random((1, 3, 128)).astype("float32")
+        with base.dygraph.guard():
+            x = paddle.to_tensor(x_data)
+            interp = interpolate(
+                x,
+                size=[64],
+                mode='linear',
+                align_mode=1,
+                align_corners=False,
+            )
+            expect = linear_interp_np(
+                x_data, out_w=64, align_mode=1, align_corners=False
+            )
+
+            np.testing.assert_allclose(interp.numpy(), expect, rtol=1e-05)
+
+
 class TestLinearInterpOpFP16(TestLinearInterpOp):
     def test_check_output(self):
         self.check_output(atol=1e-3, check_pir=True)
diff --git a/test/legacy_test/test_trilinear_interp_v2_op.py b/test/legacy_test/test_trilinear_interp_v2_op.py
@@ -1021,5 +1021,53 @@ def init_test_case(self):
         self.data_layout = "NDHWC"
 
 
+class TestTrilinearInterpOpAPI(unittest.TestCase):
+    def test_case(self):
+        import paddle
+
+        if core.is_compiled_with_cuda():
+            place = core.CUDAPlace(0)
+        else:
+            place = core.CPUPlace()
+        with base.dygraph.guard(place):
+            input_data = np.random.random((2, 3, 6, 6, 6)).astype("float32")
+            scale_np = np.array([2, 2, 2]).astype("int64")
+            input_x = paddle.to_tensor(input_data)
+            scale = paddle.to_tensor(scale_np)
+            expect_res = trilinear_interp_np(
+                input_data, out_d=12, out_h=12, out_w=12, align_corners=False
+            )
+            up_layer = paddle.nn.Upsample(
+                scale_factor=scale, mode="trilinear", align_corners=False
+            )
+            out = up_layer(input_x)
+            np.testing.assert_allclose(out.numpy(), expect_res, rtol=1e-05)
+
+
+class TestTrilinearInterpOpAPI2(unittest.TestCase):
+    def test_case(self):
+        import paddle
+
+        if core.is_compiled_with_cuda():
+            place = core.CUDAPlace(0)
+        else:
+            place = core.CPUPlace()
+        with base.dygraph.guard(place):
+            input_data = np.random.random((2, 3, 6, 6, 6)).astype("float32")
+            scale_np = np.array([2, 2, 2]).astype("int64")
+            input_x = paddle.to_tensor(input_data)
+            scale = paddle.to_tensor(scale_np)
+            expect_res = trilinear_interp_np(
+                input_data, out_d=12, out_h=12, out_w=12, align_corners=False
+            )
+            out = interpolate(
+                x=input_x,
+                scale_factor=scale,
+                mode="trilinear",
+                align_corners=False,
+            )
+            np.testing.assert_allclose(out.numpy(), expect_res, rtol=1e-05)
+
+
 if __name__ == "__main__":
     unittest.main()

Original file line number	Diff line number	Diff line change
`@@ -108,7 +108,7 @@ def test_layer_str(self):`
`108`	`108`	`module = nn.Upsample(size=[12, 12])`
`109`	`109`	`self.assertEqual(`
`110`	`110`	`str(module),`
`111`		`- 'Upsample(size=[12, 12], mode=nearest, align_corners=False, align_mode=0, data_format=NCHW)',`
	`111`	`+ 'Upsample(size=[12, 12], mode=nearest, align_corners=False, align_mode=0, data_format=None)',`
`112`	`112`	`)`
`113`	`113`
`114`	`114`	`module = nn.UpsamplingNearest2D(size=[12, 12])`