add notes about overshoot in bicubic mode (#23321)

Ailing Zhang · facebook-github-bot · commit b7d90332eabd · 2019-07-24T14:46:37.000-07:00
Summary: fix #21044 Bicubic interpolation can cause overshoot. Opencv keeps results dtype aligned with input dtype: - If input is uint8, the result is clamped [0, 255] - If input is float, the result is unclamped. In Pytorch case, we only accept float input, so we'll keep the result unclamped, and add some notes so that users can explicitly call `torch.clamp()` when necessary. Pull Request resolved: #23321 Differential Revision: D16464796 Pulled By: ailzhang fbshipit-source-id: 177915e525d1f54c2209e277cf73e40699ed1acd
diff --git a/torch/nn/functional.py b/torch/nn/functional.py
@@ -2370,6 +2370,12 @@ def upsample(input, size=None, scale_factor=None, mode='nearest', align_corners=
             ``'bilinear'``, ``'bicubic'`` or ``'trilinear'``.
             Default: ``False``
 
+    .. note::
+        With ``mode='bicubic'``, it's possible to cause overshoot, in other words it can produce
+        negative values or values greater than 255 for images.
+        Explicitly call ``result.clamp(min=0, max=255)`` if you want to reduce the overshoot
+        when displaying the image.
+
     .. warning::
         With ``align_corners = True``, the linearly interpolating modes
         (`linear`, `bilinear`, and `trilinear`) don't proportionally align the
@@ -2417,6 +2423,12 @@ def interpolate(input, size=None, scale_factor=None, mode='nearest', align_corne
             ``'bilinear'``, ``'bicubic'``, or ``'trilinear'``.
             Default: ``False``
 
+    .. note::
+        With ``mode='bicubic'``, it's possible to cause overshoot, in other words it can produce
+        negative values or values greater than 255 for images.
+        Explicitly call ``result.clamp(min=0, max=255)`` if you want to reduce the overshoot
+        when displaying the image.
+
     .. warning::
         With ``align_corners = True``, the linearly interpolating modes
         (`linear`, `bilinear`, and `trilinear`) don't proportionally align the
