From e90b3f320b2fb8b65e7f8533c5cc295b4def2066 Mon Sep 17 00:00:00 2001 From: Sandeep Krishnamurthy Date: Wed, 8 May 2019 11:24:16 -0700 Subject: [PATCH 1/5] Add API documentation for upsampling operator with examples --- src/operator/nn/upsampling.cc | 64 +++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 3 deletions(-) diff --git a/src/operator/nn/upsampling.cc b/src/operator/nn/upsampling.cc index cb57b1b2d16f..81494c04d8ac 100644 --- a/src/operator/nn/upsampling.cc +++ b/src/operator/nn/upsampling.cc @@ -121,9 +121,67 @@ struct UpSamplingGrad { DMLC_REGISTER_PARAMETER(UpSamplingParam); NNVM_REGISTER_OP(UpSampling) -.describe("Performs nearest neighbor/bilinear up sampling to inputs. " - "Bilinear upsampling makes use of deconvolution. Therefore, " - "provide 2 inputs - data and weight. ") +.describe(R"code(Upsamples the given input data. + +2 algorithms (``sample_type``) are available for upsampling + +- Nearest Neighbor +- Bilinear + +**Nearest Neighbor Upsampling** + +Input data is expected to be 4D of the form `(batch, channel, height, width)`. + +Example:: + + >>> x = nd.ones((1,1,3,3)) + >>> x + [[[[1. 1. 1.] + [1. 1. 1.] + [1. 1. 1.]]]] + + >>> upsampled_x = nd.UpSampling(x, scale=2, sample_type='nearest') + >>> upsampled_x + [[[[1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.]]]] + + +**Bilinear Upsampling** + +Uses `deconvolution` algorithm under the hood. You need provide both input data and the kernel. + +Input data is expected to be 4D of the form `(batch, channel, height, width)`. + +`num_filter` is expected to be same as the number of channels. + +Example:: + + >>> x = nd.ones((1,1,3,3)) + >>> x + [[[[1. 1. 1.] + [1. 1. 1.] + [1. 1. 1.]]]] + + >>> w = nd.ones((1,1,4,4)) + >>> w + [[[[1. 1. 1. 1.] + [1. 1. 1. 1.] + [1. 1. 1. 1.] + [1. 1. 1. 1.]]]] + + >>> nd.UpSampling(x, w, scale=2, sample_type='bilinear', num_filter=1) + [[[[1. 2. 2. 2. 2. 1.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [1. 2. 2. 2. 2. 1.]]]] + +)code" ADD_FILELINE) .set_num_inputs([](const NodeAttrs& attrs) { const UpSamplingParam& params = nnvm::get(attrs.parsed); return params.sample_type == up_enum::kNearest ? params.num_args : 2; From 8f46f8502b785a2379d9a25048f55a25ed26fb9e Mon Sep 17 00:00:00 2001 From: Sandeep Krishnamurthy Date: Thu, 9 May 2019 12:44:52 -0700 Subject: [PATCH 2/5] Update src/operator/nn/upsampling.cc Co-Authored-By: Aaron Markham --- src/operator/nn/upsampling.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operator/nn/upsampling.cc b/src/operator/nn/upsampling.cc index 81494c04d8ac..14590bbee67e 100644 --- a/src/operator/nn/upsampling.cc +++ b/src/operator/nn/upsampling.cc @@ -123,7 +123,7 @@ DMLC_REGISTER_PARAMETER(UpSamplingParam); NNVM_REGISTER_OP(UpSampling) .describe(R"code(Upsamples the given input data. -2 algorithms (``sample_type``) are available for upsampling +Two algorithms (``sample_type``) are available for upsampling: - Nearest Neighbor - Bilinear From 38748594d7bebff3cbc6a812ba01b5899f75555f Mon Sep 17 00:00:00 2001 From: Sandeep Krishnamurthy Date: Thu, 9 May 2019 12:45:08 -0700 Subject: [PATCH 3/5] Update src/operator/nn/upsampling.cc Co-Authored-By: Aaron Markham --- src/operator/nn/upsampling.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operator/nn/upsampling.cc b/src/operator/nn/upsampling.cc index 14590bbee67e..7a44068f9baa 100644 --- a/src/operator/nn/upsampling.cc +++ b/src/operator/nn/upsampling.cc @@ -154,7 +154,7 @@ Example:: Uses `deconvolution` algorithm under the hood. You need provide both input data and the kernel. -Input data is expected to be 4D of the form `(batch, channel, height, width)`. +Input data is expected to be NCHW. `num_filter` is expected to be same as the number of channels. From 5f9435fef1e07e1af371845fb5d994e0e250a505 Mon Sep 17 00:00:00 2001 From: Sandeep Krishnamurthy Date: Thu, 9 May 2019 12:45:17 -0700 Subject: [PATCH 4/5] Update src/operator/nn/upsampling.cc Co-Authored-By: Aaron Markham --- src/operator/nn/upsampling.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operator/nn/upsampling.cc b/src/operator/nn/upsampling.cc index 7a44068f9baa..f14ebd52fa4c 100644 --- a/src/operator/nn/upsampling.cc +++ b/src/operator/nn/upsampling.cc @@ -130,7 +130,7 @@ Two algorithms (``sample_type``) are available for upsampling: **Nearest Neighbor Upsampling** -Input data is expected to be 4D of the form `(batch, channel, height, width)`. +Input data is expected to be NCHW. Example:: From f0e108569da0cb3a3dd9f6bf63f86d5c9d628cd1 Mon Sep 17 00:00:00 2001 From: Sandeep Krishnamurthy Date: Thu, 9 May 2019 14:07:04 -0700 Subject: [PATCH 5/5] Make API doc example as pseudocode than code --- src/operator/nn/upsampling.cc | 61 ++++++++++++++--------------------- 1 file changed, 25 insertions(+), 36 deletions(-) diff --git a/src/operator/nn/upsampling.cc b/src/operator/nn/upsampling.cc index f14ebd52fa4c..971ff6ad560b 100644 --- a/src/operator/nn/upsampling.cc +++ b/src/operator/nn/upsampling.cc @@ -134,21 +134,16 @@ Input data is expected to be NCHW. Example:: - >>> x = nd.ones((1,1,3,3)) - >>> x - [[[[1. 1. 1.] - [1. 1. 1.] - [1. 1. 1.]]]] - - >>> upsampled_x = nd.UpSampling(x, scale=2, sample_type='nearest') - >>> upsampled_x - [[[[1. 1. 1. 1. 1. 1.] - [1. 1. 1. 1. 1. 1.] - [1. 1. 1. 1. 1. 1.] - [1. 1. 1. 1. 1. 1.] - [1. 1. 1. 1. 1. 1.] - [1. 1. 1. 1. 1. 1.]]]] - + x = [[[[1. 1. 1.] + [1. 1. 1.] + [1. 1. 1.]]]] + + UpSampling(x, scale=2, sample_type='nearest') = [[[[1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.] + [1. 1. 1. 1. 1. 1.]]]] **Bilinear Upsampling** @@ -160,27 +155,21 @@ Input data is expected to be NCHW. Example:: - >>> x = nd.ones((1,1,3,3)) - >>> x - [[[[1. 1. 1.] - [1. 1. 1.] - [1. 1. 1.]]]] - - >>> w = nd.ones((1,1,4,4)) - >>> w - [[[[1. 1. 1. 1.] - [1. 1. 1. 1.] - [1. 1. 1. 1.] - [1. 1. 1. 1.]]]] - - >>> nd.UpSampling(x, w, scale=2, sample_type='bilinear', num_filter=1) - [[[[1. 2. 2. 2. 2. 1.] - [2. 4. 4. 4. 4. 2.] - [2. 4. 4. 4. 4. 2.] - [2. 4. 4. 4. 4. 2.] - [2. 4. 4. 4. 4. 2.] - [1. 2. 2. 2. 2. 1.]]]] - + x = [[[[1. 1. 1.] + [1. 1. 1.] + [1. 1. 1.]]]] + + w = [[[[1. 1. 1. 1.] + [1. 1. 1. 1.] + [1. 1. 1. 1.] + [1. 1. 1. 1.]]]] + + UpSampling(x, w, scale=2, sample_type='bilinear', num_filter=1) = [[[[1. 2. 2. 2. 2. 1.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [2. 4. 4. 4. 4. 2.] + [1. 2. 2. 2. 2. 1.]]]] )code" ADD_FILELINE) .set_num_inputs([](const NodeAttrs& attrs) { const UpSamplingParam& params = nnvm::get(attrs.parsed);