functional.py 56.5 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
18
19
from . import functional_pil as F_pil
from . import functional_tensor as F_t

20

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

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


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


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

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


61
62
63
64
65
66
67
68
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
69
70
    """
    if isinstance(img, torch.Tensor):
71
        return F_t.get_image_size(img)
72

73
    return F_pil.get_image_size(img)
74

vfdev's avatar
vfdev committed
75

76
77
78
79
80
81
82
83
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.
84
    """
85
    if isinstance(img, torch.Tensor):
86
        return F_t.get_image_num_channels(img)
87

88
    return F_pil.get_image_num_channels(img)
89
90


vfdev's avatar
vfdev committed
91
92
@torch.jit.unused
def _is_numpy(img: Any) -> bool:
93
94
95
    return isinstance(img, np.ndarray)


vfdev's avatar
vfdev committed
96
97
@torch.jit.unused
def _is_numpy_image(img: Any) -> bool:
98
    return img.ndim in {2, 3}
99
100
101
102


def to_tensor(pic):
    """Convert a ``PIL Image`` or ``numpy.ndarray`` to tensor.
103
    This function does not support torchscript.
104

105
    See :class:`~torchvision.transforms.ToTensor` for more details.
106
107
108
109
110
111
112

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

    Returns:
        Tensor: Converted image.
    """
113
114
    if not (F_pil._is_pil_image(pic) or _is_numpy(pic)):
        raise TypeError("pic should be PIL Image or ndarray. Got {}".format(type(pic)))
115

116
    if _is_numpy(pic) and not _is_numpy_image(pic):
117
        raise ValueError("pic should be 2/3 dimensional. Got {} dimensions.".format(pic.ndim))
118

119
120
    default_float_dtype = torch.get_default_dtype()

121
122
    if isinstance(pic, np.ndarray):
        # handle numpy array
surgan12's avatar
surgan12 committed
123
124
125
        if pic.ndim == 2:
            pic = pic[:, :, None]

126
        img = torch.from_numpy(pic.transpose((2, 0, 1))).contiguous()
127
        # backward compatibility
128
        if isinstance(img, torch.ByteTensor):
129
            return img.to(dtype=default_float_dtype).div(255)
130
131
        else:
            return img
132
133

    if accimage is not None and isinstance(pic, accimage.Image):
134
        nppic = np.zeros([pic.channels, pic.height, pic.width], dtype=np.float32)
135
        pic.copyto(nppic)
136
        return torch.from_numpy(nppic).to(dtype=default_float_dtype)
137
138

    # handle PIL Image
139
140
    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))
141

142
    if pic.mode == "1":
143
        img = 255 * img
144
    img = img.view(pic.size[1], pic.size[0], len(pic.getbands()))
145
    # put it from HWC to CHW format
146
    img = img.permute((2, 0, 1)).contiguous()
147
    if isinstance(img, torch.ByteTensor):
148
        return img.to(dtype=default_float_dtype).div(255)
149
150
151
152
    else:
        return img


153
154
def pil_to_tensor(pic):
    """Convert a ``PIL Image`` to a tensor of the same type.
155
    This function does not support torchscript.
156

vfdev's avatar
vfdev committed
157
    See :class:`~torchvision.transforms.PILToTensor` for more details.
158
159
160
161
162
163
164

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

    Returns:
        Tensor: Converted image.
    """
165
    if not F_pil._is_pil_image(pic):
166
        raise TypeError("pic should be PIL Image. Got {}".format(type(pic)))
167
168

    if accimage is not None and isinstance(pic, accimage.Image):
169
170
        # accimage format is always uint8 internally, so always return uint8 here
        nppic = np.zeros([pic.channels, pic.height, pic.width], dtype=np.uint8)
171
172
173
174
175
176
177
178
179
180
181
        pic.copyto(nppic)
        return torch.as_tensor(nppic)

    # handle PIL Image
    img = torch.as_tensor(np.asarray(pic))
    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


182
183
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
184
    This function does not support PIL Image.
185
186
187
188
189
190

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

    Returns:
vfdev's avatar
vfdev committed
191
        Tensor: Converted image
192
193
194
195
196
197
198
199
200
201
202
203

    .. 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``.
    """
204
    if not isinstance(image, torch.Tensor):
205
        raise TypeError("Input img should be Tensor Image")
206
207

    return F_t.convert_image_dtype(image, dtype)
208
209


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

213
    See :class:`~torchvision.transforms.ToPILImage` for more details.
214
215
216
217
218

    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).

219
    .. _PIL.Image mode: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#concept-modes
220
221
222
223

    Returns:
        PIL Image: Image converted to PIL Image.
    """
224
225
    if not (isinstance(pic, torch.Tensor) or isinstance(pic, np.ndarray)):
        raise TypeError("pic should be Tensor or ndarray. Got {}.".format(type(pic)))
226

Varun Agrawal's avatar
Varun Agrawal committed
227
228
    elif isinstance(pic, torch.Tensor):
        if pic.ndimension() not in {2, 3}:
229
            raise ValueError("pic should be 2/3 dimensional. Got {} dimensions.".format(pic.ndimension()))
Varun Agrawal's avatar
Varun Agrawal committed
230
231
232

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

235
236
        # check number of channels
        if pic.shape[-3] > 4:
237
            raise ValueError("pic should not have > 4 channels. Got {} channels.".format(pic.shape[-3]))
238

Varun Agrawal's avatar
Varun Agrawal committed
239
240
    elif isinstance(pic, np.ndarray):
        if pic.ndim not in {2, 3}:
241
            raise ValueError("pic should be 2/3 dimensional. Got {} dimensions.".format(pic.ndim))
Varun Agrawal's avatar
Varun Agrawal committed
242
243
244
245
246

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

247
248
        # check number of channels
        if pic.shape[-1] > 4:
249
            raise ValueError("pic should not have > 4 channels. Got {} channels.".format(pic.shape[-1]))
250

251
    npimg = pic
Varun Agrawal's avatar
Varun Agrawal committed
252
    if isinstance(pic, torch.Tensor):
253
        if pic.is_floating_point() and mode != "F":
254
255
            pic = pic.mul(255).byte()
        npimg = np.transpose(pic.cpu().numpy(), (1, 2, 0))
256
257

    if not isinstance(npimg, np.ndarray):
258
        raise TypeError("Input pic must be a torch.Tensor or NumPy ndarray, " + "not {}".format(type(npimg)))
259
260
261
262
263

    if npimg.shape[2] == 1:
        expected_mode = None
        npimg = npimg[:, :, 0]
        if npimg.dtype == np.uint8:
264
            expected_mode = "L"
vfdev's avatar
vfdev committed
265
        elif npimg.dtype == np.int16:
266
            expected_mode = "I;16"
vfdev's avatar
vfdev committed
267
        elif npimg.dtype == np.int32:
268
            expected_mode = "I"
269
        elif npimg.dtype == np.float32:
270
            expected_mode = "F"
271
        if mode is not None and mode != expected_mode:
272
273
274
            raise ValueError(
                "Incorrect mode ({}) supplied for input type {}. Should be {}".format(mode, np.dtype, expected_mode)
            )
275
276
        mode = expected_mode

surgan12's avatar
surgan12 committed
277
    elif npimg.shape[2] == 2:
278
        permitted_2_channel_modes = ["LA"]
surgan12's avatar
surgan12 committed
279
280
281
282
        if mode is not None and mode not in permitted_2_channel_modes:
            raise ValueError("Only modes {} are supported for 2D inputs".format(permitted_2_channel_modes))

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

285
    elif npimg.shape[2] == 4:
286
        permitted_4_channel_modes = ["RGBA", "CMYK", "RGBX"]
287
288
289
290
        if mode is not None and mode not in permitted_4_channel_modes:
            raise ValueError("Only modes {} are supported for 4D inputs".format(permitted_4_channel_modes))

        if mode is None and npimg.dtype == np.uint8:
291
            mode = "RGBA"
292
    else:
293
        permitted_3_channel_modes = ["RGB", "YCbCr", "HSV"]
294
295
296
        if mode is not None and mode not in permitted_3_channel_modes:
            raise ValueError("Only modes {} are supported for 3D inputs".format(permitted_3_channel_modes))
        if mode is None and npimg.dtype == np.uint8:
297
            mode = "RGB"
298
299

    if mode is None:
300
        raise TypeError("Input type {} is not supported".format(npimg.dtype))
301
302
303
304

    return Image.fromarray(npimg, mode=mode)


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

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

312
    See :class:`~torchvision.transforms.Normalize` for more details.
313
314

    Args:
315
        tensor (Tensor): Float tensor image of size (C, H, W) or (B, C, H, W) to be normalized.
316
        mean (sequence): Sequence of means for each channel.
317
        std (sequence): Sequence of standard deviations for each channel.
318
        inplace(bool,optional): Bool to make this operation inplace.
319
320
321
322

    Returns:
        Tensor: Normalized Tensor image.
    """
323
    if not isinstance(tensor, torch.Tensor):
324
        raise TypeError("Input tensor should be a torch tensor. Got {}.".format(type(tensor)))
325

326
    if not tensor.is_floating_point():
327
        raise TypeError("Input tensor should be a float tensor. Got {}.".format(tensor.dtype))
328

329
    if tensor.ndim < 3:
330
331
332
333
        raise ValueError(
            "Expected tensor to be a tensor image of size (..., C, H, W). Got tensor.size() = "
            "{}.".format(tensor.size())
        )
334

surgan12's avatar
surgan12 committed
335
336
337
    if not inplace:
        tensor = tensor.clone()

338
339
340
    dtype = tensor.dtype
    mean = torch.as_tensor(mean, dtype=dtype, device=tensor.device)
    std = torch.as_tensor(std, dtype=dtype, device=tensor.device)
341
    if (std == 0).any():
342
        raise ValueError("std evaluated to zero after conversion to {}, leading to division by zero.".format(dtype))
343
    if mean.ndim == 1:
344
        mean = mean.view(-1, 1, 1)
345
    if std.ndim == 1:
346
        std = std.view(-1, 1, 1)
347
    tensor.sub_(mean).div_(std)
348
    return tensor
349
350


351
352
353
354
355
356
357
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
358
    r"""Resize the input image to the given size.
359
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
360
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
361

362
363
364
365
    .. 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
366
367
        types. See also below the ``antialias`` parameter, which can help making the output of PIL images and tensors
        closer.
368

369
    Args:
vfdev's avatar
vfdev committed
370
        img (PIL Image or Tensor): Image to be resized.
371
372
        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
373
            the smaller edge of the image will be matched to this number maintaining
374
            the aspect ratio. i.e, if height > width, then image will be rescaled to
vfdev's avatar
vfdev committed
375
            :math:`\left(\text{size} \times \frac{\text{height}}{\text{width}}, \text{size}\right)`.
376
377
378

            .. note::
                In torchscript mode size as single int is not supported, use a sequence of length 1: ``[size, ]``.
379
380
381
382
        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.
383
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
384
385
386
387
        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
388
            ``max_size``. As a result, ``size`` might be overruled, i.e the
389
390
391
            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).
392
        antialias (bool, optional): antialias flag. If ``img`` is PIL Image, the flag is ignored and anti-alias
393
394
395
            is always used. If ``img`` is Tensor, the flag is False by default and can be set to True for
            ``InterpolationMode.BILINEAR`` only mode. This can help making the output for PIL images and tensors
            closer.
396
397
398

            .. warning::
                There is no autodiff support for ``antialias=True`` option with input ``img`` as Tensor.
399
400

    Returns:
vfdev's avatar
vfdev committed
401
        PIL Image or Tensor: Resized image.
402
    """
403
404
405
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
406
407
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
408
409
410
        )
        interpolation = _interpolation_modes_from_int(interpolation)

411
412
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
413

vfdev's avatar
vfdev committed
414
    if not isinstance(img, torch.Tensor):
415
        if antialias is not None and not antialias:
416
            warnings.warn("Anti-alias option is always applied for PIL Image input. Argument antialias is ignored.")
417
        pil_interpolation = pil_modes_mapping[interpolation]
418
        return F_pil.resize(img, size=size, interpolation=pil_interpolation, max_size=max_size)
vfdev's avatar
vfdev committed
419

420
    return F_t.resize(img, size=size, interpolation=interpolation.value, max_size=max_size, antialias=antialias)
421
422
423


def scale(*args, **kwargs):
424
    warnings.warn("The use of the transforms.Scale transform is deprecated, " + "please use transforms.Resize instead.")
425
426
427
    return resize(*args, **kwargs)


428
429
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.
430
    If the image is torch Tensor, it is expected
431
432
433
    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
434
435

    Args:
436
        img (PIL Image or Tensor): Image to be padded.
437
438
439
        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
440
            this is the padding for the left, top, right and bottom borders respectively.
441
442
443
444

            .. note::
                In torchscript mode padding as single int is not supported, use a sequence of
                length 1: ``[padding, ]``.
445
446
447
448
449
        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.
450
451
        padding_mode (str): Type of padding. Should be: constant, edge, reflect or symmetric.
            Default is constant.
452
453
454

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

455
456
            - 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
457

458
459
460
            - 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]
461

462
463
464
            - 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]
465
466

    Returns:
467
        PIL Image or Tensor: Padded image.
468
    """
469
470
    if not isinstance(img, torch.Tensor):
        return F_pil.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
471

472
    return F_t.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
473
474


vfdev's avatar
vfdev committed
475
476
def crop(img: Tensor, top: int, left: int, height: int, width: int) -> Tensor:
    """Crop the given image at specified location and output size.
477
    If the image is torch Tensor, it is expected
478
479
    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.
480

481
    Args:
vfdev's avatar
vfdev committed
482
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
483
484
485
486
        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.
487

488
    Returns:
vfdev's avatar
vfdev committed
489
        PIL Image or Tensor: Cropped image.
490
491
    """

vfdev's avatar
vfdev committed
492
493
    if not isinstance(img, torch.Tensor):
        return F_pil.crop(img, top, left, height, width)
494

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

vfdev's avatar
vfdev committed
497
498
499

def center_crop(img: Tensor, output_size: List[int]) -> Tensor:
    """Crops the given image at the center.
500
    If the image is torch Tensor, it is expected
501
502
    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.
503

504
    Args:
vfdev's avatar
vfdev committed
505
        img (PIL Image or Tensor): Image to be cropped.
506
        output_size (sequence or int): (height, width) of the crop box. If int or sequence with single int,
vfdev's avatar
vfdev committed
507
508
            it is used for both directions.

509
    Returns:
vfdev's avatar
vfdev committed
510
        PIL Image or Tensor: Cropped image.
511
    """
512
513
    if isinstance(output_size, numbers.Number):
        output_size = (int(output_size), int(output_size))
vfdev's avatar
vfdev committed
514
515
516
    elif isinstance(output_size, (tuple, list)) and len(output_size) == 1:
        output_size = (output_size[0], output_size[0])

517
    image_width, image_height = get_image_size(img)
518
    crop_height, crop_width = output_size
vfdev's avatar
vfdev committed
519

520
521
522
523
524
525
526
527
    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
528
        image_width, image_height = get_image_size(img)
529
530
531
        if crop_width == image_width and crop_height == image_height:
            return img

532
533
    crop_top = int(round((image_height - crop_height) / 2.0))
    crop_left = int(round((image_width - crop_width) / 2.0))
534
    return crop(img, crop_top, crop_left, crop_height, crop_width)
535
536


537
def resized_crop(
538
539
540
541
542
543
544
    img: Tensor,
    top: int,
    left: int,
    height: int,
    width: int,
    size: List[int],
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
545
546
) -> Tensor:
    """Crop the given image and resize it to desired size.
547
    If the image is torch Tensor, it is expected
548
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
549

550
    Notably used in :class:`~torchvision.transforms.RandomResizedCrop`.
551
552

    Args:
553
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
554
555
556
557
        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.
558
        size (sequence or int): Desired output size. Same semantics as ``resize``.
559
560
561
562
        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.
563
564
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.

565
    Returns:
566
        PIL Image or Tensor: Cropped image.
567
    """
568
    img = crop(img, top, left, height, width)
569
570
571
572
    img = resize(img, size, interpolation)
    return img


573
def hflip(img: Tensor) -> Tensor:
574
    """Horizontally flip the given image.
575
576

    Args:
vfdev's avatar
vfdev committed
577
        img (PIL Image or Tensor): Image to be flipped. If img
578
            is a Tensor, it is expected to be in [..., H, W] format,
579
            where ... means it can have an arbitrary number of leading
580
            dimensions.
581
582

    Returns:
vfdev's avatar
vfdev committed
583
        PIL Image or Tensor:  Horizontally flipped image.
584
    """
585
586
    if not isinstance(img, torch.Tensor):
        return F_pil.hflip(img)
587

588
    return F_t.hflip(img)
589
590


591
def _get_perspective_coeffs(startpoints: List[List[int]], endpoints: List[List[int]]) -> List[float]:
592
593
    """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
594
    In Perspective Transform each pixel (x, y) in the original image gets transformed as,
595
596
597
     (x, y) -> ( (ax + by + c) / (gx + hy + 1), (dx + ey + f) / (gx + hy + 1) )

    Args:
598
599
600
601
602
        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.

603
604
605
    Returns:
        octuple (a, b, c, d, e, f, g, h) for transforming each pixel.
    """
606
607
608
609
610
    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]])
611

612
    b_matrix = torch.tensor(startpoints, dtype=torch.float).view(8)
613
    res = torch.linalg.lstsq(a_matrix, b_matrix, driver="gels").solution
614

615
    output: List[float] = res.tolist()
616
    return output
617
618


619
def perspective(
620
621
622
623
624
    img: Tensor,
    startpoints: List[List[int]],
    endpoints: List[List[int]],
    interpolation: InterpolationMode = InterpolationMode.BILINEAR,
    fill: Optional[List[float]] = None,
625
626
) -> Tensor:
    """Perform perspective transform of the given image.
627
    If the image is torch Tensor, it is expected
628
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
629
630

    Args:
631
632
633
634
635
        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.
636
637
638
        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.
639
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
640
641
        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.
642
643
644
645

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

647
    Returns:
648
        PIL Image or Tensor: transformed Image.
649
    """
650

651
    coeffs = _get_perspective_coeffs(startpoints, endpoints)
652

653
654
655
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
656
657
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
658
659
660
        )
        interpolation = _interpolation_modes_from_int(interpolation)

661
662
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
663

664
    if not isinstance(img, torch.Tensor):
665
666
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.perspective(img, coeffs, interpolation=pil_interpolation, fill=fill)
667

668
    return F_t.perspective(img, coeffs, interpolation=interpolation.value, fill=fill)
669
670


671
def vflip(img: Tensor) -> Tensor:
672
    """Vertically flip the given image.
673
674

    Args:
vfdev's avatar
vfdev committed
675
        img (PIL Image or Tensor): Image to be flipped. If img
676
            is a Tensor, it is expected to be in [..., H, W] format,
677
            where ... means it can have an arbitrary number of leading
678
            dimensions.
679
680

    Returns:
681
        PIL Image or Tensor:  Vertically flipped image.
682
    """
683
684
    if not isinstance(img, torch.Tensor):
        return F_pil.vflip(img)
685

686
    return F_t.vflip(img)
687
688


vfdev's avatar
vfdev committed
689
690
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.
691
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
692
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
693
694
695
696
697
698

    .. 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
699
700
701
        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
702
            made. If provided a sequence of length 1, it will be interpreted as (size[0], size[0]).
703

704
    Returns:
705
       tuple: tuple (tl, tr, bl, br, center)
706
       Corresponding top left, top right, bottom left, bottom right and center crop.
707
708
709
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
710
711
    elif isinstance(size, (tuple, list)) and len(size) == 1:
        size = (size[0], size[0])
712

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

716
    image_width, image_height = get_image_size(img)
717
718
719
720
721
    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
722
723
724
725
726
727
728
729
    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
730
731


vfdev's avatar
vfdev committed
732
733
734
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
735
    flipped version of these (horizontal flipping is used by default).
736
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
737
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
738
739
740
741
742

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

743
    Args:
vfdev's avatar
vfdev committed
744
        img (PIL Image or Tensor): Image to be cropped.
745
        size (sequence or int): Desired output size of the crop. If size is an
746
            int instead of sequence like (h, w), a square crop (size, size) is
747
            made. If provided a sequence of length 1, it will be interpreted as (size[0], size[0]).
748
        vertical_flip (bool): Use vertical flipping instead of horizontal
749
750

    Returns:
751
        tuple: tuple (tl, tr, bl, br, center, tl_flip, tr_flip, bl_flip, br_flip, center_flip)
752
753
        Corresponding top left, top right, bottom left, bottom right and
        center crop and same for the flipped image.
754
755
756
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
757
758
759
760
761
    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.")
762
763
764
765
766
767
768
769
770
771
772
773

    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


774
def adjust_brightness(img: Tensor, brightness_factor: float) -> Tensor:
775
    """Adjust brightness of an image.
776
777

    Args:
vfdev's avatar
vfdev committed
778
        img (PIL Image or Tensor): Image to be adjusted.
779
780
            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.
781
782
783
784
785
        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
786
        PIL Image or Tensor: Brightness adjusted image.
787
    """
788
789
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_brightness(img, brightness_factor)
790

791
    return F_t.adjust_brightness(img, brightness_factor)
792
793


794
def adjust_contrast(img: Tensor, contrast_factor: float) -> Tensor:
795
    """Adjust contrast of an image.
796
797

    Args:
vfdev's avatar
vfdev committed
798
        img (PIL Image or Tensor): Image to be adjusted.
799
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
800
            where ... means it can have an arbitrary number of leading dimensions.
801
802
803
804
805
        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
806
        PIL Image or Tensor: Contrast adjusted image.
807
    """
808
809
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_contrast(img, contrast_factor)
810

811
    return F_t.adjust_contrast(img, contrast_factor)
812
813


814
def adjust_saturation(img: Tensor, saturation_factor: float) -> Tensor:
815
816
817
    """Adjust color saturation of an image.

    Args:
vfdev's avatar
vfdev committed
818
        img (PIL Image or Tensor): Image to be adjusted.
819
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
820
            where ... means it can have an arbitrary number of leading dimensions.
821
822
823
824
825
        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
826
        PIL Image or Tensor: Saturation adjusted image.
827
    """
828
829
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_saturation(img, saturation_factor)
830

831
    return F_t.adjust_saturation(img, saturation_factor)
832
833


834
def adjust_hue(img: Tensor, hue_factor: float) -> Tensor:
835
836
837
838
839
840
841
842
843
    """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]`.

844
845
846
    See `Hue`_ for more details.

    .. _Hue: https://en.wikipedia.org/wiki/Hue
847
848

    Args:
849
        img (PIL Image or Tensor): Image to be adjusted.
850
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
851
            where ... means it can have an arbitrary number of leading dimensions.
852
            If img is PIL Image mode "1", "I", "F" and modes with transparency (alpha channel) are not supported.
853
854
855
856
857
858
859
        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:
860
        PIL Image or Tensor: Hue adjusted image.
861
    """
862
863
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_hue(img, hue_factor)
864

865
    return F_t.adjust_hue(img, hue_factor)
866
867


868
def adjust_gamma(img: Tensor, gamma: float, gain: float = 1) -> Tensor:
869
    r"""Perform gamma correction on an image.
870
871
872
873

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

874
875
876
877
    .. math::
        I_{\text{out}} = 255 \times \text{gain} \times \left(\frac{I_{\text{in}}}{255}\right)^{\gamma}

    See `Gamma Correction`_ for more details.
878

879
    .. _Gamma Correction: https://en.wikipedia.org/wiki/Gamma_correction
880
881

    Args:
882
        img (PIL Image or Tensor): PIL Image to be adjusted.
883
884
885
            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.
886
887
888
        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.
889
        gain (float): The constant multiplier.
890
891
    Returns:
        PIL Image or Tensor: Gamma correction adjusted image.
892
    """
893
894
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_gamma(img, gamma, gain)
895

896
    return F_t.adjust_gamma(img, gamma, gain)
897
898


vfdev's avatar
vfdev committed
899
def _get_inverse_affine_matrix(
900
    center: List[float], angle: float, translate: List[float], scale: float, shear: List[float]
vfdev's avatar
vfdev committed
901
) -> List[float]:
902
903
904
905
906
907
908
    # Helper method to compute inverse matrix for affine transformation

    # As it is explained in PIL.Image.rotate
    # We need compute INVERSE of affine transformation matrix: M = T * C * RSS * C^-1
    # 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]
    #       RSS is rotation with scale and shear matrix
909
910
911
912
913
914
915
916
917
918
    #       RSS(a, s, (sx, sy)) =
    #       = R(a) * S(s) * SHy(sy) * SHx(sx)
    #       = [ s*cos(a - sy)/cos(sy), s*(-cos(a - sy)*tan(x)/cos(y) - sin(a)), 0 ]
    #         [ s*sin(a + sy)/cos(sy), s*(-sin(a - sy)*tan(x)/cos(y) + cos(a)), 0 ]
    #         [ 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]
    #
919
920
    # Thus, the inverse is M^-1 = C * RSS^-1 * C^-1 * T^-1

921
922
923
924
925
926
927
    rot = math.radians(angle)
    sx, sy = [math.radians(s) for s in shear]

    cx, cy = center
    tx, ty = translate

    # RSS without scaling
vfdev's avatar
vfdev committed
928
929
930
931
    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)
932
933

    # Inverted rotation matrix with scale and shear
934
    # det([[a, b], [c, d]]) == 1, since det(rotation) = 1 and det(shear) = 1
vfdev's avatar
vfdev committed
935
936
    matrix = [d, -b, 0.0, -c, a, 0.0]
    matrix = [x / scale for x in matrix]
937
938

    # Apply inverse of translation and of center translation: RSS^-1 * C^-1 * T^-1
vfdev's avatar
vfdev committed
939
940
    matrix[2] += matrix[0] * (-cx - tx) + matrix[1] * (-cy - ty)
    matrix[5] += matrix[3] * (-cx - tx) + matrix[4] * (-cy - ty)
941
942

    # Apply center translation: C * RSS^-1 * C^-1 * T^-1
vfdev's avatar
vfdev committed
943
944
    matrix[2] += cx
    matrix[5] += cy
945

vfdev's avatar
vfdev committed
946
    return matrix
947

vfdev's avatar
vfdev committed
948

vfdev's avatar
vfdev committed
949
def rotate(
950
951
952
953
954
955
956
    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
957
958
) -> Tensor:
    """Rotate the image by angle.
959
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
960
961
962
963
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.

    Args:
        img (PIL Image or Tensor): image to be rotated.
964
        angle (number): rotation angle value in degrees, counter-clockwise.
965
966
967
        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.
968
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
vfdev's avatar
vfdev committed
969
970
971
972
        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.
973
        center (sequence, optional): Optional center of rotation. Origin is the upper left corner.
vfdev's avatar
vfdev committed
974
            Default is the center of the image.
975
976
        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.
977
978
979
980

            .. note::
                In torchscript mode single int/float value is not supported, please use a sequence
                of length 1: ``[value, ]``.
vfdev's avatar
vfdev committed
981
982
983
984
985
986
987

    Returns:
        PIL Image or Tensor: Rotated image.

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

    """
988
989
990
991
992
993
994
995
996
    if resample is not None:
        warnings.warn(
            "Argument resample is deprecated and will be removed since v0.10.0. Please, use interpolation instead"
        )
        interpolation = _interpolation_modes_from_int(resample)

    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
997
998
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
999
1000
1001
        )
        interpolation = _interpolation_modes_from_int(interpolation)

vfdev's avatar
vfdev committed
1002
1003
1004
1005
1006
1007
    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")

1008
1009
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
1010

vfdev's avatar
vfdev committed
1011
    if not isinstance(img, torch.Tensor):
1012
1013
        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
1014
1015
1016

    center_f = [0.0, 0.0]
    if center is not None:
1017
        img_size = get_image_size(img)
1018
1019
1020
        # Center values should be in pixel coordinates but translated such that (0, 0) corresponds to image center.
        center_f = [1.0 * (c - s * 0.5) for c, s in zip(center, img_size)]

vfdev's avatar
vfdev committed
1021
1022
1023
    # 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])
1024
    return F_t.rotate(img, matrix=matrix, interpolation=interpolation.value, expand=expand, fill=fill)
vfdev's avatar
vfdev committed
1025
1026


vfdev's avatar
vfdev committed
1027
def affine(
1028
1029
1030
1031
1032
1033
1034
1035
1036
    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,
vfdev's avatar
vfdev committed
1037
1038
) -> Tensor:
    """Apply affine transformation on the image keeping image center invariant.
1039
    If the image is torch Tensor, it is expected
vfdev's avatar
vfdev committed
1040
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
1041
1042

    Args:
vfdev's avatar
vfdev committed
1043
        img (PIL Image or Tensor): image to transform.
1044
1045
        angle (number): rotation angle in degrees between -180 and 180, clockwise direction.
        translate (sequence of integers): horizontal and vertical translations (post-rotation translation)
1046
        scale (float): overall scale
1047
1048
        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
1049
            the second value corresponds to a shear parallel to the y axis.
1050
1051
1052
        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.
1053
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
1054
1055
        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.
1056
1057
1058
1059

            .. note::
                In torchscript mode single int/float value is not supported, please use a sequence
                of length 1: ``[value, ]``.
1060
        fillcolor (sequence, int, float): deprecated argument and will be removed since v0.10.0.
1061
            Please use the ``fill`` parameter instead.
1062
        resample (int, optional): deprecated argument and will be removed since v0.10.0.
1063
            Please use the ``interpolation`` parameter instead.
vfdev's avatar
vfdev committed
1064
1065
1066

    Returns:
        PIL Image or Tensor: Transformed image.
1067
    """
1068
1069
1070
1071
1072
1073
1074
1075
1076
    if resample is not None:
        warnings.warn(
            "Argument resample is deprecated and will be removed since v0.10.0. Please, use interpolation instead"
        )
        interpolation = _interpolation_modes_from_int(resample)

    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
1077
1078
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
1079
1080
1081
1082
        )
        interpolation = _interpolation_modes_from_int(interpolation)

    if fillcolor is not None:
1083
        warnings.warn("Argument fillcolor is deprecated and will be removed since v0.10.0. Please, use fill instead")
1084
1085
        fill = fillcolor

vfdev's avatar
vfdev committed
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
    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")

1101
1102
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
1103

vfdev's avatar
vfdev committed
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
    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:
        raise ValueError("Shear should be a sequence containing two values. Got {}".format(shear))

1122
    img_size = get_image_size(img)
vfdev's avatar
vfdev committed
1123
1124
1125
1126
1127
1128
    if not isinstance(img, torch.Tensor):
        # center = (img_size[0] * 0.5 + 0.5, img_size[1] * 0.5 + 0.5)
        # 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
        center = [img_size[0] * 0.5, img_size[1] * 0.5]
        matrix = _get_inverse_affine_matrix(center, angle, translate, scale, shear)
1129
1130
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.affine(img, matrix=matrix, interpolation=pil_interpolation, fill=fill)
1131

1132
1133
    translate_f = [1.0 * t for t in translate]
    matrix = _get_inverse_affine_matrix([0.0, 0.0], angle, translate_f, scale, shear)
1134
    return F_t.affine(img, matrix=matrix, interpolation=interpolation.value, fill=fill)
1135
1136


1137
@torch.jit.unused
1138
def to_grayscale(img, num_output_channels=1):
1139
    """Convert PIL image of any mode (RGB, HSV, LAB, etc) to grayscale version of image.
1140
    This transform does not support torch Tensor.
1141
1142

    Args:
1143
        img (PIL Image): PIL Image to be converted to grayscale.
1144
        num_output_channels (int): number of channels of the output image. Value can be 1 or 3. Default is 1.
1145
1146

    Returns:
1147
1148
        PIL Image: Grayscale version of the image.

1149
1150
        - if num_output_channels = 1 : returned image is single channel
        - if num_output_channels = 3 : returned image is 3 channel with r = g = b
1151
    """
1152
1153
    if isinstance(img, Image.Image):
        return F_pil.to_grayscale(img, num_output_channels)
1154

1155
1156
1157
1158
1159
    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.
1160
1161
    If the image is torch Tensor, it is expected
    to have [..., 3, H, W] shape, where ... means an arbitrary number of leading dimensions
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173

    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.

1174
1175
        - if num_output_channels = 1 : returned image is single channel
        - if num_output_channels = 3 : returned image is 3 channel with r = g = b
1176
1177
1178
1179
1180
    """
    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)
1181
1182


1183
def erase(img: Tensor, i: int, j: int, h: int, w: int, v: Tensor, inplace: bool = False) -> Tensor:
1184
    """Erase the input Tensor Image with given value.
1185
    This transform does not support PIL Image.
1186
1187
1188
1189
1190
1191
1192
1193

    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
1194
        inplace(bool, optional): For in-place operations. By default is set False.
1195
1196
1197
1198
1199

    Returns:
        Tensor Image: Erased image.
    """
    if not isinstance(img, torch.Tensor):
1200
        raise TypeError("img should be Tensor Image. Got {}".format(type(img)))
1201

1202
1203
1204
    if not inplace:
        img = img.clone()

1205
    img[..., i : i + h, j : j + w] = v
1206
    return img
1207
1208
1209


def gaussian_blur(img: Tensor, kernel_size: List[int], sigma: Optional[List[float]] = None) -> Tensor:
1210
1211
1212
    """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.
1213
1214
1215
1216
1217

    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.
1218
1219
1220
1221

            .. note::
                In torchscript mode kernel_size as single int is not supported, use a sequence of
                length 1: ``[ksize, ]``.
1222
1223
1224
1225
        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``.
1226
1227
1228
1229
1230
            Default, None.

            .. note::
                In torchscript mode sigma as single float is
                not supported, use a sequence of length 1: ``[sigma, ]``.
1231
1232
1233
1234
1235

    Returns:
        PIL Image or Tensor: Gaussian Blurred version of the image.
    """
    if not isinstance(kernel_size, (int, list, tuple)):
1236
        raise TypeError("kernel_size should be int or a sequence of integers. Got {}".format(type(kernel_size)))
1237
1238
1239
    if isinstance(kernel_size, int):
        kernel_size = [kernel_size, kernel_size]
    if len(kernel_size) != 2:
1240
        raise ValueError("If kernel_size is a sequence its length should be 2. Got {}".format(len(kernel_size)))
1241
1242
    for ksize in kernel_size:
        if ksize % 2 == 0 or ksize < 0:
1243
            raise ValueError("kernel_size should have odd and positive integers. Got {}".format(kernel_size))
1244
1245
1246
1247
1248

    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)):
1249
        raise TypeError("sigma should be either float or sequence of floats. Got {}".format(type(sigma)))
1250
1251
1252
1253
1254
    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:
1255
        raise ValueError("If sigma is a sequence, its length should be 2. Got {}".format(len(sigma)))
1256
    for s in sigma:
1257
1258
        if s <= 0.0:
            raise ValueError("sigma should have positive values. Got {}".format(sigma))
1259
1260
1261
1262

    t_img = img
    if not isinstance(img, torch.Tensor):
        if not F_pil._is_pil_image(img):
1263
            raise TypeError("img should be PIL Image or Tensor. Got {}".format(type(img)))
1264
1265
1266
1267
1268
1269
1270
1271

        t_img = to_tensor(img)

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

    if not isinstance(img, torch.Tensor):
        output = to_pil_image(output)
    return output
1272
1273
1274


def invert(img: Tensor) -> Tensor:
1275
    """Invert the colors of an RGB/grayscale image.
1276
1277
1278

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
1279
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1280
1281
            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".
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292

    Returns:
        PIL Image or Tensor: Color inverted image.
    """
    if not isinstance(img, torch.Tensor):
        return F_pil.invert(img)

    return F_t.invert(img)


def posterize(img: Tensor, bits: int) -> Tensor:
1293
    """Posterize an image by reducing the number of bits for each color channel.
1294
1295
1296

    Args:
        img (PIL Image or Tensor): Image to have its colors posterized.
1297
            If img is torch Tensor, it should be of type torch.uint8 and
1298
1299
1300
            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".
1301
1302
1303
1304
1305
        bits (int): The number of bits to keep for each channel (0-8).
    Returns:
        PIL Image or Tensor: Posterized image.
    """
    if not (0 <= bits <= 8):
1306
        raise ValueError("The number if bits should be between 0 and 8. Got {}".format(bits))
1307
1308
1309
1310
1311
1312
1313
1314

    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:
1315
    """Solarize an RGB/grayscale image by inverting all pixel values above a threshold.
1316
1317
1318

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
1319
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1320
1321
            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".
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
        threshold (float): All pixels equal or above this value are inverted.
    Returns:
        PIL Image or Tensor: Solarized image.
    """
    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:
1333
    """Adjust the sharpness of an image.
1334
1335
1336

    Args:
        img (PIL Image or Tensor): Image to be adjusted.
1337
1338
            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.
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
        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.
    """
    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:
1353
    """Maximize contrast of an image by remapping its
1354
1355
1356
1357
1358
    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.
1359
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1360
1361
            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".
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372

    Returns:
        PIL Image or Tensor: An image that was autocontrasted.
    """
    if not isinstance(img, torch.Tensor):
        return F_pil.autocontrast(img)

    return F_t.autocontrast(img)


def equalize(img: Tensor) -> Tensor:
1373
    """Equalize the histogram of an image by applying
1374
1375
1376
1377
1378
    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.
1379
            If img is torch Tensor, it is expected to be in [..., 1 or 3, H, W] format,
1380
            where ... means it can have an arbitrary number of leading dimensions.
1381
            The tensor dtype must be ``torch.uint8`` and values are expected to be in ``[0, 255]``.
1382
            If img is PIL Image, it is expected to be in mode "P", "L" or "RGB".
1383
1384
1385
1386
1387
1388
1389
1390

    Returns:
        PIL Image or Tensor: An image that was equalized.
    """
    if not isinstance(img, torch.Tensor):
        return F_pil.equalize(img)

    return F_t.equalize(img)