Skip to content

GitLab

Unverified Commit 7b9d30eb authored by Zhengyang Feng's avatar Zhengyang Feng Committed by GitHub
Browse files

Transforms documentation clean-up (#3200) 

* Initial doc clean-up

* Remove all private docs

* Rename files

* Highlight backend inconsistencies

* Sequence and number

* [Need checking] AutoAugment related doc change

* Revert name changes
parent 8c0bb6c2
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 188 additions and 881 deletions
torchvision/transforms/autoaugment.py
View file @ 7b9d30eb
......@@ -127,8 +127,9 @@ def _get_magnitudes():
class AutoAugment(torch.nn.Module):
r"""AutoAugment data augmentation method based on
`"AutoAugment: Learning Augmentation Strategies from Data" <https://arxiv.org/pdf/1805.09501.pdf>`_.
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.
If the image is torch Tensor, it should be of type torch.uint8, and it is expected
to have [..., 1 or 3, H, W] shape, where ... means an arbitrary number of leading dimensions.
If img is PIL Image, it is expected to be in mode "L" or "RGB".
Args:
policy (AutoAugmentPolicy): Desired policy enum defined by
......@@ -136,9 +137,8 @@ class AutoAugment(torch.nn.Module):
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.
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.
fill (sequence or number, optional): Pixel fill value for the area outside the transformed
image. If given a number, the value is used for all bands respectively.
If input is PIL Image, the options is only available for ``Pillow>=5.0.0``.
Example:
......
torchvision/transforms/functional.py
View file @ 7b9d30eb
This diff is collapsed.
torchvision/transforms/functional_pil.py
View file @ 7b9d30eb
......@@ -35,19 +35,6 @@ def _get_image_num_channels(img: Any) -> int:
@torch.jit.unused
def hflip(img):
"""PRIVATE METHOD. Horizontally flip the given PIL Image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be flipped.
Returns:
PIL Image: Horizontally flipped image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -56,19 +43,6 @@ def hflip(img):
@torch.jit.unused
def vflip(img):
"""PRIVATE METHOD. Vertically flip the given PIL Image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be flipped.
Returns:
PIL Image: Vertically flipped image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -77,22 +51,6 @@ def vflip(img):
@torch.jit.unused
def adjust_brightness(img, brightness_factor):
"""PRIVATE METHOD. Adjust brightness of an RGB image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be adjusted.
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:
PIL Image: Brightness adjusted image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -103,21 +61,6 @@ def adjust_brightness(img, brightness_factor):
@torch.jit.unused
def adjust_contrast(img, contrast_factor):
"""PRIVATE METHOD. Adjust contrast of an Image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): PIL Image to be adjusted.
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:
PIL Image: Contrast adjusted image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -128,21 +71,6 @@ def adjust_contrast(img, contrast_factor):
@torch.jit.unused
def adjust_saturation(img, saturation_factor):
"""PRIVATE METHOD. Adjust color saturation of an image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): PIL Image to be adjusted.
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:
PIL Image: Saturation adjusted image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -153,35 +81,6 @@ def adjust_saturation(img, saturation_factor):
@torch.jit.unused
def adjust_hue(img, hue_factor):
"""PRIVATE METHOD. Adjust hue of an image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
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]`.
See `Hue`_ for more details.
.. _Hue: https://en.wikipedia.org/wiki/Hue
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.
"""
if not(-0.5 <= hue_factor <= 0.5):
raise ValueError('hue_factor ({}) is not in [-0.5, 0.5].'.format(hue_factor))
......@@ -206,30 +105,6 @@ def adjust_hue(img, hue_factor):
@torch.jit.unused
def adjust_gamma(img, gamma, gain=1):
r"""PRIVATE METHOD. Perform gamma correction on an image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Also known as Power Law Transform. Intensities in RGB mode are adjusted
based on the following equation:
.. math::
I_{\text{out}} = 255 \times \text{gain} \times \left(\frac{I_{\text{in}}}{255}\right)^{\gamma}
See `Gamma Correction`_ for more details.
.. _Gamma Correction: https://en.wikipedia.org/wiki/Gamma_correction
Args:
img (PIL Image): PIL Image to be adjusted.
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.
gain (float): The constant multiplier.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -247,44 +122,6 @@ def adjust_gamma(img, gamma, gain=1):
@torch.jit.unused
def pad(img, padding, fill=0, padding_mode="constant"):
r"""PRIVATE METHOD. Pad the given PIL.Image on all sides with the given "pad" value.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be padded.
padding (int or tuple or list): Padding on each border. If a single int is provided this
is used to pad all borders. If a tuple or list of length 2 is provided this is the padding
on left/right and top/bottom respectively. If a tuple or list of length 4 is provided
this is the padding for the left, top, right and bottom borders respectively. For compatibility reasons
with ``functional_tensor.pad``, if a tuple or list of length 1 is provided, it is interpreted as
a single int.
fill (int or str or tuple): Pixel fill value for constant fill. Default is 0. If a tuple of
length 3, it is used to fill R, G, B channels respectively.
This value is only used when the padding_mode is constant.
padding_mode: Type of padding. Should be: constant, edge, reflect or symmetric. Default is constant.
- 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]
Returns:
PIL Image: Padded image.
"""
if not _is_pil_image(img):
raise TypeError("img should be PIL Image. Got {}".format(type(img)))
......@@ -360,23 +197,6 @@ def pad(img, padding, fill=0, padding_mode="constant"):
@torch.jit.unused
def crop(img: Image.Image, top: int, left: int, height: int, width: int) -> Image.Image:
"""PRIVATE METHOD. Crop the given PIL Image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be cropped. (0,0) denotes the top left corner of the image.
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.
Returns:
PIL Image: Cropped image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -385,27 +205,6 @@ def crop(img: Image.Image, top: int, left: int, height: int, width: int) -> Imag
@torch.jit.unused
def resize(img, size, interpolation=Image.BILINEAR):
r"""PRIVATE METHOD. Resize the input PIL Image to the given size.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be resized.
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,
the smaller edge of the image will be matched to this number maintaining
the aspect ratio. i.e, if height > width, then image will be rescaled to
:math:`\left(\text{size} \times \frac{\text{height}}{\text{width}}, \text{size}\right)`.
For compatibility reasons with ``functional_tensor.resize``, if a tuple or list of length 1 is provided,
it is interpreted as a single int.
interpolation (int, optional): Desired interpolation. Default is ``PIL.Image.BILINEAR``.
Returns:
PIL Image: Resized image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
if not (isinstance(size, int) or (isinstance(size, Sequence) and len(size) in (1, 2))):
......@@ -431,25 +230,7 @@ def resize(img, size, interpolation=Image.BILINEAR):
@torch.jit.unused
def _parse_fill(fill, img, min_pil_version, name="fillcolor"):
"""PRIVATE METHOD. Helper function to get the fill color for rotate, perspective transforms, and pad.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
fill (n-tuple or int or float): Pixel fill value for area outside the transformed
image. If int or float, the value is used for all bands respectively.
Defaults to 0 for all bands.
img (PIL Image): Image to be filled.
min_pil_version (str): The minimum PILLOW version for when the ``fillcolor`` option
was first introduced in the calling function. (e.g. rotate->5.2.0, perspective->5.0.0)
name (str): Name of the ``fillcolor`` option in the output. Defaults to ``"fillcolor"``.
Returns:
dict: kwarg for ``fillcolor``
"""
# Process fill color for affine transforms
major_found, minor_found = (int(v) for v in PILLOW_VERSION.split('.')[:2])
major_required, minor_required = (int(v) for v in min_pil_version.split('.')[:2])
if major_found < major_required or (major_found == major_required and minor_found < minor_required):
......@@ -478,25 +259,6 @@ def _parse_fill(fill, img, min_pil_version, name="fillcolor"):
@torch.jit.unused
def affine(img, matrix, interpolation=0, fill=None):
"""PRIVATE METHOD. Apply affine transformation on the PIL Image keeping image center invariant.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): image to be rotated.
matrix (list of floats): list of 6 float values representing inverse matrix for affine transformation.
interpolation (``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``.
fill (int): Optional fill color for the area outside the transform in the output image. (Pillow>=5.0.0)
Returns:
PIL Image: Transformed image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -507,36 +269,6 @@ def affine(img, matrix, interpolation=0, fill=None):
@torch.jit.unused
def rotate(img, angle, interpolation=0, expand=False, center=None, fill=None):
"""PRIVATE METHOD. Rotate PIL image by angle.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): image to be rotated.
angle (float or int): rotation angle value in degrees, counter-clockwise.
interpolation (``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``.
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.
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``.
Returns:
PIL Image: Rotated image.
.. _filters: https://pillow.readthedocs.io/en/latest/handbook/concepts.html#filters
"""
if not _is_pil_image(img):
raise TypeError("img should be PIL Image. Got {}".format(type(img)))
......@@ -546,25 +278,6 @@ def rotate(img, angle, interpolation=0, expand=False, center=None, fill=None):
@torch.jit.unused
def perspective(img, perspective_coeffs, interpolation=Image.BICUBIC, fill=None):
"""PRIVATE METHOD. Perform perspective transform of the given PIL Image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): Image to be transformed.
perspective_coeffs (list of float): perspective transformation coefficients.
interpolation (int): Interpolation type. Default, ``Image.BICUBIC``.
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``.
Returns:
PIL Image: Perspectively transformed Image.
"""
if not _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......@@ -575,23 +288,6 @@ def perspective(img, perspective_coeffs, interpolation=Image.BICUBIC, fill=None)
@torch.jit.unused
def to_grayscale(img, num_output_channels):
"""PRIVATE METHOD. Convert PIL image of any mode (RGB, HSV, LAB, etc) to grayscale version of image.
.. warning::
Module ``transforms.functional_pil`` is private and should not be used in user application.
Please, consider instead using methods from `transforms.functional` module.
Args:
img (PIL Image): 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: 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 _is_pil_image(img):
raise TypeError('img should be PIL Image. Got {}'.format(type(img)))
......
torchvision/transforms/functional_tensor.py
View file @ 7b9d30eb
This diff is collapsed.
torchvision/transforms/transforms.py
View file @ 7b9d30eb
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment