functional.py 52 KB
Newer Older
1
import math
2
3
import numbers
import warnings
4
from enum import Enum
5
6

import numpy as np
vfdev's avatar
vfdev committed
7
from PIL import Image
8
9
10

import torch
from torch import Tensor
11
from typing import List, Tuple, Any, Optional
12

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

18
19
20
from . import functional_pil as F_pil
from . import functional_tensor as F_t

21

22
class InterpolationMode(Enum):
23
24
25
26
27
28
29
30
31
32
33
34
    """Interpolation modes
    """
    NEAREST = "nearest"
    BILINEAR = "bilinear"
    BICUBIC = "bicubic"
    # For PIL compatibility
    BOX = "box"
    HAMMING = "hamming"
    LANCZOS = "lanczos"


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


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

vfdev's avatar
vfdev committed
57
_is_pil_image = F_pil._is_pil_image
vfdev's avatar
vfdev committed
58
_parse_fill = F_pil._parse_fill
vfdev's avatar
vfdev committed
59
60
61
62
63
64
65


def _get_image_size(img: Tensor) -> List[int]:
    """Returns image sizea as (w, h)
    """
    if isinstance(img, torch.Tensor):
        return F_t._get_image_size(img)
66

vfdev's avatar
vfdev committed
67
    return F_pil._get_image_size(img)
68

vfdev's avatar
vfdev committed
69

70
71
72
73
74
75
76
def _get_image_num_channels(img: Tensor) -> int:
    if isinstance(img, torch.Tensor):
        return F_t._get_image_num_channels(img)

    return F_pil._get_image_num_channels(img)


vfdev's avatar
vfdev committed
77
78
@torch.jit.unused
def _is_numpy(img: Any) -> bool:
79
80
81
    return isinstance(img, np.ndarray)


vfdev's avatar
vfdev committed
82
83
@torch.jit.unused
def _is_numpy_image(img: Any) -> bool:
84
    return img.ndim in {2, 3}
85
86
87
88
89
90
91
92
93
94
95
96
97


def to_tensor(pic):
    """Convert a ``PIL Image`` or ``numpy.ndarray`` to tensor.

    See ``ToTensor`` for more details.

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

    Returns:
        Tensor: Converted image.
    """
vfdev's avatar
vfdev committed
98
    if not(F_pil._is_pil_image(pic) or _is_numpy(pic)):
99
100
        raise TypeError('pic should be PIL Image or ndarray. Got {}'.format(type(pic)))

101
102
103
    if _is_numpy(pic) and not _is_numpy_image(pic):
        raise ValueError('pic should be 2/3 dimensional. Got {} dimensions.'.format(pic.ndim))

104
105
    if isinstance(pic, np.ndarray):
        # handle numpy array
surgan12's avatar
surgan12 committed
106
107
108
        if pic.ndim == 2:
            pic = pic[:, :, None]

109
        img = torch.from_numpy(pic.transpose((2, 0, 1))).contiguous()
110
        # backward compatibility
111
112
113
114
        if isinstance(img, torch.ByteTensor):
            return img.float().div(255)
        else:
            return img
115
116
117
118
119
120
121
122
123
124
125

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

    # handle PIL Image
    if pic.mode == 'I':
        img = torch.from_numpy(np.array(pic, np.int32, copy=False))
    elif pic.mode == 'I;16':
        img = torch.from_numpy(np.array(pic, np.int16, copy=False))
126
127
    elif pic.mode == 'F':
        img = torch.from_numpy(np.array(pic, np.float32, copy=False))
128
129
    elif pic.mode == '1':
        img = 255 * torch.from_numpy(np.array(pic, np.uint8, copy=False))
130
131
    else:
        img = torch.ByteTensor(torch.ByteStorage.from_buffer(pic.tobytes()))
132
133

    img = img.view(pic.size[1], pic.size[0], len(pic.getbands()))
134
    # put it from HWC to CHW format
135
    img = img.permute((2, 0, 1)).contiguous()
136
137
138
139
140
141
    if isinstance(img, torch.ByteTensor):
        return img.float().div(255)
    else:
        return img


142
143
144
def pil_to_tensor(pic):
    """Convert a ``PIL Image`` to a tensor of the same type.

vfdev's avatar
vfdev committed
145
    See :class:`~torchvision.transforms.PILToTensor` for more details.
146
147
148
149
150
151
152

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

    Returns:
        Tensor: Converted image.
    """
153
    if not F_pil._is_pil_image(pic):
154
155
156
        raise TypeError('pic should be PIL Image. Got {}'.format(type(pic)))

    if accimage is not None and isinstance(pic, accimage.Image):
157
158
        # accimage format is always uint8 internally, so always return uint8 here
        nppic = np.zeros([pic.channels, pic.height, pic.width], dtype=np.uint8)
159
160
161
162
163
164
165
166
167
168
169
        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


170
171
172
173
174
175
176
177
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

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

    Returns:
vfdev's avatar
vfdev committed
178
        Tensor: Converted image
179
180
181
182
183
184
185
186
187
188
189
190

    .. 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``.
    """
191
192
193
194
    if not isinstance(image, torch.Tensor):
        raise TypeError('Input img should be Tensor Image')

    return F_t.convert_image_dtype(image, dtype)
195
196


197
198
199
def to_pil_image(pic, mode=None):
    """Convert a tensor or an ndarray to PIL Image.

200
    See :class:`~torchvision.transforms.ToPILImage` for more details.
201
202
203
204
205

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

206
    .. _PIL.Image mode: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#concept-modes
207
208
209
210

    Returns:
        PIL Image: Image converted to PIL Image.
    """
Varun Agrawal's avatar
Varun Agrawal committed
211
    if not(isinstance(pic, torch.Tensor) or isinstance(pic, np.ndarray)):
212
213
        raise TypeError('pic should be Tensor or ndarray. Got {}.'.format(type(pic)))

Varun Agrawal's avatar
Varun Agrawal committed
214
215
216
217
218
219
    elif isinstance(pic, torch.Tensor):
        if pic.ndimension() not in {2, 3}:
            raise ValueError('pic should be 2/3 dimensional. Got {} dimensions.'.format(pic.ndimension()))

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

222
223
224
225
        # check number of channels
        if pic.shape[-3] > 4:
            raise ValueError('pic should not have > 4 channels. Got {} channels.'.format(pic.shape[-3]))

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

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

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

238
    npimg = pic
Varun Agrawal's avatar
Varun Agrawal committed
239
    if isinstance(pic, torch.Tensor):
240
241
242
        if pic.is_floating_point() and mode != 'F':
            pic = pic.mul(255).byte()
        npimg = np.transpose(pic.cpu().numpy(), (1, 2, 0))
243
244
245
246
247
248
249
250
251
252

    if not isinstance(npimg, np.ndarray):
        raise TypeError('Input pic must be a torch.Tensor or NumPy ndarray, ' +
                        'not {}'.format(type(npimg)))

    if npimg.shape[2] == 1:
        expected_mode = None
        npimg = npimg[:, :, 0]
        if npimg.dtype == np.uint8:
            expected_mode = 'L'
vfdev's avatar
vfdev committed
253
        elif npimg.dtype == np.int16:
254
            expected_mode = 'I;16'
vfdev's avatar
vfdev committed
255
        elif npimg.dtype == np.int32:
256
257
258
259
260
261
262
263
            expected_mode = 'I'
        elif npimg.dtype == np.float32:
            expected_mode = 'F'
        if mode is not None and mode != expected_mode:
            raise ValueError("Incorrect mode ({}) supplied for input type {}. Should be {}"
                             .format(mode, np.dtype, expected_mode))
        mode = expected_mode

surgan12's avatar
surgan12 committed
264
265
266
267
268
269
270
271
    elif npimg.shape[2] == 2:
        permitted_2_channel_modes = ['LA']
        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:
            mode = 'LA'

272
    elif npimg.shape[2] == 4:
surgan12's avatar
surgan12 committed
273
        permitted_4_channel_modes = ['RGBA', 'CMYK', 'RGBX']
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
        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:
            mode = 'RGBA'
    else:
        permitted_3_channel_modes = ['RGB', 'YCbCr', 'HSV']
        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:
            mode = 'RGB'

    if mode is None:
        raise TypeError('Input type {} is not supported'.format(npimg.dtype))

    return Image.fromarray(npimg, mode=mode)


292
def normalize(tensor: Tensor, mean: List[float], std: List[float], inplace: bool = False) -> Tensor:
293
294
    """Normalize a tensor image with mean and standard deviation.

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

298
    See :class:`~torchvision.transforms.Normalize` for more details.
299
300

    Args:
301
        tensor (Tensor): Tensor image of size (C, H, W) or (B, C, H, W) to be normalized.
302
        mean (sequence): Sequence of means for each channel.
303
        std (sequence): Sequence of standard deviations for each channel.
304
        inplace(bool,optional): Bool to make this operation inplace.
305
306
307
308

    Returns:
        Tensor: Normalized Tensor image.
    """
309
310
    if not isinstance(tensor, torch.Tensor):
        raise TypeError('Input tensor should be a torch tensor. Got {}.'.format(type(tensor)))
311

312
313
    if tensor.ndim < 3:
        raise ValueError('Expected tensor to be a tensor image of size (..., C, H, W). Got tensor.size() = '
314
                         '{}.'.format(tensor.size()))
315

surgan12's avatar
surgan12 committed
316
317
318
    if not inplace:
        tensor = tensor.clone()

319
320
321
    dtype = tensor.dtype
    mean = torch.as_tensor(mean, dtype=dtype, device=tensor.device)
    std = torch.as_tensor(std, dtype=dtype, device=tensor.device)
322
323
    if (std == 0).any():
        raise ValueError('std evaluated to zero after conversion to {}, leading to division by zero.'.format(dtype))
324
    if mean.ndim == 1:
325
        mean = mean.view(-1, 1, 1)
326
    if std.ndim == 1:
327
        std = std.view(-1, 1, 1)
328
    tensor.sub_(mean).div_(std)
329
    return tensor
330
331


332
def resize(img: Tensor, size: List[int], interpolation: InterpolationMode = InterpolationMode.BILINEAR) -> Tensor:
vfdev's avatar
vfdev committed
333
334
335
    r"""Resize the input image to the given size.
    The image can be a PIL Image or a torch Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
336
337

    Args:
vfdev's avatar
vfdev committed
338
        img (PIL Image or Tensor): Image to be resized.
339
340
        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
341
            the smaller edge of the image will be matched to this number maintaining
342
            the aspect ratio. i.e, if height > width, then image will be rescaled to
vfdev's avatar
vfdev committed
343
            :math:`\left(\text{size} \times \frac{\text{height}}{\text{width}}, \text{size}\right)`.
344
            In torchscript mode size as single int is not supported, use a tuple or
vfdev's avatar
vfdev committed
345
            list of length 1: ``[size, ]``.
346
347
348
349
        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.
350
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
351
352

    Returns:
vfdev's avatar
vfdev committed
353
        PIL Image or Tensor: Resized image.
354
    """
355
356
357
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
358
359
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
360
361
362
        )
        interpolation = _interpolation_modes_from_int(interpolation)

363
364
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
365

vfdev's avatar
vfdev committed
366
    if not isinstance(img, torch.Tensor):
367
368
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.resize(img, size=size, interpolation=pil_interpolation)
vfdev's avatar
vfdev committed
369

370
    return F_t.resize(img, size=size, interpolation=interpolation.value)
371
372
373
374
375
376
377
378


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


379
380
381
382
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.
    The image can be a PIL Image or a torch Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
383
384

    Args:
385
386
        img (PIL Image or Tensor): Image to be padded.
        padding (int or tuple or list): Padding on each border. If a single int is provided this
387
388
            is used to pad all borders. If tuple of length 2 is provided this is the padding
            on left/right and top/bottom respectively. If a tuple of length 4 is provided
389
390
391
392
            this is the padding for the left, top, right and bottom borders respectively.
            In torchscript mode padding as single int is not supported, use a tuple or
            list of length 1: ``[padding, ]``.
        fill (int or str or tuple): Pixel fill value for constant fill. Default is 0. If a tuple of
393
            length 3, it is used to fill R, G, B channels respectively.
394
            This value is only used when the padding_mode is constant. Only int value is supported for Tensors.
395
        padding_mode: Type of padding. Should be: constant, edge, reflect or symmetric. Default is constant.
vfdev's avatar
vfdev committed
396
            Mode symmetric is not yet supported for Tensor inputs.
397
398
399
400
401
402
403
404
405
406
407
408
409
410

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

            - edge: pads with the last value on the edge of the image

            - reflect: pads with reflection of image (without repeating the last value on the edge)

                       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]

            - symmetric: pads with reflection of image (repeating the last value on the edge)

                         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]
411
412

    Returns:
413
        PIL Image or Tensor: Padded image.
414
    """
415
416
    if not isinstance(img, torch.Tensor):
        return F_pil.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
417

418
    return F_t.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
419
420


vfdev's avatar
vfdev committed
421
422
423
424
425
def crop(img: Tensor, top: int, left: int, height: int, width: int) -> Tensor:
    """Crop the given image at specified location and output size.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading
    dimensions
426

427
    Args:
vfdev's avatar
vfdev committed
428
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
429
430
431
432
        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.
433

434
    Returns:
vfdev's avatar
vfdev committed
435
        PIL Image or Tensor: Cropped image.
436
437
    """

vfdev's avatar
vfdev committed
438
439
    if not isinstance(img, torch.Tensor):
        return F_pil.crop(img, top, left, height, width)
440

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

vfdev's avatar
vfdev committed
443
444
445
446
447

def center_crop(img: Tensor, output_size: List[int]) -> Tensor:
    """Crops the given image at the center.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
448

449
    Args:
vfdev's avatar
vfdev committed
450
451
452
453
        img (PIL Image or Tensor): Image to be cropped.
        output_size (sequence or int): (height, width) of the crop box. If int or sequence with single int
            it is used for both directions.

454
    Returns:
vfdev's avatar
vfdev committed
455
        PIL Image or Tensor: Cropped image.
456
    """
457
458
    if isinstance(output_size, numbers.Number):
        output_size = (int(output_size), int(output_size))
vfdev's avatar
vfdev committed
459
460
461
462
    elif isinstance(output_size, (tuple, list)) and len(output_size) == 1:
        output_size = (output_size[0], output_size[0])

    image_width, image_height = _get_image_size(img)
463
    crop_height, crop_width = output_size
vfdev's avatar
vfdev committed
464

465
466
    crop_top = int(round((image_height - crop_height) / 2.))
    crop_left = int(round((image_width - crop_width) / 2.))
467
    return crop(img, crop_top, crop_left, crop_height, crop_width)
468
469


470
def resized_crop(
471
        img: Tensor, top: int, left: int, height: int, width: int, size: List[int],
472
        interpolation: InterpolationMode = InterpolationMode.BILINEAR
473
474
475
476
) -> Tensor:
    """Crop the given image and resize it to desired size.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
477

478
    Notably used in :class:`~torchvision.transforms.RandomResizedCrop`.
479
480

    Args:
481
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
482
483
484
485
        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.
486
        size (sequence or int): Desired output size. Same semantics as ``resize``.
487
488
489
490
        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.
491
492
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.

493
    Returns:
494
        PIL Image or Tensor: Cropped image.
495
    """
496
    img = crop(img, top, left, height, width)
497
498
499
500
    img = resize(img, size, interpolation)
    return img


501
def hflip(img: Tensor) -> Tensor:
vfdev's avatar
vfdev committed
502
    """Horizontally flip the given PIL Image or Tensor.
503
504

    Args:
vfdev's avatar
vfdev committed
505
        img (PIL Image or Tensor): Image to be flipped. If img
506
507
508
            is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.
509
510

    Returns:
vfdev's avatar
vfdev committed
511
        PIL Image or Tensor:  Horizontally flipped image.
512
    """
513
514
    if not isinstance(img, torch.Tensor):
        return F_pil.hflip(img)
515

516
    return F_t.hflip(img)
517
518


519
520
521
def _get_perspective_coeffs(
        startpoints: List[List[int]], endpoints: List[List[int]]
) -> List[float]:
522
523
    """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
524
    In Perspective Transform each pixel (x, y) in the original image gets transformed as,
525
526
527
     (x, y) -> ( (ax + by + c) / (gx + hy + 1), (dx + ey + f) / (gx + hy + 1) )

    Args:
528
529
530
531
532
        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.

533
534
535
    Returns:
        octuple (a, b, c, d, e, f, g, h) for transforming each pixel.
    """
536
537
538
539
540
    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]])
541

542
543
    b_matrix = torch.tensor(startpoints, dtype=torch.float).view(8)
    res = torch.lstsq(b_matrix, a_matrix)[0]
544

545
546
    output: List[float] = res.squeeze(1).tolist()
    return output
547
548


549
550
551
552
def perspective(
        img: Tensor,
        startpoints: List[List[int]],
        endpoints: List[List[int]],
553
        interpolation: InterpolationMode = InterpolationMode.BILINEAR,
554
        fill: Optional[List[float]] = None
555
556
557
558
) -> Tensor:
    """Perform perspective transform of the given image.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
559
560

    Args:
561
562
563
564
565
        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.
566
567
568
        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.
569
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
570
        fill (sequence or int or float, optional): Pixel fill value for the area outside the transformed
571
            image. If int or float, the value is used for all bands respectively.
572
573
574
575
            This option is supported for PIL image and Tensor inputs.
            In torchscript mode single int/float value is not supported, please use a tuple
            or list of length 1: ``[value, ]``.
            If input is PIL Image, the options is only available for ``Pillow>=5.0.0``.
576

577
    Returns:
578
        PIL Image or Tensor: transformed Image.
579
    """
580

581
    coeffs = _get_perspective_coeffs(startpoints, endpoints)
582

583
584
585
    # Backward compatibility with integer value
    if isinstance(interpolation, int):
        warnings.warn(
586
587
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
588
589
590
        )
        interpolation = _interpolation_modes_from_int(interpolation)

591
592
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
593

594
    if not isinstance(img, torch.Tensor):
595
596
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.perspective(img, coeffs, interpolation=pil_interpolation, fill=fill)
597

598
    return F_t.perspective(img, coeffs, interpolation=interpolation.value, fill=fill)
599
600


601
602
def vflip(img: Tensor) -> Tensor:
    """Vertically flip the given PIL Image or torch Tensor.
603
604

    Args:
vfdev's avatar
vfdev committed
605
        img (PIL Image or Tensor): Image to be flipped. If img
606
607
608
            is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.
609
610
611
612

    Returns:
        PIL Image:  Vertically flipped image.
    """
613
614
    if not isinstance(img, torch.Tensor):
        return F_pil.vflip(img)
615

616
    return F_t.vflip(img)
617
618


vfdev's avatar
vfdev committed
619
620
621
622
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.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
623
624
625
626
627
628

    .. 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
629
630
631
632
        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
            made. If provided a tuple or list of length 1, it will be interpreted as (size[0], size[0]).
633

634
    Returns:
635
636
       tuple: tuple (tl, tr, bl, br, center)
                Corresponding top left, top right, bottom left, bottom right and center crop.
637
638
639
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
640
641
    elif isinstance(size, (tuple, list)) and len(size) == 1:
        size = (size[0], size[0])
642

vfdev's avatar
vfdev committed
643
644
645
646
    if len(size) != 2:
        raise ValueError("Please provide only two dimensions (h, w) for size.")

    image_width, image_height = _get_image_size(img)
647
648
649
650
651
    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
652
653
654
655
656
657
658
659
    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
660
661


vfdev's avatar
vfdev committed
662
663
664
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
665
    flipped version of these (horizontal flipping is used by default).
vfdev's avatar
vfdev committed
666
667
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions
668
669
670
671
672

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

673
    Args:
vfdev's avatar
vfdev committed
674
        img (PIL Image or Tensor): Image to be cropped.
675
        size (sequence or int): Desired output size of the crop. If size is an
676
            int instead of sequence like (h, w), a square crop (size, size) is
vfdev's avatar
vfdev committed
677
            made. If provided a tuple or list of length 1, it will be interpreted as (size[0], size[0]).
678
        vertical_flip (bool): Use vertical flipping instead of horizontal
679
680

    Returns:
681
682
683
        tuple: tuple (tl, tr, bl, br, center, tl_flip, tr_flip, bl_flip, br_flip, center_flip)
            Corresponding top left, top right, bottom left, bottom right and
            center crop and same for the flipped image.
684
685
686
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
687
688
689
690
691
    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.")
692
693
694
695
696
697
698
699
700
701
702
703

    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


704
def adjust_brightness(img: Tensor, brightness_factor: float) -> Tensor:
705
706
707
    """Adjust brightness of an Image.

    Args:
vfdev's avatar
vfdev committed
708
        img (PIL Image or Tensor): Image to be adjusted.
709
710
711
712
713
        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
714
        PIL Image or Tensor: Brightness adjusted image.
715
    """
716
717
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_brightness(img, brightness_factor)
718

719
    return F_t.adjust_brightness(img, brightness_factor)
720
721


722
def adjust_contrast(img: Tensor, contrast_factor: float) -> Tensor:
723
724
725
    """Adjust contrast of an Image.

    Args:
vfdev's avatar
vfdev committed
726
        img (PIL Image or Tensor): Image to be adjusted.
727
728
729
730
731
        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
732
        PIL Image or Tensor: Contrast adjusted image.
733
    """
734
735
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_contrast(img, contrast_factor)
736

737
    return F_t.adjust_contrast(img, contrast_factor)
738
739


740
def adjust_saturation(img: Tensor, saturation_factor: float) -> Tensor:
741
742
743
    """Adjust color saturation of an image.

    Args:
vfdev's avatar
vfdev committed
744
        img (PIL Image or Tensor): Image to be adjusted.
745
746
747
748
749
        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
750
        PIL Image or Tensor: Saturation adjusted image.
751
    """
752
753
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_saturation(img, saturation_factor)
754

755
    return F_t.adjust_saturation(img, saturation_factor)
756
757


758
def adjust_hue(img: Tensor, hue_factor: float) -> Tensor:
759
760
761
762
763
764
765
766
767
    """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]`.

768
769
770
    See `Hue`_ for more details.

    .. _Hue: https://en.wikipedia.org/wiki/Hue
771
772

    Args:
773
        img (PIL Image or Tensor): Image to be adjusted.
774
775
776
777
778
779
780
        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:
781
        PIL Image or Tensor: Hue adjusted image.
782
    """
783
784
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_hue(img, hue_factor)
785

786
    return F_t.adjust_hue(img, hue_factor)
787
788


789
def adjust_gamma(img: Tensor, gamma: float, gain: float = 1) -> Tensor:
790
    r"""Perform gamma correction on an image.
791
792
793
794

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

795
796
797
798
    .. math::
        I_{\text{out}} = 255 \times \text{gain} \times \left(\frac{I_{\text{in}}}{255}\right)^{\gamma}

    See `Gamma Correction`_ for more details.
799

800
    .. _Gamma Correction: https://en.wikipedia.org/wiki/Gamma_correction
801
802

    Args:
803
        img (PIL Image or Tensor): PIL Image to be adjusted.
804
805
806
        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.
807
        gain (float): The constant multiplier.
808
809
    Returns:
        PIL Image or Tensor: Gamma correction adjusted image.
810
    """
811
812
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_gamma(img, gamma, gain)
813

814
    return F_t.adjust_gamma(img, gamma, gain)
815
816


vfdev's avatar
vfdev committed
817
def _get_inverse_affine_matrix(
vfdev's avatar
vfdev committed
818
        center: List[float], angle: float, translate: List[float], scale: float, shear: List[float]
vfdev's avatar
vfdev committed
819
) -> List[float]:
820
821
822
823
824
825
826
    # 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
827
828
829
830
831
832
833
834
835
836
    #       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]
    #
837
838
    # Thus, the inverse is M^-1 = C * RSS^-1 * C^-1 * T^-1

839
840
841
842
843
844
845
    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
846
847
848
849
    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)
850
851

    # Inverted rotation matrix with scale and shear
852
    # det([[a, b], [c, d]]) == 1, since det(rotation) = 1 and det(shear) = 1
vfdev's avatar
vfdev committed
853
854
    matrix = [d, -b, 0.0, -c, a, 0.0]
    matrix = [x / scale for x in matrix]
855
856

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

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

vfdev's avatar
vfdev committed
864
    return matrix
865

vfdev's avatar
vfdev committed
866

vfdev's avatar
vfdev committed
867
def rotate(
868
        img: Tensor, angle: float, interpolation: InterpolationMode = InterpolationMode.NEAREST,
869
        expand: bool = False, center: Optional[List[int]] = None,
870
        fill: Optional[List[float]] = None, resample: Optional[int] = None
vfdev's avatar
vfdev committed
871
872
873
874
875
876
877
878
) -> Tensor:
    """Rotate the image by angle.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.

    Args:
        img (PIL Image or Tensor): image to be rotated.
        angle (float or int): rotation angle value in degrees, counter-clockwise.
879
880
881
        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.
882
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
vfdev's avatar
vfdev committed
883
884
885
886
887
888
        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.
        center (list or tuple, optional): Optional center of rotation. Origin is the upper left corner.
            Default is the center of the image.
889
        fill (sequence or int or float, optional): Pixel fill value for the area outside the transformed
vfdev's avatar
vfdev committed
890
            image. If int or float, the value is used for all bands respectively.
891
892
893
894
            This option is supported for PIL image and Tensor inputs.
            In torchscript mode single int/float value is not supported, please use a tuple
            or list of length 1: ``[value, ]``.
            If input is PIL Image, the options is only available for ``Pillow>=5.2.0``.
vfdev's avatar
vfdev committed
895
896
897
898
899
900
901

    Returns:
        PIL Image or Tensor: Rotated image.

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

    """
902
903
904
905
906
907
908
909
910
    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(
911
912
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
913
914
915
        )
        interpolation = _interpolation_modes_from_int(interpolation)

vfdev's avatar
vfdev committed
916
917
918
919
920
921
    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")

922
923
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
924

vfdev's avatar
vfdev committed
925
    if not isinstance(img, torch.Tensor):
926
927
        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
928
929
930
931

    center_f = [0.0, 0.0]
    if center is not None:
        img_size = _get_image_size(img)
932
933
934
        # 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
935
936
937
    # 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])
938
    return F_t.rotate(img, matrix=matrix, interpolation=interpolation.value, expand=expand, fill=fill)
vfdev's avatar
vfdev committed
939
940


vfdev's avatar
vfdev committed
941
942
def affine(
        img: Tensor, angle: float, translate: List[int], scale: float, shear: List[float],
943
944
        interpolation: InterpolationMode = InterpolationMode.NEAREST, fill: Optional[List[float]] = None,
        resample: Optional[int] = None, fillcolor: Optional[List[float]] = None
vfdev's avatar
vfdev committed
945
946
947
948
) -> Tensor:
    """Apply affine transformation on the image keeping image center invariant.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions.
949
950

    Args:
vfdev's avatar
vfdev committed
951
        img (PIL Image or Tensor): image to transform.
952
        angle (float or int): rotation angle in degrees between -180 and 180, clockwise direction.
953
954
        translate (list or tuple of integers): horizontal and vertical translations (post-rotation translation)
        scale (float): overall scale
ptrblck's avatar
ptrblck committed
955
        shear (float or tuple or list): shear angle value in degrees between -180 to 180, clockwise direction.
vfdev's avatar
vfdev committed
956
957
            If a tuple of list is specified, the first value corresponds to a shear parallel to the x axis, while
            the second value corresponds to a shear parallel to the y axis.
958
959
960
        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.
961
            For backward compatibility integer values (e.g. ``PIL.Image.NEAREST``) are still acceptable.
962
963
964
965
966
967
968
        fill (sequence or int or float, optional): Pixel fill value for the area outside the transformed
            image. If int or float, the value is used for all bands respectively.
            This option is supported for PIL image and Tensor inputs.
            In torchscript mode single int/float value is not supported, please use a tuple
            or list of length 1: ``[value, ]``.
            If input is PIL Image, the options is only available for ``Pillow>=5.0.0``.
        fillcolor (sequence, int, float): deprecated argument and will be removed since v0.10.0.
969
970
971
            Please use `arg`:fill: instead.
        resample (int, optional): deprecated argument and will be removed since v0.10.0.
            Please use `arg`:interpolation: instead.
vfdev's avatar
vfdev committed
972
973
974

    Returns:
        PIL Image or Tensor: Transformed image.
975
    """
976
977
978
979
980
981
982
983
984
    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(
985
986
            "Argument interpolation should be of type InterpolationMode instead of int. "
            "Please, use InterpolationMode enum."
987
988
989
990
991
992
993
994
995
        )
        interpolation = _interpolation_modes_from_int(interpolation)

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

vfdev's avatar
vfdev committed
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
    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")

1011
1012
    if not isinstance(interpolation, InterpolationMode):
        raise TypeError("Argument interpolation should be a InterpolationMode")
1013

vfdev's avatar
vfdev committed
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
    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))

    img_size = _get_image_size(img)
    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)
1039
1040
        pil_interpolation = pil_modes_mapping[interpolation]
        return F_pil.affine(img, matrix=matrix, interpolation=pil_interpolation, fill=fill)
1041

1042
1043
    translate_f = [1.0 * t for t in translate]
    matrix = _get_inverse_affine_matrix([0.0, 0.0], angle, translate_f, scale, shear)
1044
    return F_t.affine(img, matrix=matrix, interpolation=interpolation.value, fill=fill)
1045
1046


1047
@torch.jit.unused
1048
def to_grayscale(img, num_output_channels=1):
1049
    """Convert PIL image of any mode (RGB, HSV, LAB, etc) to grayscale version of image.
1050
1051

    Args:
1052
1053
        img (PIL Image): PIL 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.
1054
1055

    Returns:
1056
1057
1058
1059
        PIL Image: Grayscale version of the image.
            if num_output_channels = 1 : returned image is single channel

            if num_output_channels = 3 : returned image is 3 channel with r = g = b
1060
    """
1061
1062
    if isinstance(img, Image.Image):
        return F_pil.to_grayscale(img, num_output_channels)
1063

1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
    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.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions

    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.
            if num_output_channels = 1 : returned image is single channel

            if num_output_channels = 3 : returned image is 3 channel with r = g = b
    """
    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)
1090
1091


1092
def erase(img: Tensor, i: int, j: int, h: int, w: int, v: Tensor, inplace: bool = False) -> Tensor:
1093
1094
1095
1096
1097
1098
1099
1100
1101
    """ Erase the input Tensor Image with given value.

    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
1102
        inplace(bool, optional): For in-place operations. By default is set False.
1103
1104
1105
1106
1107
1108
1109

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

1110
1111
1112
    if not inplace:
        img = img.clone()

vfdev's avatar
vfdev committed
1113
    img[..., i:i + h, j:j + w] = v
1114
    return img
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174


def gaussian_blur(img: Tensor, kernel_size: List[int], sigma: Optional[List[float]] = None) -> Tensor:
    """Performs Gaussian blurring on the img by given kernel.
    The image can be a PIL Image or a Tensor, in which case it is expected
    to have [..., H, W] shape, where ... means an arbitrary number of leading dimensions

    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.
            In torchscript mode kernel_size as single int is not supported, use a tuple or
            list of length 1: ``[ksize, ]``.
        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``.
            Default, None. In torchscript mode sigma as single float is
            not supported, use a tuple or list of length 1: ``[sigma, ]``.

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

    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)):
        raise TypeError('sigma should be either float or sequence of floats. Got {}'.format(type(sigma)))
    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:
        raise ValueError('If sigma is a sequence, its length should be 2. Got {}'.format(len(sigma)))
    for s in sigma:
        if s <= 0.:
            raise ValueError('sigma should have positive values. Got {}'.format(sigma))

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

        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
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289


def invert(img: Tensor) -> Tensor:
    """Invert the colors of an RGB/grayscale PIL Image or torch Tensor.

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
            If img is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.

    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:
    """Posterize a PIL Image or torch Tensor by reducing the number of bits for each color channel.

    Args:
        img (PIL Image or Tensor): Image to have its colors posterized.
            If img is a Tensor, it should be of type torch.uint8 and
            it is expected to be in [..., H, W] format, where ... means
            it can have an arbitrary number of trailing dimensions.
        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):
        raise ValueError('The number if bits should be between 0 and 8. Got {}'.format(bits))

    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:
    """Solarize a PIL Image or torch Tensor by inverting all pixel values above a threshold.

    Args:
        img (PIL Image or Tensor): Image to have its colors inverted.
            If img is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.
        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:
    """Adjust the sharpness of an Image.

    Args:
        img (PIL Image or Tensor): Image to be adjusted.
        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:
    """Maximize contrast of a PIL Image or torch Tensor by remapping its
    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.
            If img is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.

    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:
    """Equalize the histogram of a PIL Image or torch Tensor by applying
    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.
            If img is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.

    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)