Unverified Commit de908627 authored by Edgar Andrés Margffoy Tuay's avatar Edgar Andrés Margffoy Tuay Committed by GitHub
Browse files

Update docstings and expose main image io functions in the vision docs (#2760)

* Expose image io functions in docs

* Expose image funcs in module

* Update docstring

* Update docstrings for all functions

* Update section header
parent a9e4cea0
...@@ -4,7 +4,8 @@ torchvision.io ...@@ -4,7 +4,8 @@ torchvision.io
.. currentmodule:: torchvision.io .. currentmodule:: torchvision.io
The :mod:`torchvision.io` package provides functions for performing IO The :mod:`torchvision.io` package provides functions for performing IO
operations. They are currently specific to reading and writing video. operations. They are currently specific to reading and writing video and
images.
Video Video
----- -----
...@@ -14,3 +15,19 @@ Video ...@@ -14,3 +15,19 @@ Video
.. autofunction:: read_video_timestamps .. autofunction:: read_video_timestamps
.. autofunction:: write_video .. autofunction:: write_video
Image
-----
.. autofunction:: read_image
.. autofunction:: decode_image
.. autofunction:: encode_jpeg
.. autofunction:: write_jpeg
.. autofunction:: encode_png
.. autofunction:: write_png
...@@ -14,6 +14,15 @@ from .video import ( ...@@ -14,6 +14,15 @@ from .video import (
read_video_timestamps, read_video_timestamps,
write_video, write_video,
) )
from .image import (
read_image,
decode_image,
encode_jpeg,
write_jpeg,
encode_png,
write_png
)
__all__ = [ __all__ = [
"write_video", "write_video",
...@@ -29,5 +38,11 @@ __all__ = [ ...@@ -29,5 +38,11 @@ __all__ = [
"_read_video_clip_from_memory", "_read_video_clip_from_memory",
"_read_video_meta_data", "_read_video_meta_data",
"VideoMetaData", "VideoMetaData",
"Timebase" "Timebase",
'read_image',
'decode_image',
'encode_jpeg',
'write_jpeg',
'encode_png',
'write_png',
] ]
...@@ -73,14 +73,20 @@ def encode_png(input: torch.Tensor, compression_level: int = 6) -> torch.Tensor: ...@@ -73,14 +73,20 @@ def encode_png(input: torch.Tensor, compression_level: int = 6) -> torch.Tensor:
""" """
Takes an input tensor in CHW layout and returns a buffer with the contents Takes an input tensor in CHW layout and returns a buffer with the contents
of its corresponding PNG file. of its corresponding PNG file.
Arguments:
input (Tensor[channels, image_height, image_width]): int8 image tensor Parameters
of `c` channels, where `c` must 3 or 1. ----------
compression_level (int): Compression factor for the resulting file, it input: Tensor[channels, image_height, image_width]
must be a number between 0 and 9. Default: 6 int8 image tensor of `c` channels, where `c` must 3 or 1.
compression_level: int
Compression factor for the resulting file, it must be a number
between 0 and 9. Default: 6
Returns Returns
output (Tensor[1]): A one dimensional int8 tensor that contains the raw -------
bytes of the PNG file. output: Tensor[1]
A one dimensional int8 tensor that contains the raw bytes of the
PNG file.
""" """
output = torch.ops.image.encode_png(input, compression_level) output = torch.ops.image.encode_png(input, compression_level)
return output return output
...@@ -90,12 +96,16 @@ def write_png(input: torch.Tensor, filename: str, compression_level: int = 6): ...@@ -90,12 +96,16 @@ def write_png(input: torch.Tensor, filename: str, compression_level: int = 6):
""" """
Takes an input tensor in CHW layout (or HW in the case of grayscale images) Takes an input tensor in CHW layout (or HW in the case of grayscale images)
and saves it in a PNG file. and saves it in a PNG file.
Arguments:
input (Tensor[channels, image_height, image_width]): int8 image tensor Parameters
of `c` channels, where `c` must be 1 or 3. ----------
filename (str): Path to save the image. input: Tensor[channels, image_height, image_width]
compression_level (int): Compression factor for the resulting file, it int8 image tensor of `c` channels, where `c` must be 1 or 3.
must be a number between 0 and 9. Default: 6 filename: str
Path to save the image.
compression_level: int
Compression factor for the resulting file, it must be a number
between 0 and 9. Default: 6
""" """
torch.ops.image.write_png(input, filename, compression_level) torch.ops.image.write_png(input, filename, compression_level)
...@@ -131,14 +141,20 @@ def encode_jpeg(input: torch.Tensor, quality: int = 75) -> torch.Tensor: ...@@ -131,14 +141,20 @@ def encode_jpeg(input: torch.Tensor, quality: int = 75) -> torch.Tensor:
""" """
Takes an input tensor in CHW layout and returns a buffer with the contents Takes an input tensor in CHW layout and returns a buffer with the contents
of its corresponding JPEG file. of its corresponding JPEG file.
Arguments:
input (Tensor[channels, image_height, image_width]): int8 image tensor Parameters
of `c` channels, where `c` must be 1 or 3. ----------
quality (int): Quality of the resulting JPEG file, it must be a number input: Tensor[channels, image_height, image_width])
between 1 and 100. Default: 75 int8 image tensor of `c` channels, where `c` must be 1 or 3.
quality: int
Quality of the resulting JPEG file, it must be a number between
1 and 100. Default: 75
Returns Returns
output (Tensor[1]): A one dimensional int8 tensor that contains the raw -------
bytes of the JPEG file. output: Tensor[1]
A one dimensional int8 tensor that contains the raw bytes of the
JPEG file.
""" """
if quality < 1 or quality > 100: if quality < 1 or quality > 100:
raise ValueError('Image quality should be a positive number ' raise ValueError('Image quality should be a positive number '
...@@ -151,12 +167,16 @@ def encode_jpeg(input: torch.Tensor, quality: int = 75) -> torch.Tensor: ...@@ -151,12 +167,16 @@ def encode_jpeg(input: torch.Tensor, quality: int = 75) -> torch.Tensor:
def write_jpeg(input: torch.Tensor, filename: str, quality: int = 75): def write_jpeg(input: torch.Tensor, filename: str, quality: int = 75):
""" """
Takes an input tensor in CHW layout and saves it in a JPEG file. Takes an input tensor in CHW layout and saves it in a JPEG file.
Arguments:
input (Tensor[channels, image_height, image_width]): int8 image tensor Parameters
of `c` channels, where `c` must be 1 or 3. ----------
filename (str): Path to save the image. input: Tensor[channels, image_height, image_width]
quality (int): Quality of the resulting JPEG file, it must be a number int8 image tensor of `c` channels, where `c` must be 1 or 3.
between 1 and 100. Default: 75 filename: str
Path to save the image.
quality: int
Quality of the resulting JPEG file, it must be a number
between 1 and 100. Default: 75
""" """
if quality < 1 or quality > 100: if quality < 1 or quality > 100:
raise ValueError('Image quality should be a positive number ' raise ValueError('Image quality should be a positive number '
...@@ -172,11 +192,15 @@ def decode_image(input: torch.Tensor) -> torch.Tensor: ...@@ -172,11 +192,15 @@ def decode_image(input: torch.Tensor) -> torch.Tensor:
The values of the output tensor are uint8 between 0 and 255. The values of the output tensor are uint8 between 0 and 255.
Arguments: Parameters
input (Tensor): a one dimensional uint8 tensor containing ----------
the raw bytes of the PNG or JPEG image. input: Tensor
Returns: a one dimensional uint8 tensor containing the raw bytes of the
output (Tensor[3, image_height, image_width]) PNG or JPEG image.
Returns
-------
output: Tensor[3, image_height, image_width]
""" """
output = torch.ops.image.decode_image(input) output = torch.ops.image.decode_image(input)
return output return output
...@@ -186,10 +210,15 @@ def read_image(path: str) -> torch.Tensor: ...@@ -186,10 +210,15 @@ def read_image(path: str) -> torch.Tensor:
""" """
Reads a JPEG or PNG image into a 3 dimensional RGB Tensor. Reads a JPEG or PNG image into a 3 dimensional RGB Tensor.
The values of the output tensor are uint8 between 0 and 255. The values of the output tensor are uint8 between 0 and 255.
Arguments:
path (str): path of the JPEG or PNG image. Parameters
Returns: ----------
output (Tensor[3, image_height, image_width]) path: str
path of the JPEG or PNG image.
Returns
-------
output: Tensor[3, image_height, image_width]
""" """
data = read_file(path) data = read_file(path)
return decode_image(data) return decode_image(data)
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