functional.py 65 KB
Newer Older
1
import math
2
3
import numbers
import warnings
4
from enum import Enum
5
from typing import List, Tuple, Any, Optional
6
7
8

import numpy as np
import torch
9
from PIL import Image
10
11
from torch import Tensor

12
13
14
15
16
try:
    import accimage
except ImportError:
    accimage = None

17
from ..utils import _log_api_usage_once
18
19
20
from . import functional_pil as F_pil
from . import functional_tensor as F_t

21

22
class InterpolationMode(Enum):
23
    """Interpolation modes
24
    Available interpolation methods are ``nearest``, ``bilinear``, ``bicubic``, ``box``, ``hamming``, and ``lanczos``.
25
    """
26

27
28
29
30
31
32
33
34
35
36
    NEAREST = "nearest"
    BILINEAR = "bilinear"
    BICUBIC = "bicubic"
    # For PIL compatibility
    BOX = "box"
    HAMMING = "hamming"
    LANCZOS = "lanczos"


# TODO: Once torchscript supports Enums with staticmethod
37
38
# this can be put into InterpolationMode as staticmethod
def _interpolation_modes_from_int(i: int) -> InterpolationMode:
39
    inverse_modes_mapping = {
40
41
42
43
44
45
        0: InterpolationMode.NEAREST,
        2: InterpolationMode.BILINEAR,
        3: InterpolationMode.BICUBIC,
        4: InterpolationMode.BOX,
        5: InterpolationMode.HAMMING,
        1: InterpolationMode.LANCZOS,
46
47
48
49
50
    }
    return inverse_modes_mapping[i]


pil_modes_mapping = {
51
52
53
54
55
56
    InterpolationMode.NEAREST: 0,
    InterpolationMode.BILINEAR: 2,
    InterpolationMode.BICUBIC: 3,
    InterpolationMode.BOX: 4,
    InterpolationMode.HAMMING: 5,
    InterpolationMode.LANCZOS: 1,
57
58
}

vfdev's avatar
vfdev committed
59
60
61
_is_pil_image = F_pil._is_pil_image


62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def get_dimensions(img: Tensor) -> List[int]:
    """Returns the dimensions of an image as [channels, height, width].

    Args:
        img (PIL Image or Tensor): The image to be checked.

    Returns:
        List[int]: The image dimensions.
    """
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(get_dimensions)
    if isinstance(img, torch.Tensor):
        return F_t.get_dimensions(img)

    return F_pil.get_dimensions(img)


79
80
81
82
83
84
85
86
def get_image_size(img: Tensor) -> List[int]:
    """Returns the size of an image as [width, height].

    Args:
        img (PIL Image or Tensor): The image to be checked.

    Returns:
        List[int]: The image size.
vfdev's avatar
vfdev committed
87
    """
88
89
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(get_image_size)
vfdev's avatar
vfdev committed
90
    if isinstance(img, torch.Tensor):
91
        return F_t.get_image_size(img)
92

93
    return F_pil.get_image_size(img)
94

vfdev's avatar
vfdev committed
95

96
97
98
99
100
101
102
103
def get_image_num_channels(img: Tensor) -> int:
    """Returns the number of channels of an image.

    Args:
        img (PIL Image or Tensor): The image to be checked.

    Returns:
        int: The number of channels.
104
    """
105
106
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(get_image_num_channels)
107
    if isinstance(img, torch.Tensor):
108
        return F_t.get_image_num_channels(img)
109

110
    return F_pil.get_image_num_channels(img)
111
112


vfdev's avatar
vfdev committed
113
114
@torch.jit.unused
def _is_numpy(img: Any) -> bool:
115
116
117
    return isinstance(img, np.ndarray)


vfdev's avatar
vfdev committed
118
119
@torch.jit.unused
def _is_numpy_image(img: Any) -> bool:
120
    return img.ndim in {2, 3}
121
122


123
def to_tensor(pic) -> Tensor:
124
    """Convert a ``PIL Image`` or ``numpy.ndarray`` to tensor.
125
    This function does not support torchscript.
126

127
    See :class:`~torchvision.transforms.ToTensor` for more details.
128
129
130
131
132
133
134

    Args:
        pic (PIL Image or numpy.ndarray): Image to be converted to tensor.

    Returns:
        Tensor: Converted image.
    """
135
136
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(to_tensor)
137
    if not (F_pil._is_pil_image(pic) or _is_numpy(pic)):
138
        raise TypeError(f"pic should be PIL Image or ndarray. Got {type(pic)}")
139

140
    if _is_numpy(pic) and not _is_numpy_image(pic):
141
        raise ValueError(f"pic should be 2/3 dimensional. Got {pic.ndim} dimensions.")
142

143
144
    default_float_dtype = torch.get_default_dtype()

145
146
    if isinstance(pic, np.ndarray):
        # handle numpy array
surgan12's avatar
surgan12 committed
147
148
149
        if pic.ndim == 2:
            pic = pic[:, :, None]

150
        img = torch.from_numpy(pic.transpose((2, 0, 1))).contiguous()
151
        # backward compatibility
152
        if isinstance(img, torch.ByteTensor):
153
            return img.to(dtype=default_float_dtype).div(255)
154
155
        else:
            return img
156
157

    if accimage is not None and isinstance(pic, accimage.Image):
158
        nppic = np.zeros([pic.channels, pic.height, pic.width], dtype=np.float32)
159
        pic.copyto(nppic)
160
        return torch.from_numpy(nppic).to(dtype=default_float_dtype)
161
162

    # handle PIL Image
163
164
    mode_to_nptype = {"I": np.int32, "I;16": np.int16, "F": np.float32}
    img = torch.from_numpy(np.array(pic, mode_to_nptype.get(pic.mode, np.uint8), copy=True))
165

166
    if pic.mode == "1":
167
        img = 255 * img
168
    img = img.view(pic.size[1], pic.size[0], len(pic.getbands()))
169
    # put it from HWC to CHW format
170
    img = img.permute((2, 0, 1)).contiguous()
171
    if isinstance(img, torch.ByteTensor):
172
        return img.to(dtype=default_float_dtype).div(255)
173
174
175
176
    else:
        return img


177
178
def pil_to_tensor(pic):
    """Convert a ``PIL Image`` to a tensor of the same type.
179
    This function does not support torchscript.
180

vfdev's avatar
vfdev committed
181
    See :class:`~torchvision.transforms.PILToTensor` for more details.
182

183
184
185
186
    .. note::

        A deep copy of the underlying array is performed.

187
188
189
190
191
192
    Args:
        pic (PIL Image): Image to be converted to tensor.

    Returns:
        Tensor: Converted image.
    """
193
194
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(pil_to_tensor)
195
    if not F_pil._is_pil_image(pic):
196
        raise TypeError(f"pic should be PIL Image. Got {type(pic)}")
197
198

    if accimage is not None and isinstance(pic, accimage.Image):
199
200
        # accimage format is always uint8 internally, so always return uint8 here
        nppic = np.zeros([pic.channels, pic.height, pic.width], dtype=np.uint8)
201
202
203
204
        pic.copyto(nppic)
        return torch.as_tensor(nppic)

    # handle PIL Image
205
    img = torch.as_tensor(np.array(pic, copy=True))
206
207
208
209
210
211
    img = img.view(pic.size[1], pic.size[0], len(pic.getbands()))
    # put it from HWC to CHW format
    img = img.permute((2, 0, 1))
    return img


212
213
def convert_image_dtype(image: torch.Tensor, dtype: torch.dtype = torch.float) -> torch.Tensor:
    """Convert a tensor image to the given ``dtype`` and scale the values accordingly
214
    This function does not support PIL Image.
215
216
217
218
219
220

    Args:
        image (torch.Tensor): Image to be converted
        dtype (torch.dtype): Desired data type of the output

    Returns:
vfdev's avatar
vfdev committed
221
        Tensor: Converted image
222
223
224
225
226
227
228
229
230
231
232
233

    .. note::

        When converting from a smaller to a larger integer ``dtype`` the maximum values are **not** mapped exactly.
        If converted back and forth, this mismatch has no effect.

    Raises:
        RuntimeError: When trying to cast :class:`torch.float32` to :class:`torch.int32` or :class:`torch.int64` as
            well as for trying to cast :class:`torch.float64` to :class:`torch.int64`. These conversions might lead to
            overflow errors since the floating point ``dtype`` cannot store consecutive integers over the whole range
            of the integer ``dtype``.
    """
234
235
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(convert_image_dtype)
236
    if not isinstance(image, torch.Tensor):
237
        raise TypeError("Input img should be Tensor Image")
238
239

    return F_t.convert_image_dtype(image, dtype)
240
241


242
def to_pil_image(pic, mode=None):
243
    """Convert a tensor or an ndarray to PIL Image. This function does not support torchscript.
244

245
    See :class:`~torchvision.transforms.ToPILImage` for more details.
246
247
248
249
250

    Args:
        pic (Tensor or numpy.ndarray): Image to be converted to PIL Image.
        mode (`PIL.Image mode`_): color space and pixel depth of input data (optional).

251
    .. _PIL.Image mode: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#concept-modes
252
253
254
255

    Returns:
        PIL Image: Image converted to PIL Image.
    """
256
257
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(to_pil_image)
258
    if not (isinstance(pic, torch.Tensor) or isinstance(pic, np.ndarray)):
259
        raise TypeError(f"pic should be Tensor or ndarray. Got {type(pic)}.")
260

Varun Agrawal's avatar
Varun Agrawal committed
261
262
    elif isinstance(pic, torch.Tensor):
        if pic.ndimension() not in {2, 3}:
263
            raise ValueError(f"pic should be 2/3 dimensional. Got {pic.ndimension()} dimensions.")
Varun Agrawal's avatar
Varun Agrawal committed
264
265
266

        elif pic.ndimension() == 2:
            # if 2D image, add channel dimension (CHW)
Surgan Jandial's avatar
Surgan Jandial committed
267
            pic = pic.unsqueeze(0)
Varun Agrawal's avatar
Varun Agrawal committed
268

269
270
        # check number of channels
        if pic.shape[-3] > 4:
271
            raise ValueError(f"pic should not have > 4 channels. Got {pic.shape[-3]} channels.")
272

Varun Agrawal's avatar
Varun Agrawal committed
273
274
    elif isinstance(pic, np.ndarray):
        if pic.ndim not in {2, 3}:
275
            raise ValueError(f"pic should be 2/3 dimensional. Got {pic.ndim} dimensions.")
Varun Agrawal's avatar
Varun Agrawal committed
276
277
278
279
280

        elif pic.ndim == 2:
            # if 2D image, add channel dimension (HWC)
            pic = np.expand_dims(pic, 2)

281
282
        # check number of channels
        if pic.shape[-1] > 4:
283
            raise ValueError(f"pic should not have > 4 channels. Got {pic.shape[-1]} channels.")
284

285
    npimg = pic
Varun Agrawal's avatar
Varun Agrawal committed
286
    if isinstance(pic, torch.Tensor):
287
        if pic.is_floating_point() and mode != "F":
288
289
            pic = pic.mul(255).byte()
        npimg = np.transpose(pic.cpu().numpy(), (1, 2, 0))
290
291

    if not isinstance(npimg, np.ndarray):
292
        raise TypeError("Input pic must be a torch.Tensor or NumPy ndarray, not {type(npimg)}")
293
294
295
296
297

    if npimg.shape[2] == 1:
        expected_mode = None
        npimg = npimg[:, :, 0]
        if npimg.dtype == np.uint8:
298
            expected_mode = "L"
vfdev's avatar
vfdev committed
299
        elif npimg.dtype == np.int16:
300
            expected_mode = "I;16"
vfdev's avatar
vfdev committed
301
        elif npimg.dtype == np.int32:
302
            expected_mode = "I"
303
        elif npimg.dtype == np.float32:
304
            expected_mode = "F"
305
        if mode is not None and mode != expected_mode:
306
            raise ValueError(f"Incorrect mode ({mode}) supplied for input type {np.dtype}. Should be {expected_mode}")
307
308
        mode = expected_mode

surgan12's avatar
surgan12 committed
309
    elif npimg.shape[2] == 2:
310
        permitted_2_channel_modes = ["LA"]
surgan12's avatar
surgan12 committed
311
        if mode is not None and mode not in permitted_2_channel_modes:
312
            raise ValueError(f"Only modes {permitted_2_channel_modes} are supported for 2D inputs")
surgan12's avatar
surgan12 committed
313
314

        if mode is None and npimg.dtype == np.uint8:
315
            mode = "LA"
surgan12's avatar
surgan12 committed
316

317
    elif npimg.shape[2] == 4:
318
        permitted_4_channel_modes = ["RGBA", "CMYK", "RGBX"]
319
        if mode is not None and mode not in permitted_4_channel_modes:
320
            raise ValueError(f"Only modes {permitted_4_channel_modes} are supported for 4D inputs")
321
322

        if mode is None and npimg.dtype == np.uint8:
323
            mode = "RGBA"
324
    else:
325
        permitted_3_channel_modes = ["RGB", "YCbCr", "HSV"]
326
        if mode is not None and mode not in permitted_3_channel_modes:
327
            raise ValueError(f"Only modes {permitted_3_channel_modes} are supported for 3D inputs")
328
        if mode is None and npimg.dtype == np.uint8:
329
            mode = "RGB"
330
331

    if mode is None:
332
        raise TypeError(f"Input type {npimg.dtype} is not supported")
333
334
335
336

    return Image.fromarray(npimg, mode=mode)


337
def normalize(tensor: Tensor, mean: List[float], std: List[float], inplace: bool = False) -> Tensor:
338
    """Normalize a float tensor image with mean and standard deviation.
339
    This transform does not support PIL Image.
340

341
    .. note::
surgan12's avatar
surgan12 committed
342
        This transform acts out of place by default, i.e., it does not mutates the input tensor.
343

344
    See :class:`~torchvision.transforms.Normalize` for more details.
345
346

    Args:
347
        tensor (Tensor): Float tensor image of size (C, H, W) or (B, C, H, W) to be normalized.
348
        mean (sequence): Sequence of means for each channel.
349
        std (sequence): Sequence of standard deviations for each channel.
350
        inplace(bool,optional): Bool to make this operation inplace.
351
352
353
354

    Returns:
        Tensor: Normalized Tensor image.
    """
355
356
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(normalize)
357
    if not isinstance(tensor, torch.Tensor):
358
        raise TypeError(f"img should be Tensor Image. Got {type(tensor)}")
359

360
    return F_t.normalize(tensor, mean=mean, std=std, inplace=inplace)
361
362


363
364
365
366
367
368
369
def resize(
    img: Tensor,
    size: List[int],
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
    max_size: Optional[int] = None,
    antialias: Optional[bool] = None,
) -> Tensor:
vfdev's avatar
vfdev committed
370
    r"""Resize the input image to the given size.
371
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
372
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
373

374
375
376
377
    .. warning::
        The output image might be different depending on its type: when downsampling, the interpolation of PIL images
        and tensors is slightly different, because PIL applies antialiasing. This may lead to significant differences
        in the performance of a network. Therefore, it is preferable to train and serve a model with the same input
378
379
        types. See also below the ``antialias`` parameter, which can help making the output of PIL images and tensors
        closer.
380

381
    Args:
vfdev's avatar
vfdev committed
382
        img (PIL Image or Tensor): Image to be resized.
383
384
        size (sequence or int): Desired output size. If size is a sequence like
            (h, w), the output size will be matched to this. If size is an int,
Vitaliy Chiley's avatar
Vitaliy Chiley committed
385
            the smaller edge of the image will be matched to this number maintaining
386
            the aspect ratio. i.e, if height > width, then image will be rescaled to
vfdev's avatar
vfdev committed
387
            :math:`\left(\text{size} \times \frac{\text{height}}{\text{width}}, \text{size}\right)`.
388
389
390

            .. note::
                In torchscript mode size as single int is not supported, use a sequence of length 1: ``[size, ]``.
391
392
393
394
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`.
            Default is ``InterpolationMode.BILINEAR``. If input is Tensor, only ``InterpolationMode.NEAREST``,
            ``InterpolationMode.BILINEAR`` and ``InterpolationMode.BICUBIC`` are supported.
395
396
            For backward compatibility integer values (e.g. ``PIL.Image[.Resampling].NEAREST``) are still accepted,
            but deprecated since 0.13 and will be removed in 0.15. Please use InterpolationMode enum.
397
398
399
400
        max_size (int, optional): The maximum allowed for the longer edge of
            the resized image: if the longer edge of the image is greater
            than ``max_size`` after being resized according to ``size``, then
            the image is resized again so that the longer edge is equal to
401
            ``max_size``. As a result, ``size`` might be overruled, i.e the
402
403
404
            smaller edge may be shorter than ``size``. This is only supported
            if ``size`` is an int (or a sequence of length 1 in torchscript
            mode).
405
        antialias (bool, optional): antialias flag. If ``img`` is PIL Image, the flag is ignored and anti-alias
406
            is always used. If ``img`` is Tensor, the flag is False by default and can be set to True for
407
408
            ``InterpolationMode.BILINEAR`` and ``InterpolationMode.BICUBIC`` modes.
            This can help making the output for PIL images and tensors closer.
409
410

    Returns:
vfdev's avatar
vfdev committed
411
        PIL Image or Tensor: Resized image.
412
    """
413
414
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(resize)
415
416
417
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
418
419
            "Argument 'interpolation' of type int is deprecated since 0.13 and will be removed in 0.15. "
            "Please use InterpolationMode enum."
420
421
422
        )
        interpolation = _interpolation_modes_from_int(interpolation)

423
424
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
425

vfdev's avatar
vfdev committed
426
    if not isinstance(img, torch.Tensor):
427
        if antialias is not None and not antialias:
428
            warnings.warn("Anti-alias option is always applied for PIL Image input. Argument antialias is ignored.")
429
        pil_interpolation = pil_modes_mapping[interpolation]
430
        return F_pil.resize(img, size=size, interpolation=pil_interpolation, max_size=max_size)
vfdev's avatar
vfdev committed
431

432
    return F_t.resize(img, size=size, interpolation=interpolation.value, max_size=max_size, antialias=antialias)
433
434


435
436
def pad(img: Tensor, padding: List[int], fill: int = 0, padding_mode: str = "constant") -> Tensor:
    r"""Pad the given image on all sides with the given "pad" value.
437
    If the image is torch Tensor, it is expected
438
439
440
    to have [..., H, W] shape, where ... means at most 2 leading dimensions for mode reflect and symmetric,
    at most 3 leading dimensions for mode edge,
    and an arbitrary number of leading dimensions for mode constant
441
442

    Args:
443
        img (PIL Image or Tensor): Image to be padded.
444
445
446
        padding (int or sequence): Padding on each border. If a single int is provided this
            is used to pad all borders. If sequence of length 2 is provided this is the padding
            on left/right and top/bottom respectively. If a sequence of length 4 is provided
447
            this is the padding for the left, top, right and bottom borders respectively.
448
449
450
451

            .. note::
                In torchscript mode padding as single int is not supported, use a sequence of
                length 1: ``[padding, ]``.
452
        fill (number or tuple): Pixel fill value for constant fill. Default is 0.
453
454
455
            If a tuple of length 3, it is used to fill R, G, B channels respectively.
            This value is only used when the padding_mode is constant.
            Only number is supported for torch Tensor.
456
            Only int or tuple value is supported for PIL Image.
457
458
        padding_mode (str): Type of padding. Should be: constant, edge, reflect or symmetric.
            Default is constant.
459
460
461

            - constant: pads with a constant value, this value is specified with fill

462
463
            - edge: pads with the last value at the edge of the image.
              If input a 5D torch Tensor, the last 3 dimensions will be padded instead of the last 2
464

465
466
467
            - reflect: pads with reflection of image without repeating the last value on the edge.
              For example, padding [1, 2, 3, 4] with 2 elements on both sides in reflect mode
              will result in [3, 2, 1, 2, 3, 4, 3, 2]
468

469
470
471
            - symmetric: pads with reflection of image repeating the last value on the edge.
              For example, padding [1, 2, 3, 4] with 2 elements on both sides in symmetric mode
              will result in [2, 1, 1, 2, 3, 4, 4, 3]
472
473

    Returns:
474
        PIL Image or Tensor: Padded image.
475
    """
476
477
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(pad)
478
479
    if not isinstance(img, torch.Tensor):
        return F_pil.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
480

481
    return F_t.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
482
483


vfdev's avatar
vfdev committed
484
485
def crop(img: Tensor, top: int, left: int, height: int, width: int) -> Tensor:
    """Crop the given image at specified location and output size.
486
    If the image is torch Tensor, it is expected
487
488
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
    If image size is smaller than output size along any edge, image is padded with 0 and then cropped.
489

490
    Args:
vfdev's avatar
vfdev committed
491
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
492
493
494
495
        top (int): Vertical component of the top left corner of the crop box.
        left (int): Horizontal component of the top left corner of the crop box.
        height (int): Height of the crop box.
        width (int): Width of the crop box.
496

497
    Returns:
vfdev's avatar
vfdev committed
498
        PIL Image or Tensor: Cropped image.
499
500
    """

501
502
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(crop)
vfdev's avatar
vfdev committed
503
504
    if not isinstance(img, torch.Tensor):
        return F_pil.crop(img, top, left, height, width)
505

vfdev's avatar
vfdev committed
506
    return F_t.crop(img, top, left, height, width)
507

vfdev's avatar
vfdev committed
508
509
510

def center_crop(img: Tensor, output_size: List[int]) -> Tensor:
    """Crops the given image at the center.
511
    If the image is torch Tensor, it is expected
512
513
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
    If image size is smaller than output size along any edge, image is padded with 0 and then center cropped.
514

515
    Args:
vfdev's avatar
vfdev committed
516
        img (PIL Image or Tensor): Image to be cropped.
517
        output_size (sequence or int): (height, width) of the crop box. If int or sequence with single int,
vfdev's avatar
vfdev committed
518
519
            it is used for both directions.

520
    Returns:
vfdev's avatar
vfdev committed
521
        PIL Image or Tensor: Cropped image.
522
    """
523
524
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(center_crop)
525
526
    if isinstance(output_size, numbers.Number):
        output_size = (int(output_size), int(output_size))
vfdev's avatar
vfdev committed
527
528
529
    elif isinstance(output_size, (tuple, list)) and len(output_size) == 1:
        output_size = (output_size[0], output_size[0])

530
    _, image_height, image_width = get_dimensions(img)
531
    crop_height, crop_width = output_size
vfdev's avatar
vfdev committed
532

533
534
535
536
537
538
539
540
    if crop_width > image_width or crop_height > image_height:
        padding_ltrb = [
            (crop_width - image_width) // 2 if crop_width > image_width else 0,
            (crop_height - image_height) // 2 if crop_height > image_height else 0,
            (crop_width - image_width + 1) // 2 if crop_width > image_width else 0,
            (crop_height - image_height + 1) // 2 if crop_height > image_height else 0,
        ]
        img = pad(img, padding_ltrb, fill=0)  # PIL uses fill value 0
541
        _, image_height, image_width = get_dimensions(img)
542
543
544
        if crop_width == image_width and crop_height == image_height:
            return img

545
546
    crop_top = int(round((image_height - crop_height) / 2.0))
    crop_left = int(round((image_width - crop_width) / 2.0))
547
    return crop(img, crop_top, crop_left, crop_height, crop_width)
548
549


550
def resized_crop(
551
552
553
554
555
556
557
    img: Tensor,
    top: int,
    left: int,
    height: int,
    width: int,
    size: List[int],
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
558
    antialias: Optional[bool] = None,
559
560
) -> Tensor:
    """Crop the given image and resize it to desired size.
561
    If the image is torch Tensor, it is expected
562
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
563

564
    Notably used in :class:`~torchvision.transforms.RandomResizedCrop`.
565
566

    Args:
567
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
568
569
570
571
        top (int): Vertical component of the top left corner of the crop box.
        left (int): Horizontal component of the top left corner of the crop box.
        height (int): Height of the crop box.
        width (int): Width of the crop box.
572
        size (sequence or int): Desired output size. Same semantics as ``resize``.
573
574
575
576
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`.
            Default is ``InterpolationMode.BILINEAR``. If input is Tensor, only ``InterpolationMode.NEAREST``,
            ``InterpolationMode.BILINEAR`` and ``InterpolationMode.BICUBIC`` are supported.
577
578
            For backward compatibility integer values (e.g. ``PIL.Image[.Resampling].NEAREST``) are still accepted,
            but deprecated since 0.13 and will be removed in 0.15. Please use InterpolationMode enum.
579
580
581
582
        antialias (bool, optional): antialias flag. If ``img`` is PIL Image, the flag is ignored and anti-alias
            is always used. If ``img`` is Tensor, the flag is False by default and can be set to True for
            ``InterpolationMode.BILINEAR`` and ``InterpolationMode.BICUBIC`` modes.
            This can help making the output for PIL images and tensors closer.
583
    Returns:
584
        PIL Image or Tensor: Cropped image.
585
    """
586
587
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(resized_crop)
588
    img = crop(img, top, left, height, width)
589
    img = resize(img, size, interpolation, antialias=antialias)
590
591
592
    return img


593
def hflip(img: Tensor) -> Tensor:
594
    """Horizontally flip the given image.
595
596

    Args:
vfdev's avatar
vfdev committed
597
        img (PIL Image or Tensor): Image to be flipped. If img
598
            is a Tensor, it is expected to be in [..., H, W] format,
599
            where ... means it can have an arbitrary number of leading
600
            dimensions.
601
602

    Returns:
vfdev's avatar
vfdev committed
603
        PIL Image or Tensor:  Horizontally flipped image.
604
    """
605
606
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(hflip)
607
608
    if not isinstance(img, torch.Tensor):
        return F_pil.hflip(img)
609

610
    return F_t.hflip(img)
611
612


613
def _get_perspective_coeffs(startpoints: List[List[int]], endpoints: List[List[int]]) -> List[float]:
614
615
    """Helper function to get the coefficients (a, b, c, d, e, f, g, h) for the perspective transforms.

Vitaliy Chiley's avatar
Vitaliy Chiley committed
616
    In Perspective Transform each pixel (x, y) in the original image gets transformed as,
617
618
619
     (x, y) -> ( (ax + by + c) / (gx + hy + 1), (dx + ey + f) / (gx + hy + 1) )

    Args:
620
621
622
623
624
        startpoints (list of list of ints): List containing four lists of two integers corresponding to four corners
            ``[top-left, top-right, bottom-right, bottom-left]`` of the original image.
        endpoints (list of list of ints): List containing four lists of two integers corresponding to four corners
            ``[top-left, top-right, bottom-right, bottom-left]`` of the transformed image.

625
626
627
    Returns:
        octuple (a, b, c, d, e, f, g, h) for transforming each pixel.
    """
628
629
630
631
632
    a_matrix = torch.zeros(2 * len(startpoints), 8, dtype=torch.float)

    for i, (p1, p2) in enumerate(zip(endpoints, startpoints)):
        a_matrix[2 * i, :] = torch.tensor([p1[0], p1[1], 1, 0, 0, 0, -p2[0] * p1[0], -p2[0] * p1[1]])
        a_matrix[2 * i + 1, :] = torch.tensor([0, 0, 0, p1[0], p1[1], 1, -p2[1] * p1[0], -p2[1] * p1[1]])
633

634
    b_matrix = torch.tensor(startpoints, dtype=torch.float).view(8)
635
    res = torch.linalg.lstsq(a_matrix, b_matrix, driver="gels").solution
636

637
    output: List[float] = res.tolist()
638
    return output
639
640


641
def perspective(
642
643
644
645
646
    img: Tensor,
    startpoints: List[List[int]],
    endpoints: List[List[int]],
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
    fill: Optional[List[float]] = None,
647
648
) -> Tensor:
    """Perform perspective transform of the given image.
649
    If the image is torch Tensor, it is expected
650
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
651
652

    Args:
653
654
655
656
657
        img (PIL Image or Tensor): Image to be transformed.
        startpoints (list of list of ints): List containing four lists of two integers corresponding to four corners
            ``[top-left, top-right, bottom-right, bottom-left]`` of the original image.
        endpoints (list of list of ints): List containing four lists of two integers corresponding to four corners
            ``[top-left, top-right, bottom-right, bottom-left]`` of the transformed image.
658
659
660
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`. Default is ``InterpolationMode.BILINEAR``.
            If input is Tensor, only ``InterpolationMode.NEAREST``, ``InterpolationMode.BILINEAR`` are supported.
661
662
            For backward compatibility integer values (e.g. ``PIL.Image[.Resampling].NEAREST``) are still accepted,
            but deprecated since 0.13 and will be removed in 0.15. Please use InterpolationMode enum.
663
664
        fill (sequence or number, optional): Pixel fill value for the area outside the transformed
            image. If given a number, the value is used for all bands respectively.
665
666
667
668

            .. note::
                In torchscript mode single int/float value is not supported, please use a sequence
                of length 1: ``[value, ]``.
669

670
    Returns:
671
        PIL Image or Tensor: transformed Image.
672
    """
673
674
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(perspective)
675

676
    coeffs = _get_perspective_coeffs(startpoints, endpoints)
677

678
679
680
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
681
682
            "Argument 'interpolation' of type int is deprecated since 0.13 and will be removed in 0.15. "
            "Please use InterpolationMode enum."
683
684
685
        )
        interpolation = _interpolation_modes_from_int(interpolation)

686
687
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
688

689
    if not isinstance(img, torch.Tensor):
690
691
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.perspective(img, coeffs, interpolation=pil_interpolation, fill=fill)
692

693
    return F_t.perspective(img, coeffs, interpolation=interpolation.value, fill=fill)
694
695


696
def vflip(img: Tensor) -> Tensor:
697
    """Vertically flip the given image.
698
699

    Args:
vfdev's avatar
vfdev committed
700
        img (PIL Image or Tensor): Image to be flipped. If img
701
            is a Tensor, it is expected to be in [..., H, W] format,
702
            where ... means it can have an arbitrary number of leading
703
            dimensions.
704
705

    Returns:
706
        PIL Image or Tensor:  Vertically flipped image.
707
    """
708
709
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(vflip)
710
711
    if not isinstance(img, torch.Tensor):
        return F_pil.vflip(img)
712

713
    return F_t.vflip(img)
714
715


vfdev's avatar
vfdev committed
716
717
def five_crop(img: Tensor, size: List[int]) -> Tuple[Tensor, Tensor, Tensor, Tensor, Tensor]:
    """Crop the given image into four corners and the central crop.
718
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
719
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
720
721
722
723
724
725

    .. Note::
        This transform returns a tuple of images and there may be a
        mismatch in the number of inputs and targets your ``Dataset`` returns.

    Args:
vfdev's avatar
vfdev committed
726
727
728
        img (PIL Image or Tensor): Image to be cropped.
        size (sequence or int): Desired output size of the crop. If size is an
            int instead of sequence like (h, w), a square crop (size, size) is
729
            made. If provided a sequence of length 1, it will be interpreted as (size[0], size[0]).
730

731
    Returns:
732
       tuple: tuple (tl, tr, bl, br, center)
733
       Corresponding top left, top right, bottom left, bottom right and center crop.
734
    """
735
736
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(five_crop)
737
738
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
739
740
    elif isinstance(size, (tuple, list)) and len(size) == 1:
        size = (size[0], size[0])
741

vfdev's avatar
vfdev committed
742
743
744
    if len(size) != 2:
        raise ValueError("Please provide only two dimensions (h, w) for size.")

745
    _, image_height, image_width = get_dimensions(img)
746
747
748
749
750
    crop_height, crop_width = size
    if crop_width > image_width or crop_height > image_height:
        msg = "Requested crop size {} is bigger than input size {}"
        raise ValueError(msg.format(size, (image_height, image_width)))

vfdev's avatar
vfdev committed
751
752
753
754
755
756
757
758
    tl = crop(img, 0, 0, crop_height, crop_width)
    tr = crop(img, 0, image_width - crop_width, crop_height, crop_width)
    bl = crop(img, image_height - crop_height, 0, crop_height, crop_width)
    br = crop(img, image_height - crop_height, image_width - crop_width, crop_height, crop_width)

    center = center_crop(img, [crop_height, crop_width])

    return tl, tr, bl, br, center
759
760


vfdev's avatar
vfdev committed
761
762
763
def ten_crop(img: Tensor, size: List[int], vertical_flip: bool = False) -> List[Tensor]:
    """Generate ten cropped images from the given image.
    Crop the given image into four corners and the central crop plus the
764
    flipped version of these (horizontal flipping is used by default).
765
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
766
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
767
768
769
770
771

    .. Note::
        This transform returns a tuple of images and there may be a
        mismatch in the number of inputs and targets your ``Dataset`` returns.

772
    Args:
vfdev's avatar
vfdev committed
773
        img (PIL Image or Tensor): Image to be cropped.
774
        size (sequence or int): Desired output size of the crop. If size is an
775
            int instead of sequence like (h, w), a square crop (size, size) is
776
            made. If provided a sequence of length 1, it will be interpreted as (size[0], size[0]).
777
        vertical_flip (bool): Use vertical flipping instead of horizontal
778
779

    Returns:
780
        tuple: tuple (tl, tr, bl, br, center, tl_flip, tr_flip, bl_flip, br_flip, center_flip)
781
782
        Corresponding top left, top right, bottom left, bottom right and
        center crop and same for the flipped image.
783
    """
784
785
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(ten_crop)
786
787
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
788
789
790
791
792
    elif isinstance(size, (tuple, list)) and len(size) == 1:
        size = (size[0], size[0])

    if len(size) != 2:
        raise ValueError("Please provide only two dimensions (h, w) for size.")
793
794
795
796
797
798
799
800
801
802
803
804

    first_five = five_crop(img, size)

    if vertical_flip:
        img = vflip(img)
    else:
        img = hflip(img)

    second_five = five_crop(img, size)
    return first_five + second_five


805
def adjust_brightness(img: Tensor, brightness_factor: float) -> Tensor:
806
    """Adjust brightness of an image.
807
808

    Args:
vfdev's avatar
vfdev committed
809
        img (PIL Image or Tensor): Image to be adjusted.
810
811
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
            where ... means it can have an arbitrary number of leading dimensions.
812
813
814
815
816
        brightness_factor (float):  How much to adjust the brightness. Can be
            any non negative number. 0 gives a black image, 1 gives the
            original image while 2 increases the brightness by a factor of 2.

    Returns:
vfdev's avatar
vfdev committed
817
        PIL Image or Tensor: Brightness adjusted image.
818
    """
819
820
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_brightness)
821
822
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_brightness(img, brightness_factor)
823

824
    return F_t.adjust_brightness(img, brightness_factor)
825
826


827
def adjust_contrast(img: Tensor, contrast_factor: float) -> Tensor:
828
    """Adjust contrast of an image.
829
830

    Args:
vfdev's avatar
vfdev committed
831
        img (PIL Image or Tensor): Image to be adjusted.
832
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
833
            where ... means it can have an arbitrary number of leading dimensions.
834
835
836
837
838
        contrast_factor (float): How much to adjust the contrast. Can be any
            non negative number. 0 gives a solid gray image, 1 gives the
            original image while 2 increases the contrast by a factor of 2.

    Returns:
vfdev's avatar
vfdev committed
839
        PIL Image or Tensor: Contrast adjusted image.
840
    """
841
842
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_contrast)
843
844
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_contrast(img, contrast_factor)
845

846
    return F_t.adjust_contrast(img, contrast_factor)
847
848


849
def adjust_saturation(img: Tensor, saturation_factor: float) -> Tensor:
850
851
852
    """Adjust color saturation of an image.

    Args:
vfdev's avatar
vfdev committed
853
        img (PIL Image or Tensor): Image to be adjusted.
854
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
855
            where ... means it can have an arbitrary number of leading dimensions.
856
857
858
859
860
        saturation_factor (float):  How much to adjust the saturation. 0 will
            give a black and white image, 1 will give the original image while
            2 will enhance the saturation by a factor of 2.

    Returns:
vfdev's avatar
vfdev committed
861
        PIL Image or Tensor: Saturation adjusted image.
862
    """
863
864
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_saturation)
865
866
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_saturation(img, saturation_factor)
867

868
    return F_t.adjust_saturation(img, saturation_factor)
869
870


871
def adjust_hue(img: Tensor, hue_factor: float) -> Tensor:
872
873
874
875
876
877
878
879
880
    """Adjust hue of an image.

    The image hue is adjusted by converting the image to HSV and
    cyclically shifting the intensities in the hue channel (H).
    The image is then converted back to original image mode.

    `hue_factor` is the amount of shift in H channel and must be in the
    interval `[-0.5, 0.5]`.

881
882
883
    See `Hue`_ for more details.

    .. _Hue: https://en.wikipedia.org/wiki/Hue
884
885

    Args:
886
        img (PIL Image or Tensor): Image to be adjusted.
887
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
888
            where ... means it can have an arbitrary number of leading dimensions.
889
            If img is PIL Image mode "1", "I", "F" and modes with transparency (alpha channel) are not supported.
890
891
892
            Note: the pixel values of the input image has to be non-negative for conversion to HSV space;
            thus it does not work if you normalize your image to an interval with negative values,
            or use an interpolation that generates negative values before using this function.
893
894
895
896
897
898
899
        hue_factor (float):  How much to shift the hue channel. Should be in
            [-0.5, 0.5]. 0.5 and -0.5 give complete reversal of hue channel in
            HSV space in positive and negative direction respectively.
            0 means no shift. Therefore, both -0.5 and 0.5 will give an image
            with complementary colors while 0 gives the original image.

    Returns:
900
        PIL Image or Tensor: Hue adjusted image.
901
    """
902
903
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_hue)
904
905
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_hue(img, hue_factor)
906

907
    return F_t.adjust_hue(img, hue_factor)
908
909


910
def adjust_gamma(img: Tensor, gamma: float, gain: float = 1) -> Tensor:
911
    r"""Perform gamma correction on an image.
912
913
914
915

    Also known as Power Law Transform. Intensities in RGB mode are adjusted
    based on the following equation:

916
917
918
919
    .. math::
        I_{\text{out}} = 255 \times \text{gain} \times \left(\frac{I_{\text{in}}}{255}\right)^{\gamma}

    See `Gamma Correction`_ for more details.
920

921
    .. _Gamma Correction: https://en.wikipedia.org/wiki/Gamma_correction
922
923

    Args:
924
        img (PIL Image or Tensor): PIL Image to be adjusted.
925
926
927
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
            where ... means it can have an arbitrary number of leading dimensions.
            If img is PIL Image, modes with transparency (alpha channel) are not supported.
928
929
930
        gamma (float): Non negative real number, same as :math:`\gamma` in the equation.
            gamma larger than 1 make the shadows darker,
            while gamma smaller than 1 make dark regions lighter.
931
        gain (float): The constant multiplier.
932
933
    Returns:
        PIL Image or Tensor: Gamma correction adjusted image.
934
    """
935
936
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_gamma)
937
938
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_gamma(img, gamma, gain)
939

940
    return F_t.adjust_gamma(img, gamma, gain)
941
942


vfdev's avatar
vfdev committed
943
def _get_inverse_affine_matrix(
944
    center: List[float], angle: float, translate: List[float], scale: float, shear: List[float], inverted: bool = True
vfdev's avatar
vfdev committed
945
) -> List[float]:
946
947
    # Helper method to compute inverse matrix for affine transformation

948
949
950
    # Pillow requires inverse affine transformation matrix:
    # Affine matrix is : M = T * C * RotateScaleShear * C^-1
    #
951
952
    # where T is translation matrix: [1, 0, tx | 0, 1, ty | 0, 0, 1]
    #       C is translation matrix to keep center: [1, 0, cx | 0, 1, cy | 0, 0, 1]
953
954
955
    #       RotateScaleShear is rotation with scale and shear matrix
    #
    #       RotateScaleShear(a, s, (sx, sy)) =
956
    #       = R(a) * S(s) * SHy(sy) * SHx(sx)
957
958
    #       = [ s*cos(a - sy)/cos(sy), s*(-cos(a - sy)*tan(sx)/cos(sy) - sin(a)), 0 ]
    #         [ s*sin(a + sy)/cos(sy), s*(-sin(a - sy)*tan(sx)/cos(sy) + cos(a)), 0 ]
959
960
961
962
963
    #         [ 0                    , 0                                      , 1 ]
    # where R is a rotation matrix, S is a scaling matrix, and SHx and SHy are the shears:
    # SHx(s) = [1, -tan(s)] and SHy(s) = [1      , 0]
    #          [0, 1      ]              [-tan(s), 1]
    #
964
    # Thus, the inverse is M^-1 = C * RotateScaleShear^-1 * C^-1 * T^-1
965

966
    rot = math.radians(angle)
967
968
    sx = math.radians(shear[0])
    sy = math.radians(shear[1])
969
970
971
972
973

    cx, cy = center
    tx, ty = translate

    # RSS without scaling
vfdev's avatar
vfdev committed
974
975
976
977
    a = math.cos(rot - sy) / math.cos(sy)
    b = -math.cos(rot - sy) * math.tan(sx) / math.cos(sy) - math.sin(rot)
    c = math.sin(rot - sy) / math.cos(sy)
    d = -math.sin(rot - sy) * math.tan(sx) / math.cos(sy) + math.cos(rot)
978

979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
    if inverted:
        # Inverted rotation matrix with scale and shear
        # det([[a, b], [c, d]]) == 1, since det(rotation) = 1 and det(shear) = 1
        matrix = [d, -b, 0.0, -c, a, 0.0]
        matrix = [x / scale for x in matrix]
        # Apply inverse of translation and of center translation: RSS^-1 * C^-1 * T^-1
        matrix[2] += matrix[0] * (-cx - tx) + matrix[1] * (-cy - ty)
        matrix[5] += matrix[3] * (-cx - tx) + matrix[4] * (-cy - ty)
        # Apply center translation: C * RSS^-1 * C^-1 * T^-1
        matrix[2] += cx
        matrix[5] += cy
    else:
        matrix = [a, b, 0.0, c, d, 0.0]
        matrix = [x * scale for x in matrix]
        # Apply inverse of center translation: RSS * C^-1
        matrix[2] += matrix[0] * (-cx) + matrix[1] * (-cy)
        matrix[5] += matrix[3] * (-cx) + matrix[4] * (-cy)
        # Apply translation and center : T * C * RSS * C^-1
        matrix[2] += cx + tx
        matrix[5] += cy + ty
999

vfdev's avatar
vfdev committed
1000
    return matrix
1001

vfdev's avatar
vfdev committed
1002

vfdev's avatar
vfdev committed
1003
def rotate(
1004
1005
1006
1007
1008
1009
1010
    img: Tensor,
    angle: float,
    interpolation: InterpolationMode = InterpolationMode.NEAREST,
    expand: bool = False,
    center: Optional[List[int]] = None,
    fill: Optional[List[float]] = None,
    resample: Optional[int] = None,
vfdev's avatar
vfdev committed
1011
1012
) -> Tensor:
    """Rotate the image by angle.
1013
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
1014
1015
1016
1017
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.

    Args:
        img (PIL Image or Tensor): image to be rotated.
1018
        angle (number): rotation angle value in degrees, counter-clockwise.
1019
1020
1021
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`. Default is ``InterpolationMode.NEAREST``.
            If input is Tensor, only ``InterpolationMode.NEAREST``, ``InterpolationMode.BILINEAR`` are supported.
1022
1023
            For backward compatibility integer values (e.g. ``PIL.Image[.Resampling].NEAREST``) are still accepted,
            but deprecated since 0.13 and will be removed in 0.15. Please use InterpolationMode enum.
vfdev's avatar
vfdev committed
1024
1025
1026
1027
        expand (bool, optional): Optional expansion flag.
            If true, expands the output image to make it large enough to hold the entire rotated image.
            If false or omitted, make the output image the same size as the input image.
            Note that the expand flag assumes rotation around the center and no translation.
1028
        center (sequence, optional): Optional center of rotation. Origin is the upper left corner.
vfdev's avatar
vfdev committed
1029
            Default is the center of the image.
1030
1031
        fill (sequence or number, optional): Pixel fill value for the area outside the transformed
            image. If given a number, the value is used for all bands respectively.
1032
1033
1034
1035

            .. note::
                In torchscript mode single int/float value is not supported, please use a sequence
                of length 1: ``[value, ]``.
1036
1037
1038
1039
        resample (int, optional):
            .. warning::
                This parameter was deprecated in ``0.12`` and will be removed in ``0.14``. Please use ``interpolation``
                instead.
vfdev's avatar
vfdev committed
1040
1041
1042
1043
1044
1045
1046

    Returns:
        PIL Image or Tensor: Rotated image.

    .. _filters: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#filters

    """
1047
1048
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(rotate)
1049
1050
    if resample is not None:
        warnings.warn(
1051
1052
            "The parameter 'resample' is deprecated since 0.12 and will be removed 0.14. "
            "Please use 'interpolation' instead."
1053
1054
1055
1056
1057
1058
        )
        interpolation = _interpolation_modes_from_int(resample)

    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
1059
1060
            "Argument 'interpolation' of type int is deprecated since 0.13 and will be removed in 0.15. "
            "Please use InterpolationMode enum."
1061
1062
1063
        )
        interpolation = _interpolation_modes_from_int(interpolation)

vfdev's avatar
vfdev committed
1064
1065
1066
1067
1068
1069
    if not isinstance(angle, (int, float)):
        raise TypeError("Argument angle should be int or float")

    if center is not None and not isinstance(center, (list, tuple)):
        raise TypeError("Argument center should be a sequence")

1070
1071
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
1072

vfdev's avatar
vfdev committed
1073
    if not isinstance(img, torch.Tensor):
1074
1075
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.rotate(img, angle=angle, interpolation=pil_interpolation, expand=expand, center=center, fill=fill)
vfdev's avatar
vfdev committed
1076
1077
1078

    center_f = [0.0, 0.0]
    if center is not None:
1079
        _, height, width = get_dimensions(img)
1080
        # Center values should be in pixel coordinates but translated such that (0, 0) corresponds to image center.
1081
        center_f = [1.0 * (c - s * 0.5) for c, s in zip(center, [width, height])]
1082

vfdev's avatar
vfdev committed
1083
1084
1085
    # due to current incoherence of rotation angle direction between affine and rotate implementations
    # we need to set -angle.
    matrix = _get_inverse_affine_matrix(center_f, -angle, [0.0, 0.0], 1.0, [0.0, 0.0])
1086
    return F_t.rotate(img, matrix=matrix, interpolation=interpolation.value, expand=expand, fill=fill)
vfdev's avatar
vfdev committed
1087
1088


vfdev's avatar
vfdev committed
1089
def affine(
1090
1091
1092
1093
1094
1095
1096
1097
1098
    img: Tensor,
    angle: float,
    translate: List[int],
    scale: float,
    shear: List[float],
    interpolation: InterpolationMode = InterpolationMode.NEAREST,
    fill: Optional[List[float]] = None,
    resample: Optional[int] = None,
    fillcolor: Optional[List[float]] = None,
1099
    center: Optional[List[int]] = None,
vfdev's avatar
vfdev committed
1100
1101
) -> Tensor:
    """Apply affine transformation on the image keeping image center invariant.
1102
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
1103
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
1104
1105

    Args:
vfdev's avatar
vfdev committed
1106
        img (PIL Image or Tensor): image to transform.
1107
1108
        angle (number): rotation angle in degrees between -180 and 180, clockwise direction.
        translate (sequence of integers): horizontal and vertical translations (post-rotation translation)
1109
        scale (float): overall scale
1110
1111
        shear (float or sequence): shear angle value in degrees between -180 to 180, clockwise direction.
            If a sequence is specified, the first value corresponds to a shear parallel to the x axis, while
vfdev's avatar
vfdev committed
1112
            the second value corresponds to a shear parallel to the y axis.
1113
1114
1115
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`. Default is ``InterpolationMode.NEAREST``.
            If input is Tensor, only ``InterpolationMode.NEAREST``, ``InterpolationMode.BILINEAR`` are supported.
1116
1117
            For backward compatibility integer values (e.g. ``PIL.Image[.Resampling].NEAREST``) are still accepted,
            but deprecated since 0.13 and will be removed in 0.15. Please use InterpolationMode enum.
1118
1119
        fill (sequence or number, optional): Pixel fill value for the area outside the transformed
            image. If given a number, the value is used for all bands respectively.
1120
1121
1122
1123

            .. note::
                In torchscript mode single int/float value is not supported, please use a sequence
                of length 1: ``[value, ]``.
1124
1125
1126
1127
1128
1129
1130
        fillcolor (sequence or number, optional):
            .. warning::
                This parameter was deprecated in ``0.12`` and will be removed in ``0.14``. Please use ``fill`` instead.
        resample (int, optional):
            .. warning::
                This parameter was deprecated in ``0.12`` and will be removed in ``0.14``. Please use ``interpolation``
                instead.
1131
1132
        center (sequence, optional): Optional center of rotation. Origin is the upper left corner.
            Default is the center of the image.
vfdev's avatar
vfdev committed
1133
1134
1135

    Returns:
        PIL Image or Tensor: Transformed image.
1136
    """
1137
1138
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(affine)
1139
1140
    if resample is not None:
        warnings.warn(
1141
1142
            "The parameter 'resample' is deprecated since 0.12 and will be removed in 0.14. "
            "Please use 'interpolation' instead."
1143
1144
1145
1146
1147
1148
        )
        interpolation = _interpolation_modes_from_int(resample)

    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
1149
1150
            "Argument 'interpolation' of type int is deprecated since 0.13 and will be removed in 0.15. "
            "Please use InterpolationMode enum."
1151
1152
1153
1154
        )
        interpolation = _interpolation_modes_from_int(interpolation)

    if fillcolor is not None:
1155
1156
1157
1158
        warnings.warn(
            "The parameter 'fillcolor' is deprecated since 0.12 and will be removed in 0.14. "
            "Please use 'fill' instead."
        )
1159
1160
        fill = fillcolor

vfdev's avatar
vfdev committed
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
    if not isinstance(angle, (int, float)):
        raise TypeError("Argument angle should be int or float")

    if not isinstance(translate, (list, tuple)):
        raise TypeError("Argument translate should be a sequence")

    if len(translate) != 2:
        raise ValueError("Argument translate should be a sequence of length 2")

    if scale <= 0.0:
        raise ValueError("Argument scale should be positive")

    if not isinstance(shear, (numbers.Number, (list, tuple))):
        raise TypeError("Shear should be either a single value or a sequence of two values")

1176
1177
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
1178

vfdev's avatar
vfdev committed
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
    if isinstance(angle, int):
        angle = float(angle)

    if isinstance(translate, tuple):
        translate = list(translate)

    if isinstance(shear, numbers.Number):
        shear = [shear, 0.0]

    if isinstance(shear, tuple):
        shear = list(shear)

    if len(shear) == 1:
        shear = [shear[0], shear[0]]

    if len(shear) != 2:
1195
        raise ValueError(f"Shear should be a sequence containing two values. Got {shear}")
vfdev's avatar
vfdev committed
1196

1197
1198
1199
    if center is not None and not isinstance(center, (list, tuple)):
        raise TypeError("Argument center should be a sequence")

1200
    _, height, width = get_dimensions(img)
vfdev's avatar
vfdev committed
1201
    if not isinstance(img, torch.Tensor):
1202
        # center = (width * 0.5 + 0.5, height * 0.5 + 0.5)
vfdev's avatar
vfdev committed
1203
1204
        # it is visually better to estimate the center without 0.5 offset
        # otherwise image rotated by 90 degrees is shifted vs output image of torch.rot90 or F_t.affine
1205
        if center is None:
1206
            center = [width * 0.5, height * 0.5]
vfdev's avatar
vfdev committed
1207
        matrix = _get_inverse_affine_matrix(center, angle, translate, scale, shear)
1208
1209
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.affine(img, matrix=matrix, interpolation=pil_interpolation, fill=fill)
1210

1211
1212
    center_f = [0.0, 0.0]
    if center is not None:
1213
        _, height, width = get_dimensions(img)
1214
        # Center values should be in pixel coordinates but translated such that (0, 0) corresponds to image center.
1215
        center_f = [1.0 * (c - s * 0.5) for c, s in zip(center, [width, height])]
1216

1217
    translate_f = [1.0 * t for t in translate]
1218
    matrix = _get_inverse_affine_matrix(center_f, angle, translate_f, scale, shear)
1219
    return F_t.affine(img, matrix=matrix, interpolation=interpolation.value, fill=fill)
1220
1221


1222
@torch.jit.unused
1223
def to_grayscale(img, num_output_channels=1):
1224
    """Convert PIL image of any mode (RGB, HSV, LAB, etc) to grayscale version of image.
1225
    This transform does not support torch Tensor.
1226
1227

    Args:
1228
        img (PIL Image): PIL Image to be converted to grayscale.
1229
        num_output_channels (int): number of channels of the output image. Value can be 1 or 3. Default is 1.
1230
1231

    Returns:
1232
1233
        PIL Image: Grayscale version of the image.

1234
1235
        - if num_output_channels = 1 : returned image is single channel
        - if num_output_channels = 3 : returned image is 3 channel with r = g = b
1236
    """
1237
1238
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(to_grayscale)
1239
1240
    if isinstance(img, Image.Image):
        return F_pil.to_grayscale(img, num_output_channels)
1241

1242
1243
1244
1245
1246
    raise TypeError("Input should be PIL Image")


def rgb_to_grayscale(img: Tensor, num_output_channels: int = 1) -> Tensor:
    """Convert RGB image to grayscale version of image.
1247
1248
    If the image is torch Tensor, it is expected
    to have [..., 3, H, W] shape, where ... means an arbitrary number of leading dimensions
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260

    Note:
        Please, note that this method supports only RGB images as input. For inputs in other color spaces,
        please, consider using meth:`~torchvision.transforms.functional.to_grayscale` with PIL Image.

    Args:
        img (PIL Image or Tensor): RGB Image to be converted to grayscale.
        num_output_channels (int): number of channels of the output image. Value can be 1 or 3. Default, 1.

    Returns:
        PIL Image or Tensor: Grayscale version of the image.

1261
1262
        - if num_output_channels = 1 : returned image is single channel
        - if num_output_channels = 3 : returned image is 3 channel with r = g = b
1263
    """
1264
1265
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(rgb_to_grayscale)
1266
1267
1268
1269
    if not isinstance(img, torch.Tensor):
        return F_pil.to_grayscale(img, num_output_channels)

    return F_t.rgb_to_grayscale(img, num_output_channels)
1270
1271


1272
def erase(img: Tensor, i: int, j: int, h: int, w: int, v: Tensor, inplace: bool = False) -> Tensor:
1273
    """Erase the input Tensor Image with given value.
1274
    This transform does not support PIL Image.
1275
1276
1277
1278
1279
1280
1281
1282

    Args:
        img (Tensor Image): Tensor image of size (C, H, W) to be erased
        i (int): i in (i,j) i.e coordinates of the upper left corner.
        j (int): j in (i,j) i.e coordinates of the upper left corner.
        h (int): Height of the erased region.
        w (int): Width of the erased region.
        v: Erasing value.
Zhun Zhong's avatar
Zhun Zhong committed
1283
        inplace(bool, optional): For in-place operations. By default is set False.
1284
1285
1286
1287

    Returns:
        Tensor Image: Erased image.
    """
1288
1289
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(erase)
1290
    if not isinstance(img, torch.Tensor):
1291
        raise TypeError(f"img should be Tensor Image. Got {type(img)}")
1292

1293
    return F_t.erase(img, i, j, h, w, v, inplace=inplace)
1294
1295
1296


def gaussian_blur(img: Tensor, kernel_size: List[int], sigma: Optional[List[float]] = None) -> Tensor:
1297
1298
1299
    """Performs Gaussian blurring on the image by given kernel.
    If the image is torch Tensor, it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
1300
1301
1302
1303
1304

    Args:
        img (PIL Image or Tensor): Image to be blurred
        kernel_size (sequence of ints or int): Gaussian kernel size. Can be a sequence of integers
            like ``(kx, ky)`` or a single integer for square kernels.
1305
1306
1307
1308

            .. note::
                In torchscript mode kernel_size as single int is not supported, use a sequence of
                length 1: ``[ksize, ]``.
1309
1310
1311
1312
        sigma (sequence of floats or float, optional): Gaussian kernel standard deviation. Can be a
            sequence of floats like ``(sigma_x, sigma_y)`` or a single float to define the
            same sigma in both X/Y directions. If None, then it is computed using
            ``kernel_size`` as ``sigma = 0.3 * ((kernel_size - 1) * 0.5 - 1) + 0.8``.
1313
1314
1315
1316
1317
            Default, None.

            .. note::
                In torchscript mode sigma as single float is
                not supported, use a sequence of length 1: ``[sigma, ]``.
1318
1319
1320
1321

    Returns:
        PIL Image or Tensor: Gaussian Blurred version of the image.
    """
1322
1323
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(gaussian_blur)
1324
    if not isinstance(kernel_size, (int, list, tuple)):
1325
        raise TypeError(f"kernel_size should be int or a sequence of integers. Got {type(kernel_size)}")
1326
1327
1328
    if isinstance(kernel_size, int):
        kernel_size = [kernel_size, kernel_size]
    if len(kernel_size) != 2:
1329
        raise ValueError(f"If kernel_size is a sequence its length should be 2. Got {len(kernel_size)}")
1330
1331
    for ksize in kernel_size:
        if ksize % 2 == 0 or ksize < 0:
1332
            raise ValueError(f"kernel_size should have odd and positive integers. Got {kernel_size}")
1333
1334
1335
1336
1337

    if sigma is None:
        sigma = [ksize * 0.15 + 0.35 for ksize in kernel_size]

    if sigma is not None and not isinstance(sigma, (int, float, list, tuple)):
1338
        raise TypeError(f"sigma should be either float or sequence of floats. Got {type(sigma)}")
1339
1340
1341
1342
1343
    if isinstance(sigma, (int, float)):
        sigma = [float(sigma), float(sigma)]
    if isinstance(sigma, (list, tuple)) and len(sigma) == 1:
        sigma = [sigma[0], sigma[0]]
    if len(sigma) != 2:
1344
        raise ValueError(f"If sigma is a sequence, its length should be 2. Got {len(sigma)}")
1345
    for s in sigma:
1346
        if s <= 0.0:
1347
            raise ValueError(f"sigma should have positive values. Got {sigma}")
1348
1349
1350
1351

    t_img = img
    if not isinstance(img, torch.Tensor):
        if not F_pil._is_pil_image(img):
1352
            raise TypeError(f"img should be PIL Image or Tensor. Got {type(img)}")
1353

1354
        t_img = pil_to_tensor(img)
1355
1356
1357
1358

    output = F_t.gaussian_blur(t_img, kernel_size, sigma)

    if not isinstance(img, torch.Tensor):
1359
        output = to_pil_image(output, mode=img.mode)
1360
    return output
1361
1362
1363


def invert(img: Tensor) -> Tensor:
1364
    """Invert the colors of an RGB/grayscale image.
1365
1366
1367

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
1368
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1369
1370
            where ... means it can have an arbitrary number of leading dimensions.
            If img is PIL Image, it is expected to be in mode "L" or "RGB".
1371
1372
1373
1374

    Returns:
        PIL Image or Tensor: Color inverted image.
    """
1375
1376
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(invert)
1377
1378
1379
1380
1381
1382
1383
    if not isinstance(img, torch.Tensor):
        return F_pil.invert(img)

    return F_t.invert(img)


def posterize(img: Tensor, bits: int) -> Tensor:
1384
    """Posterize an image by reducing the number of bits for each color channel.
1385
1386
1387

    Args:
        img (PIL Image or Tensor): Image to have its colors posterized.
1388
            If img is torch Tensor, it should be of type torch.uint8 and
1389
1390
1391
            it is expected to be in [..., 1 or 3, H, W] format, where ... means
            it can have an arbitrary number of leading dimensions.
            If img is PIL Image, it is expected to be in mode "L" or "RGB".
1392
1393
1394
1395
        bits (int): The number of bits to keep for each channel (0-8).
    Returns:
        PIL Image or Tensor: Posterized image.
    """
1396
1397
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(posterize)
1398
    if not (0 <= bits <= 8):
1399
        raise ValueError(f"The number if bits should be between 0 and 8. Got {bits}")
1400
1401
1402
1403
1404
1405
1406
1407

    if not isinstance(img, torch.Tensor):
        return F_pil.posterize(img, bits)

    return F_t.posterize(img, bits)


def solarize(img: Tensor, threshold: float) -> Tensor:
1408
    """Solarize an RGB/grayscale image by inverting all pixel values above a threshold.
1409
1410
1411

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
1412
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1413
1414
            where ... means it can have an arbitrary number of leading dimensions.
            If img is PIL Image, it is expected to be in mode "L" or "RGB".
1415
1416
1417
1418
        threshold (float): All pixels equal or above this value are inverted.
    Returns:
        PIL Image or Tensor: Solarized image.
    """
1419
1420
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(solarize)
1421
1422
1423
1424
1425
1426
1427
    if not isinstance(img, torch.Tensor):
        return F_pil.solarize(img, threshold)

    return F_t.solarize(img, threshold)


def adjust_sharpness(img: Tensor, sharpness_factor: float) -> Tensor:
1428
    """Adjust the sharpness of an image.
1429
1430
1431

    Args:
        img (PIL Image or Tensor): Image to be adjusted.
1432
1433
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
            where ... means it can have an arbitrary number of leading dimensions.
1434
1435
1436
1437
1438
1439
1440
        sharpness_factor (float):  How much to adjust the sharpness. Can be
            any non negative number. 0 gives a blurred image, 1 gives the
            original image while 2 increases the sharpness by a factor of 2.

    Returns:
        PIL Image or Tensor: Sharpness adjusted image.
    """
1441
1442
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(adjust_sharpness)
1443
1444
1445
1446
1447
1448
1449
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_sharpness(img, sharpness_factor)

    return F_t.adjust_sharpness(img, sharpness_factor)


def autocontrast(img: Tensor) -> Tensor:
1450
    """Maximize contrast of an image by remapping its
1451
1452
1453
1454
1455
    pixels per channel so that the lowest becomes black and the lightest
    becomes white.

    Args:
        img (PIL Image or Tensor): Image on which autocontrast is applied.
1456
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1457
1458
            where ... means it can have an arbitrary number of leading dimensions.
            If img is PIL Image, it is expected to be in mode "L" or "RGB".
1459
1460
1461
1462

    Returns:
        PIL Image or Tensor: An image that was autocontrasted.
    """
1463
1464
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(autocontrast)
1465
1466
1467
1468
1469
1470
1471
    if not isinstance(img, torch.Tensor):
        return F_pil.autocontrast(img)

    return F_t.autocontrast(img)


def equalize(img: Tensor) -> Tensor:
1472
    """Equalize the histogram of an image by applying
1473
1474
1475
1476
1477
    a non-linear mapping to the input in order to create a uniform
    distribution of grayscale values in the output.

    Args:
        img (PIL Image or Tensor): Image on which equalize is applied.
1478
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1479
            where ... means it can have an arbitrary number of leading dimensions.
1480
            The tensor dtype must be ``torch.uint8`` and values are expected to be in ``[0, 255]``.
1481
            If img is PIL Image, it is expected to be in mode "P", "L" or "RGB".
1482
1483
1484
1485

    Returns:
        PIL Image or Tensor: An image that was equalized.
    """
1486
1487
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(equalize)
1488
1489
1490
1491
    if not isinstance(img, torch.Tensor):
        return F_pil.equalize(img)

    return F_t.equalize(img)
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555


def elastic_transform(
    img: Tensor,
    displacement: Tensor,
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
    fill: Optional[List[float]] = None,
) -> Tensor:
    """Transform a tensor image with elastic transformations.
    Given alpha and sigma, it will generate displacement
    vectors for all pixels based on random offsets. Alpha controls the strength
    and sigma controls the smoothness of the displacements.
    The displacements are added to an identity grid and the resulting grid is
    used to grid_sample from the image.

    Applications:
        Randomly transforms the morphology of objects in images and produces a
        see-through-water-like effect.

    Args:
        img (PIL Image or Tensor): Image on which elastic_transform is applied.
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
            where ... means it can have an arbitrary number of leading dimensions.
            If img is PIL Image, it is expected to be in mode "P", "L" or "RGB".
        displacement (Tensor): The displacement field.
        interpolation (InterpolationMode): Desired interpolation enum defined by
            :class:`torchvision.transforms.InterpolationMode`.
            Default is ``InterpolationMode.BILINEAR``.
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
        fill (number or str or tuple): Pixel fill value for constant fill. Default is 0.
            If a tuple of length 3, it is used to fill R, G, B channels respectively.
            This value is only used when the padding_mode is constant.
            Only number is supported for torch Tensor.
            Only int or str or tuple value is supported for PIL Image.
    """
    if not torch.jit.is_scripting() and not torch.jit.is_tracing():
        _log_api_usage_once(elastic_transform)
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
        )
        interpolation = _interpolation_modes_from_int(interpolation)

    if not isinstance(displacement, torch.Tensor):
        raise TypeError("displacement should be a Tensor")

    t_img = img
    if not isinstance(img, torch.Tensor):
        if not F_pil._is_pil_image(img):
            raise TypeError(f"img should be PIL Image or Tensor. Got {type(img)}")
        t_img = pil_to_tensor(img)

    output = F_t.elastic_transform(
        t_img,
        displacement,
        interpolation=interpolation.value,
        fill=fill,
    )

    if not isinstance(img, torch.Tensor):
        output = to_pil_image(output, mode=img.mode)
    return output