functional.py 37.3 KB
Newer Older
1
import math
2
3
import numbers
import warnings
vfdev's avatar
vfdev committed
4
from typing import Any, Optional
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
vfdev's avatar
vfdev committed
11
from torch.jit.annotations import List, Tuple
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

vfdev's avatar
vfdev committed
22
_is_pil_image = F_pil._is_pil_image
vfdev's avatar
vfdev committed
23
_parse_fill = F_pil._parse_fill
vfdev's avatar
vfdev committed
24
25
26
27
28
29
30


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

vfdev's avatar
vfdev committed
32
    return F_pil._get_image_size(img)
33

vfdev's avatar
vfdev committed
34
35
36

@torch.jit.unused
def _is_numpy(img: Any) -> bool:
37
38
39
    return isinstance(img, np.ndarray)


vfdev's avatar
vfdev committed
40
41
@torch.jit.unused
def _is_numpy_image(img: Any) -> bool:
42
    return img.ndim in {2, 3}
43
44
45
46
47
48
49
50
51
52
53
54
55


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
56
    if not(F_pil._is_pil_image(pic) or _is_numpy(pic)):
57
58
        raise TypeError('pic should be PIL Image or ndarray. Got {}'.format(type(pic)))

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

62
63
    if isinstance(pic, np.ndarray):
        # handle numpy array
surgan12's avatar
surgan12 committed
64
65
66
        if pic.ndim == 2:
            pic = pic[:, :, None]

67
68
        img = torch.from_numpy(pic.transpose((2, 0, 1)))
        # backward compatibility
69
70
71
72
        if isinstance(img, torch.ByteTensor):
            return img.float().div(255)
        else:
            return img
73
74
75
76
77
78
79
80
81
82
83

    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))
84
85
    elif pic.mode == 'F':
        img = torch.from_numpy(np.array(pic, np.float32, copy=False))
86
87
    elif pic.mode == '1':
        img = 255 * torch.from_numpy(np.array(pic, np.uint8, copy=False))
88
89
    else:
        img = torch.ByteTensor(torch.ByteStorage.from_buffer(pic.tobytes()))
90
91

    img = img.view(pic.size[1], pic.size[0], len(pic.getbands()))
92
    # put it from HWC to CHW format
93
    img = img.permute((2, 0, 1)).contiguous()
94
95
96
97
98
99
    if isinstance(img, torch.ByteTensor):
        return img.float().div(255)
    else:
        return img


100
101
102
103
104
105
106
107
108
109
110
def pil_to_tensor(pic):
    """Convert a ``PIL Image`` to a tensor of the same type.

    See ``AsTensor`` for more details.

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

    Returns:
        Tensor: Converted image.
    """
vfdev's avatar
vfdev committed
111
    if not(F_pil._is_pil_image(pic)):
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
        raise TypeError('pic should be PIL Image. Got {}'.format(type(pic)))

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


127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
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:
        (torch.Tensor): Converted image

    .. 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``.
    """
    if image.dtype == dtype:
        return image

    if image.dtype.is_floating_point:
        # float to float
        if dtype.is_floating_point:
            return image.to(dtype)

        # float to int
        if (image.dtype == torch.float32 and dtype in (torch.int32, torch.int64)) or (
            image.dtype == torch.float64 and dtype == torch.int64
        ):
            msg = f"The cast from {image.dtype} to {dtype} cannot be performed safely."
            raise RuntimeError(msg)

        eps = 1e-3
        return image.mul(torch.iinfo(dtype).max + 1 - eps).to(dtype)
    else:
        # int to float
        if dtype.is_floating_point:
            max = torch.iinfo(image.dtype).max
            image = image.to(dtype)
            return image / max

        # int to int
        input_max = torch.iinfo(image.dtype).max
        output_max = torch.iinfo(dtype).max

        if input_max > output_max:
            factor = (input_max + 1) // (output_max + 1)
            image = image // factor
            return image.to(dtype)
        else:
            factor = (output_max + 1) // (input_max + 1)
            image = image.to(dtype)
            return image * factor


186
187
188
def to_pil_image(pic, mode=None):
    """Convert a tensor or an ndarray to PIL Image.

189
    See :class:`~torchvision.transforms.ToPILImage` for more details.
190
191
192
193
194

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

195
    .. _PIL.Image mode: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#concept-modes
196
197
198
199

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

Varun Agrawal's avatar
Varun Agrawal committed
203
204
205
206
207
208
    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
209
            pic = pic.unsqueeze(0)
Varun Agrawal's avatar
Varun Agrawal committed
210
211
212
213
214
215
216
217
218

    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)

219
    npimg = pic
220
    if isinstance(pic, torch.FloatTensor) and mode != 'F':
221
        pic = pic.mul(255).byte()
Varun Agrawal's avatar
Varun Agrawal committed
222
    if isinstance(pic, torch.Tensor):
223
224
225
226
227
228
229
230
231
232
233
        npimg = np.transpose(pic.numpy(), (1, 2, 0))

    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
234
        elif npimg.dtype == np.int16:
235
            expected_mode = 'I;16'
vfdev's avatar
vfdev committed
236
        elif npimg.dtype == np.int32:
237
238
239
240
241
242
243
244
            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
245
246
247
248
249
250
251
252
    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'

253
    elif npimg.shape[2] == 4:
surgan12's avatar
surgan12 committed
254
        permitted_4_channel_modes = ['RGBA', 'CMYK', 'RGBX']
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
        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)


surgan12's avatar
surgan12 committed
273
def normalize(tensor, mean, std, inplace=False):
274
275
    """Normalize a tensor image with mean and standard deviation.

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

279
    See :class:`~torchvision.transforms.Normalize` for more details.
280
281
282
283

    Args:
        tensor (Tensor): Tensor image of size (C, H, W) to be normalized.
        mean (sequence): Sequence of means for each channel.
284
        std (sequence): Sequence of standard deviations for each channel.
285
        inplace(bool,optional): Bool to make this operation inplace.
286
287
288
289

    Returns:
        Tensor: Normalized Tensor image.
    """
290
291
    if not torch.is_tensor(tensor):
        raise TypeError('tensor should be a torch tensor. Got {}.'.format(type(tensor)))
292

293
294
295
    if tensor.ndimension() != 3:
        raise ValueError('Expected tensor to be a tensor image of size (C, H, W). Got tensor.size() = '
                         '{}.'.format(tensor.size()))
296

surgan12's avatar
surgan12 committed
297
298
299
    if not inplace:
        tensor = tensor.clone()

300
301
302
    dtype = tensor.dtype
    mean = torch.as_tensor(mean, dtype=dtype, device=tensor.device)
    std = torch.as_tensor(std, dtype=dtype, device=tensor.device)
303
304
    if (std == 0).any():
        raise ValueError('std evaluated to zero after conversion to {}, leading to division by zero.'.format(dtype))
305
306
307
308
309
    if mean.ndim == 1:
        mean = mean[:, None, None]
    if std.ndim == 1:
        std = std[:, None, None]
    tensor.sub_(mean).div_(std)
310
    return tensor
311
312


vfdev's avatar
vfdev committed
313
def resize(img: Tensor, size: List[int], interpolation: int = Image.BILINEAR) -> Tensor:
vfdev's avatar
vfdev committed
314
315
316
    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
317
318

    Args:
vfdev's avatar
vfdev committed
319
        img (PIL Image or Tensor): Image to be resized.
320
321
        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
322
            the smaller edge of the image will be matched to this number maintaining
323
            the aspect ratio. i.e, if height > width, then image will be rescaled to
vfdev's avatar
vfdev committed
324
325
326
            :math:`\left(\text{size} \times \frac{\text{height}}{\text{width}}, \text{size}\right)`.
            In torchscript mode padding as single int is not supported, use a tuple or
            list of length 1: ``[size, ]``.
vfdev's avatar
vfdev committed
327
328
329
        interpolation (int, optional): Desired interpolation enum defined by `filters`_.
            Default is ``PIL.Image.BILINEAR``. If input is Tensor, only ``PIL.Image.NEAREST``, ``PIL.Image.BILINEAR``
            and ``PIL.Image.BICUBIC`` are supported.
330
331

    Returns:
vfdev's avatar
vfdev committed
332
        PIL Image or Tensor: Resized image.
333
    """
vfdev's avatar
vfdev committed
334
335
336
337
    if not isinstance(img, torch.Tensor):
        return F_pil.resize(img, size=size, interpolation=interpolation)

    return F_t.resize(img, size=size, interpolation=interpolation)
338
339
340
341
342
343
344
345


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


346
347
348
349
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
350
351

    Args:
352
353
        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
354
355
            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
356
357
358
359
            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
360
            length 3, it is used to fill R, G, B channels respectively.
361
            This value is only used when the padding_mode is constant. Only int value is supported for Tensors.
362
        padding_mode: Type of padding. Should be: constant, edge, reflect or symmetric. Default is constant.
vfdev's avatar
vfdev committed
363
            Mode symmetric is not yet supported for Tensor inputs.
364
365
366
367
368
369
370
371
372
373
374
375
376
377

            - 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]
378
379

    Returns:
380
        PIL Image or Tensor: Padded image.
381
    """
382
383
    if not isinstance(img, torch.Tensor):
        return F_pil.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
384

385
    return F_t.pad(img, padding=padding, fill=fill, padding_mode=padding_mode)
386
387


vfdev's avatar
vfdev committed
388
389
390
391
392
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
393

394
    Args:
vfdev's avatar
vfdev committed
395
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
396
397
398
399
        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.
400

401
    Returns:
vfdev's avatar
vfdev committed
402
        PIL Image or Tensor: Cropped image.
403
404
    """

vfdev's avatar
vfdev committed
405
406
    if not isinstance(img, torch.Tensor):
        return F_pil.crop(img, top, left, height, width)
407

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

vfdev's avatar
vfdev committed
410
411
412
413
414

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
415

416
    Args:
vfdev's avatar
vfdev committed
417
418
419
420
        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.

421
    Returns:
vfdev's avatar
vfdev committed
422
        PIL Image or Tensor: Cropped image.
423
    """
424
425
    if isinstance(output_size, numbers.Number):
        output_size = (int(output_size), int(output_size))
vfdev's avatar
vfdev committed
426
427
428
429
    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)
430
    crop_height, crop_width = output_size
vfdev's avatar
vfdev committed
431
432
433
434
435
436
437
438
439

    # crop_top = int(round((image_height - crop_height) / 2.))
    # Result can be different between python func and scripted func
    # Temporary workaround:
    crop_top = int((image_height - crop_height + 1) * 0.5)
    # crop_left = int(round((image_width - crop_width) / 2.))
    # Result can be different between python func and scripted func
    # Temporary workaround:
    crop_left = int((image_width - crop_width + 1) * 0.5)
440
    return crop(img, crop_top, crop_left, crop_height, crop_width)
441
442


443
444
445
446
447
448
def resized_crop(
        img: Tensor, top: int, left: int, height: int, width: int, size: List[int], interpolation: int = Image.BILINEAR
) -> 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
449

450
    Notably used in :class:`~torchvision.transforms.RandomResizedCrop`.
451
452

    Args:
453
        img (PIL Image or Tensor): Image to be cropped. (0,0) denotes the top left corner of the image.
454
455
456
457
        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.
458
        size (sequence or int): Desired output size. Same semantics as ``resize``.
vfdev's avatar
vfdev committed
459
460
461
        interpolation (int, optional): Desired interpolation enum defined by `filters`_.
            Default is ``PIL.Image.BILINEAR``. If input is Tensor, only ``PIL.Image.NEAREST``, ``PIL.Image.BILINEAR``
            and ``PIL.Image.BICUBIC`` are supported.
462
    Returns:
463
        PIL Image or Tensor: Cropped image.
464
    """
465
    img = crop(img, top, left, height, width)
466
467
468
469
    img = resize(img, size, interpolation)
    return img


470
def hflip(img: Tensor) -> Tensor:
vfdev's avatar
vfdev committed
471
    """Horizontally flip the given PIL Image or Tensor.
472
473

    Args:
vfdev's avatar
vfdev committed
474
        img (PIL Image or Tensor): Image to be flipped. If img
475
476
477
            is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.
478
479

    Returns:
vfdev's avatar
vfdev committed
480
        PIL Image or Tensor:  Horizontally flipped image.
481
    """
482
483
    if not isinstance(img, torch.Tensor):
        return F_pil.hflip(img)
484

485
    return F_t.hflip(img)
486
487


488
489
490
def _get_perspective_coeffs(startpoints, endpoints):
    """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
491
    In Perspective Transform each pixel (x, y) in the original image gets transformed as,
492
493
494
     (x, y) -> ( (ax + by + c) / (gx + hy + 1), (dx + ey + f) / (gx + hy + 1) )

    Args:
Vitaliy Chiley's avatar
Vitaliy Chiley committed
495
        List containing [top-left, top-right, bottom-right, bottom-left] of the original image,
vfdev's avatar
vfdev committed
496
        List containing [top-left, top-right, bottom-right, bottom-left] of the transformed image
497
498
499
500
501
502
503
504
505
506
507
    Returns:
        octuple (a, b, c, d, e, f, g, h) for transforming each pixel.
    """
    matrix = []

    for p1, p2 in zip(endpoints, startpoints):
        matrix.append([p1[0], p1[1], 1, 0, 0, 0, -p2[0] * p1[0], -p2[0] * p1[1]])
        matrix.append([0, 0, 0, p1[0], p1[1], 1, -p2[1] * p1[0], -p2[1] * p1[1]])

    A = torch.tensor(matrix, dtype=torch.float)
    B = torch.tensor(startpoints, dtype=torch.float).view(8)
508
    res = torch.lstsq(B, A)[0]
509
510
511
    return res.squeeze_(1).tolist()


512
def perspective(img, startpoints, endpoints, interpolation=Image.BICUBIC, fill=None):
513
514
515
516
    """Perform perspective transform of the given PIL Image.

    Args:
        img (PIL Image): Image to be transformed.
Vitaliy Chiley's avatar
Vitaliy Chiley committed
517
        startpoints: List containing [top-left, top-right, bottom-right, bottom-left] of the original image
518
        endpoints: List containing [top-left, top-right, bottom-right, bottom-left] of the transformed image
519
        interpolation: Default- Image.BICUBIC
520
521
522
523
        fill (n-tuple or int or float): Pixel fill value for area outside the rotated
            image. If int or float, the value is used for all bands respectively.
            This option is only available for ``pillow>=5.0.0``.

524
525
526
    Returns:
        PIL Image:  Perspectively transformed Image.
    """
527

vfdev's avatar
vfdev committed
528
    if not F_pil._is_pil_image(img):
529
530
        raise TypeError('img should be PIL Image. Got {}'.format(type(img)))

531
532
    opts = _parse_fill(fill, img, '5.0.0')

533
    coeffs = _get_perspective_coeffs(startpoints, endpoints)
534
    return img.transform(img.size, Image.PERSPECTIVE, coeffs, interpolation, **opts)
535
536


537
538
def vflip(img: Tensor) -> Tensor:
    """Vertically flip the given PIL Image or torch Tensor.
539
540

    Args:
vfdev's avatar
vfdev committed
541
        img (PIL Image or Tensor): Image to be flipped. If img
542
543
544
            is a Tensor, it is expected to be in [..., H, W] format,
            where ... means it can have an arbitrary number of trailing
            dimensions.
545
546
547
548

    Returns:
        PIL Image:  Vertically flipped image.
    """
549
550
    if not isinstance(img, torch.Tensor):
        return F_pil.vflip(img)
551

552
    return F_t.vflip(img)
553
554


vfdev's avatar
vfdev committed
555
556
557
558
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
559
560
561
562
563
564

    .. 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
565
566
567
568
        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]).
569

570
    Returns:
571
572
       tuple: tuple (tl, tr, bl, br, center)
                Corresponding top left, top right, bottom left, bottom right and center crop.
573
574
575
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
576
577
    elif isinstance(size, (tuple, list)) and len(size) == 1:
        size = (size[0], size[0])
578

vfdev's avatar
vfdev committed
579
580
581
582
    if len(size) != 2:
        raise ValueError("Please provide only two dimensions (h, w) for size.")

    image_width, image_height = _get_image_size(img)
583
584
585
586
587
    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
588
589
590
591
592
593
594
595
    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
596
597


vfdev's avatar
vfdev committed
598
599
600
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
601
    flipped version of these (horizontal flipping is used by default).
vfdev's avatar
vfdev committed
602
603
    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
604
605
606
607
608

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

609
    Args:
vfdev's avatar
vfdev committed
610
        img (PIL Image or Tensor): Image to be cropped.
611
        size (sequence or int): Desired output size of the crop. If size is an
612
            int instead of sequence like (h, w), a square crop (size, size) is
vfdev's avatar
vfdev committed
613
            made. If provided a tuple or list of length 1, it will be interpreted as (size[0], size[0]).
614
        vertical_flip (bool): Use vertical flipping instead of horizontal
615
616

    Returns:
617
618
619
        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.
620
621
622
    """
    if isinstance(size, numbers.Number):
        size = (int(size), int(size))
vfdev's avatar
vfdev committed
623
624
625
626
627
    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.")
628
629
630
631
632
633
634
635
636
637
638
639

    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


640
def adjust_brightness(img: Tensor, brightness_factor: float) -> Tensor:
641
642
643
    """Adjust brightness of an Image.

    Args:
vfdev's avatar
vfdev committed
644
        img (PIL Image or Tensor): Image to be adjusted.
645
646
647
648
649
        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
650
        PIL Image or Tensor: Brightness adjusted image.
651
    """
652
653
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_brightness(img, brightness_factor)
654

655
    return F_t.adjust_brightness(img, brightness_factor)
656
657


658
def adjust_contrast(img: Tensor, contrast_factor: float) -> Tensor:
659
660
661
    """Adjust contrast of an Image.

    Args:
vfdev's avatar
vfdev committed
662
        img (PIL Image or Tensor): Image to be adjusted.
663
664
665
666
667
        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
668
        PIL Image or Tensor: Contrast adjusted image.
669
    """
670
671
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_contrast(img, contrast_factor)
672

673
    return F_t.adjust_contrast(img, contrast_factor)
674
675


676
def adjust_saturation(img: Tensor, saturation_factor: float) -> Tensor:
677
678
679
    """Adjust color saturation of an image.

    Args:
vfdev's avatar
vfdev committed
680
        img (PIL Image or Tensor): Image to be adjusted.
681
682
683
684
685
        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
686
        PIL Image or Tensor: Saturation adjusted image.
687
    """
688
689
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_saturation(img, saturation_factor)
690

691
    return F_t.adjust_saturation(img, saturation_factor)
692
693


694
def adjust_hue(img: Tensor, hue_factor: float) -> Tensor:
695
696
697
698
699
700
701
702
703
    """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]`.

704
705
706
    See `Hue`_ for more details.

    .. _Hue: https://en.wikipedia.org/wiki/Hue
707
708
709
710
711
712
713
714
715
716
717
718

    Args:
        img (PIL Image): PIL Image to be adjusted.
        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:
        PIL Image: Hue adjusted image.
    """
719
720
    if not isinstance(img, torch.Tensor):
        return F_pil.adjust_hue(img, hue_factor)
721

722
    raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
723
724
725


def adjust_gamma(img, gamma, gain=1):
726
    r"""Perform gamma correction on an image.
727
728
729
730

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

731
732
733
734
    .. math::
        I_{\text{out}} = 255 \times \text{gain} \times \left(\frac{I_{\text{in}}}{255}\right)^{\gamma}

    See `Gamma Correction`_ for more details.
735

736
    .. _Gamma Correction: https://en.wikipedia.org/wiki/Gamma_correction
737
738
739

    Args:
        img (PIL Image): PIL Image to be adjusted.
740
741
742
        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.
743
744
        gain (float): The constant multiplier.
    """
vfdev's avatar
vfdev committed
745
    if not F_pil._is_pil_image(img):
746
747
748
749
750
751
752
753
        raise TypeError('img should be PIL Image. Got {}'.format(type(img)))

    if gamma < 0:
        raise ValueError('Gamma should be a non-negative real number')

    input_mode = img.mode
    img = img.convert('RGB')

754
755
    gamma_map = [255 * gain * pow(ele / 255., gamma) for ele in range(256)] * 3
    img = img.point(gamma_map)  # use PIL's point-function to accelerate this part
756

757
    img = img.convert(input_mode)
758
    return img
759
760


Philip Meier's avatar
Philip Meier committed
761
def rotate(img, angle, resample=False, expand=False, center=None, fill=None):
762
    """Rotate the image by angle.
763
764
765
766


    Args:
        img (PIL Image): PIL Image to be rotated.
767
768
769
770
        angle (float or int): In degrees degrees counter clockwise order.
        resample (``PIL.Image.NEAREST`` or ``PIL.Image.BILINEAR`` or ``PIL.Image.BICUBIC``, optional):
            An optional resampling filter. See `filters`_ for more information.
            If omitted, or if the image has mode "1" or "P", it is set to ``PIL.Image.NEAREST``.
771
772
773
774
775
776
777
        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 (2-tuple, optional): Optional center of rotation.
            Origin is the upper left corner.
            Default is the center of the image.
Philip Meier's avatar
Philip Meier committed
778
779
780
        fill (n-tuple or int or float): Pixel fill value for area outside the rotated
            image. If int or float, the value is used for all bands respectively.
            Defaults to 0 for all bands. This option is only available for ``pillow>=5.2.0``.
781

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

784
    """
vfdev's avatar
vfdev committed
785
    if not F_pil._is_pil_image(img):
786
787
        raise TypeError('img should be PIL Image. Got {}'.format(type(img)))

788
    opts = _parse_fill(fill, img, '5.2.0')
789

Philip Meier's avatar
Philip Meier committed
790
    return img.rotate(angle, resample, expand, center, **opts)
791
792


vfdev's avatar
vfdev committed
793
794
795
def _get_inverse_affine_matrix(
        center: List[int], angle: float, translate: List[float], scale: float, shear: List[float]
) -> List[float]:
796
797
798
799
800
801
802
    # 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
803
804
805
806
807
808
809
810
811
812
    #       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]
    #
813
814
    # Thus, the inverse is M^-1 = C * RSS^-1 * C^-1 * T^-1

815
816
817
818
819
820
821
    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
822
823
824
825
    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)
826
827

    # Inverted rotation matrix with scale and shear
828
    # det([[a, b], [c, d]]) == 1, since det(rotation) = 1 and det(shear) = 1
vfdev's avatar
vfdev committed
829
830
    matrix = [d, -b, 0.0, -c, a, 0.0]
    matrix = [x / scale for x in matrix]
831
832

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

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

vfdev's avatar
vfdev committed
840
    return matrix
841

vfdev's avatar
vfdev committed
842
843
844
845
846
847
848
849

def affine(
        img: Tensor, angle: float, translate: List[int], scale: float, shear: List[float],
        resample: int = 0, fillcolor: Optional[int] = None
) -> 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.
850
851

    Args:
vfdev's avatar
vfdev committed
852
        img (PIL Image or Tensor): image to be rotated.
853
        angle (float or int): rotation angle in degrees between -180 and 180, clockwise direction.
854
855
        translate (list or tuple of integers): horizontal and vertical translations (post-rotation translation)
        scale (float): overall scale
ptrblck's avatar
ptrblck committed
856
        shear (float or tuple or list): shear angle value in degrees between -180 to 180, clockwise direction.
vfdev's avatar
vfdev committed
857
858
            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.
859
        resample (``PIL.Image.NEAREST`` or ``PIL.Image.BILINEAR`` or ``PIL.Image.BICUBIC``, optional):
vfdev's avatar
vfdev committed
860
861
862
            An optional resampling filter. See `filters`_ for more information.
            If omitted, or if the image is PIL Image and has mode "1" or "P", it is set to ``PIL.Image.NEAREST``.
            If input is Tensor, only ``PIL.Image.NEAREST`` and ``PIL.Image.BILINEAR`` are supported.
863
        fillcolor (int): Optional fill color for the area outside the transform in the output image. (Pillow>=5.0.0)
vfdev's avatar
vfdev committed
864
865
866

    Returns:
        PIL Image or Tensor: Transformed image.
867
    """
vfdev's avatar
vfdev committed
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
    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")

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

vfdev's avatar
vfdev committed
909
        return F_pil.affine(img, matrix=matrix, resample=resample, fillcolor=fillcolor)
910

vfdev's avatar
vfdev committed
911
912
    # we need to rescale translate by image size / 2 as its values can be between -1 and 1
    translate = [2.0 * t / s for s, t in zip(img_size, translate)]
913

vfdev's avatar
vfdev committed
914
915
    matrix = _get_inverse_affine_matrix([0, 0], angle, translate, scale, shear)
    return F_t.affine(img, matrix=matrix, resample=resample, fillcolor=fillcolor)
916
917


918
919
920
921
922
923
924
def to_grayscale(img, num_output_channels=1):
    """Convert image to grayscale version of image.

    Args:
        img (PIL Image): Image to be converted to grayscale.

    Returns:
925
926
927
928
        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
929
    """
vfdev's avatar
vfdev committed
930
    if not F_pil._is_pil_image(img):
931
932
933
934
935
936
937
938
939
940
941
942
943
        raise TypeError('img should be PIL Image. Got {}'.format(type(img)))

    if num_output_channels == 1:
        img = img.convert('L')
    elif num_output_channels == 3:
        img = img.convert('L')
        np_img = np.array(img, dtype=np.uint8)
        np_img = np.dstack([np_img, np_img, np_img])
        img = Image.fromarray(np_img, 'RGB')
    else:
        raise ValueError('num_output_channels should be either 1 or 3')

    return img
944
945


946
def erase(img: Tensor, i: int, j: int, h: int, w: int, v: Tensor, inplace: bool = False) -> Tensor:
947
948
949
950
951
952
953
954
955
    """ 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
956
        inplace(bool, optional): For in-place operations. By default is set False.
957
958
959
960
961
962
963

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

964
965
966
    if not inplace:
        img = img.clone()

967
968
    img[:, i:i + h, j:j + w] = v
    return img