transforms.rst 4.59 KB
Newer Older
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
1
2
torchvision.transforms
======================
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
3
4
5

.. currentmodule:: torchvision.transforms

6
7
8
9
10
Transforms are common image transformations. They can be chained together using :class:`Compose`.
Additionally, there is the :mod:`torchvision.transforms.functional` module.
Functional transforms give fine-grained control over the transformations.
This is useful if you have to build a more complex transformation pipeline
(e.g. in the case of segmentation tasks).
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
11

12
13
14
15
16
All transformations accept PIL Image, Tensor Image or batch of Tensor Images as input. Tensor Image is a tensor with
``(C, H, W)`` shape, where ``C`` is a number of channels, ``H`` and ``W`` are image height and width. Batch of
Tensor Images is a tensor of ``(B, C, H, W)`` shape, where ``B`` is a number of images in the batch. Deterministic or
random transformations applied on the batch of Tensor Images identically transform all the images of the batch.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
.. warning::

    Since v0.8.0 all random transformations are using torch default random generator to sample random parameters.
    It is a backward compatibility breaking change and user should set the random state as following:

    .. code:: python

        # Previous versions
        # import random
        # random.seed(12)

        # Now
        import torch
        torch.manual_seed(17)

    Please, keep in mind that the same seed for torch random generator and Python random generator will not
    produce the same results.

35
36

Scriptable transforms
vfdev's avatar
vfdev committed
37
---------------------
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

In order to script the transformations, please use ``torch.nn.Sequential`` instead of :class:`Compose`.

.. code:: python

    transforms = torch.nn.Sequential(
        transforms.CenterCrop(10),
        transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
    )
    scripted_transforms = torch.jit.script(transforms)

Make sure to use only scriptable transformations, i.e. that work with ``torch.Tensor`` and does not require
`lambda` functions or ``PIL.Image``.

For any custom transformations to be used with ``torch.jit.script``, they should be derived from ``torch.nn.Module``.

54

vfdev's avatar
vfdev committed
55
56
Compositions of transforms
--------------------------
57

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
58
59
.. autoclass:: Compose

60
Transforms on PIL Image
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
61
62
-----------------------

63
.. autoclass:: CenterCrop
64

65
.. autoclass:: ColorJitter
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
66

67
.. autoclass:: FiveCrop
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
68

69
.. autoclass:: Grayscale
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
70

71
.. autoclass:: Pad
72

73
.. autoclass:: RandomAffine
74

75
.. autoclass:: RandomApply
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
76

77
.. autoclass:: RandomChoice
78

79
.. autoclass:: RandomCrop
80

81
.. autoclass:: RandomGrayscale
82

83
.. autoclass:: RandomHorizontalFlip
84

85
.. autoclass:: RandomOrder
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
86

87
88
.. autoclass:: RandomPerspective

89
.. autoclass:: RandomResizedCrop
90

91
92
.. autoclass:: RandomRotation

93
94
95
96
97
98
99
100
101
.. autoclass:: RandomSizedCrop

.. autoclass:: RandomVerticalFlip

.. autoclass:: Resize

.. autoclass:: Scale

.. autoclass:: TenCrop
102

103
104
.. autoclass:: GaussianBlur

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
105
106
107
Transforms on torch.\*Tensor
----------------------------

surgan12's avatar
surgan12 committed
108
109
.. autoclass:: LinearTransformation

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
110
111
112
113
.. autoclass:: Normalize
	:members: __call__
	:special-members:

114
115
.. autoclass:: RandomErasing

Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
116
117
118
Conversion Transforms
---------------------

119
.. autoclass:: ToPILImage
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
120
121
122
	:members: __call__
	:special-members:

123
.. autoclass:: ToTensor
Sasank Chilamkurthy's avatar
Sasank Chilamkurthy committed
124
125
126
127
128
129
130
131
	:members: __call__
	:special-members:

Generic Transforms
------------------

.. autoclass:: Lambda

132
133
134
135

Functional Transforms
---------------------

136
137
138
139
Functional transforms give you fine-grained control of the transformation pipeline.
As opposed to the transformations above, functional transforms don't contain a random number
generator for their parameters.
That means you have to specify/generate all parameters, but you can reuse the functional transform.
140
141
142

Example:
you can apply a functional transform with the same parameters to multiple images like this:
143
144
145
146
147
148
149

.. code:: python

    import torchvision.transforms.functional as TF
    import random

    def my_segmentation_transforms(image, segmentation):
150
        if random.random() > 0.5:
151
152
153
154
155
156
            angle = random.randint(-30, 30)
            image = TF.rotate(image, angle)
            segmentation = TF.rotate(segmentation, angle)
        # more transforms ...
        return image, segmentation

157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

Example:
you can use a functional transform to build transform classes with custom behavior:

.. code:: python

    import torchvision.transforms.functional as TF
    import random

    class MyRotationTransform:
        """Rotate by one of the given angles."""

        def __init__(self, angles):
            self.angles = angles

        def __call__(self, x):
            angle = random.choice(self.angles)
            return TF.rotate(x, angle)

    rotation_transform = MyRotationTransform(angles=[-30, -15, 0, 15, 30])


179
180
.. automodule:: torchvision.transforms.functional
    :members: