Repository: pytorch/vision

Issue:
Clean up and Document the io.image enhancements
PR #3024 introduced a few enhancements on the `io.image` methods used for reading JPEG and PNG images. The code changes were merged but there are a few nice-to-have improvements missing.

More specifically:
- [x] Provide better error messages for [JPEG](https://github.com/pytorch/vision/pull/3024#discussion_r527066925) and [PNG](https://github.com/pytorch/vision/pull/3024#discussion_r527093866) when a specific `ImageReadMode` value is not supported.
- [x] Ensure that `image_read_mode.h` has a new line at the [end of the file](https://github.com/pytorch/vision/pull/3024#discussion_r526710809).
- [x] [Replace](https://github.com/pytorch/vision/pull/3024#discussion_r527065253) the old `#define` with the newer `constexpr` expression at `image_read_mode.h`.
- [x] [Move the documentation](https://github.com/pytorch/vision/pull/3024#discussion_r527095264) of `ImageReadMode` values from the methods to the enum.

**Note:** `constexpr` might cause problems on Windows. If that's the case, try using const instead.


Discussion:
Hey! I was wondering if I could contribute to this issue, is there anyone already working on it?
Hey @Sid2697, welcome!

Go for it. Looking forward to your PR.

Resolving patch:
diff --git a/torchvision/io/image.py b/torchvision/io/image.py
--- a/torchvision/io/image.py
+++ b/torchvision/io/image.py
@@ -50,6 +50,15 @@
 
 
 class ImageReadMode(Enum):
+    """
+    Support for various modes while reading images.
+
+    Use `ImageReadMode.UNCHANGED` for loading the image as-is,
+    `ImageReadMode.GRAY` for converting to grayscale,
+    `ImageReadMode.GRAY_ALPHA` for grayscale with transparency,
+    `ImageReadMode.RGB` for RGB and `ImageReadMode.RGB_ALPHA` for
+    RGB with transparency.
+    """
     UNCHANGED = 0
     GRAY = 1
     GRAY_ALPHA = 2
@@ -94,11 +103,9 @@ def decode_png(input: torch.Tensor, mode: ImageReadMode = ImageReadMode.UNCHANGE
         input (Tensor[1]): a one dimensional uint8 tensor containing
     the raw bytes of the PNG image.
         mode (ImageReadMode): the read mode used for optionally
-    converting the image. Use `ImageReadMode.UNCHANGED` for loading
-    the image as-is, `ImageReadMode.GRAY` for converting to grayscale,
-    `ImageReadMode.GRAY_ALPHA` for grayscale with transparency,
-    `ImageReadMode.RGB` for RGB and `ImageReadMode.RGB_ALPHA` for
-     RGB with transparency. Default: `ImageReadMode.UNCHANGED`
+    converting the image. Default: `ImageReadMode.UNCHANGED`.
+    See `ImageReadMode` class for more information on various
+    available modes.
 
     Returns:
         output (Tensor[image_channels, image_height, image_width])
@@ -159,9 +166,9 @@ def decode_jpeg(input: torch.Tensor, mode: ImageReadMode = ImageReadMode.UNCHANG
         input (Tensor[1]): a one dimensional uint8 tensor containing
     the raw bytes of the JPEG image.
         mode (ImageReadMode): the read mode used for optionally
-    converting the image. Use `ImageReadMode.UNCHANGED` for loading
-    the image as-is, `ImageReadMode.GRAY` for converting to grayscale
-    and `ImageReadMode.RGB` for RGB. Default: `ImageReadMode.UNCHANGED`
+    converting the image. Default: `ImageReadMode.UNCHANGED`.
+    See `ImageReadMode` class for more information on various
+    available modes.
 
     Returns:
         output (Tensor[image_channels, image_height, image_width])
@@ -229,11 +236,10 @@ def decode_image(input: torch.Tensor, mode: ImageReadMode = ImageReadMode.UNCHAN
         a one dimensional uint8 tensor containing the raw bytes of the
         PNG or JPEG image.
     mode: ImageReadMode
-        the read mode used for optionally converting the image. JPEG
-        and PNG images have different permitted values. The default
-        value is `ImageReadMode.UNCHANGED` and it keeps the image as-is.
-        See `decode_jpeg()` and `decode_png()` for more information.
-        Default: `ImageReadMode.UNCHANGED`
+        the read mode used for optionally converting the image.
+        Default: `ImageReadMode.UNCHANGED`.
+        See `ImageReadMode` class for more information on various
+        available modes.
 
     Returns
     -------
@@ -254,11 +260,10 @@ def read_image(path: str, mode: ImageReadMode = ImageReadMode.UNCHANGED) -> torc
     path: str
         path of the JPEG or PNG image.
     mode: ImageReadMode
-        the read mode used for optionally converting the image. JPEG
-        and PNG images have different permitted values. The default
-        value is `ImageReadMode.UNCHANGED` and it keeps the image as-is.
-        See `decode_jpeg()` and `decode_png()` for more information.
-        Default: `ImageReadMode.UNCHANGED`
+        the read mode used for optionally converting the image.
+        Default: `ImageReadMode.UNCHANGED`.
+        See `ImageReadMode` class for more information on various
+        available modes.
 
     Returns
     -------


Test patch: