Skip to content

docs: precise yuv flavor in docstrings #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
coco-speed wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: precise yuv flavor in docstrings #90

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
57ca8f1
docs: precise yuv flavor in docstrings
egidioln Sep 9, 2024
a3fab35
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Sep 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 86 additions & 18 deletions kornia/color/yuv.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,13 @@ def rgb_to_yuv(image: Tensor) -> Tensor:

.. image:: _static/img/rgb_to_yuv.png

The image data is assumed to be in the range of (0, 1).
The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of
:math:`(0, 1)` to luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`,
respectively.

The YUV model adopted here follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.
Expand Down Expand Up @@ -45,8 +51,14 @@ def rgb_to_yuv(image: Tensor) -> Tensor:
def rgb_to_yuv420(image: Tensor) -> Tuple[Tensor, Tensor]:
r"""Convert an RGB image to YUV 420 (subsampled).

The image data is assumed to be in the range of (0, 1). Input need to be padded to be evenly divisible by 2
horizontal and vertical. This function will output chroma siting (0.5,0.5)
Input need to be padded to be evenly divisible by 2 horizontal and vertical.

The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of :math:`(0, 1)` to
luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

The YUV model adopted here follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.
Expand Down Expand Up @@ -76,8 +88,15 @@ def rgb_to_yuv420(image: Tensor) -> Tuple[Tensor, Tensor]:
def rgb_to_yuv422(image: Tensor) -> Tuple[Tensor, Tensor]:
r"""Convert an RGB image to YUV 422 (subsampled).

The image data is assumed to be in the range of (0, 1). Input need to be padded to be evenly divisible by 2
vertical. This function will output chroma siting (0.5)
Input need to be padded to be evenly divisible by 2 vertical.

The image data is assumed to be in the range of :math:`(0, 1)`. The range of the output is of
:math:`(0, 1)` to luma and the ranges of U and V are :math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`,
respectively.

The YUV model adopted here follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
image: RGB Image to be converted to YUV with shape :math:`(*, 3, H, W)`.
Expand Down Expand Up @@ -107,7 +126,12 @@ def rgb_to_yuv422(image: Tensor) -> Tuple[Tensor, Tensor]:
def yuv_to_rgb(image: Tensor) -> Tensor:
r"""Convert an YUV image to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
image: YUV Image to be converted to RGB with shape :math:`(*, 3, H, W)`.
Expand Down Expand Up @@ -141,9 +165,14 @@ def yuv_to_rgb(image: Tensor) -> Tensor:
def yuv420_to_rgb(imagey: Tensor, imageuv: Tensor) -> Tensor:
r"""Convert an YUV420 image to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
Input need to be padded to be evenly divisible by 2 horizontal and vertical.
This function assumed chroma siting is (0.5, 0.5)

The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
imagey: Y (luma) Image plane to be converted to RGB with shape :math:`(*, 1, H, W)`.
Expand Down Expand Up @@ -192,8 +221,14 @@ def yuv420_to_rgb(imagey: Tensor, imageuv: Tensor) -> Tensor:
def yuv422_to_rgb(imagey: Tensor, imageuv: Tensor) -> Tensor:
r"""Convert an YUV422 image to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
Input need to be padded to be evenly divisible by 2 vertical. This function assumed chroma siting is (0.5)
Input need to be padded to be evenly divisible by 2 vertical.

The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Args:
imagey: Y (luma) Image plane to be converted to RGB with shape :math:`(*, 1, H, W)`.
Expand Down Expand Up @@ -236,7 +271,11 @@ def yuv422_to_rgb(imagey: Tensor, imageuv: Tensor) -> Tensor:
class RgbToYuv(Module):
r"""Convert an image from RGB to YUV.

The image data is assumed to be in the range of (0, 1).
The image data is assumed to be in the range of :math:`(0, 1)`.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
YUV version of the image.
Expand All @@ -261,7 +300,13 @@ def forward(self, input: Tensor) -> Tensor:
class RgbToYuv420(Module):
r"""Convert an image from RGB to YUV420.

The image data is assumed to be in the range of (0, 1). Width and Height evenly divisible by 2.
Width and Height evenly divisible by 2.

The image data is assumed to be in the range of :math:`(0, 1)`.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
YUV420 version of the image.
Expand All @@ -286,7 +331,13 @@ def forward(self, yuvinput: Tensor) -> Tuple[Tensor, Tensor]: # skipcq: PYL-R02
class RgbToYuv422(Module):
r"""Convert an image from RGB to YUV422.

The image data is assumed to be in the range of (0, 1). Width evenly disvisible by 2.
Width must be evenly disvisible by 2.

The image data is assumed to be in the range of :math:`(0, 1)`.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
YUV422 version of the image.
Expand All @@ -311,7 +362,12 @@ def forward(self, yuvinput: Tensor) -> Tuple[Tensor, Tensor]: # skipcq: PYL-R02
class YuvToRgb(Module):
r"""Convert an image from YUV to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
RGB version of the image.
Expand All @@ -333,8 +389,14 @@ def forward(self, input: Tensor) -> Tensor:
class Yuv420ToRgb(Module):
r"""Convert an image from YUV to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
Width and Height evenly divisible by 2.
Width and Height must be evenly divisible by 2.

The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
RGB version of the image.
Expand All @@ -358,8 +420,14 @@ def forward(self, inputy: Tensor, inputuv: Tensor) -> Tensor: # skipcq: PYL-R02
class Yuv422ToRgb(Module):
r"""Convert an image from YUV to RGB.

The image data is assumed to be in the range of (0, 1) for luma and (-0.5, 0.5) for chroma.
Width evenly divisible by 2.
Width must be evenly divisible by 2.

The image data is assumed to be in the range of :math:`(0, 1)` for luma (Y). The ranges of U and V are
:math:`(-0.436, 0.436)` and :math:`(-0.615, 0.615)`, respectively.

YUV formula follows M/PAL values (see
`BT.470-5 <https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.470-5-199802-S!!PDF-E.pdf>`_, Table 2,
items 2.5 and 2.6).

Returns:
RGB version of the image.
Expand Down