Advanced Color Conversion

Overview

The Advanced Color Conversion sample demonstrates GPU-accelerated color-space transformation using CV-CUDA’s advcvtcolor operator. Unlike the basic CvtColor Operator, advcvtcolor accepts a :pydata:`cvcuda.ColorSpec` argument that selects the standardized luma/chroma coefficients (BT.601, BT.709, or BT.2020) used during the conversion. This sample converts an RGB image to YUV (BT.709) and then back to RGB, demonstrating the round-trip workflow common in video-processing pipelines.

Usage

Basic Usage

Run with the default tabby cat image:

python3 advcvtcolor.py -i input.jpg

Custom Input and Output

Specify a custom input image and output path:

python3 advcvtcolor.py -i image.jpg -o cat_advcvtcolor.jpg

Command-Line Arguments

Argument

Short Form

Default

Description

--input

-i

tabby_tiger_cat.jpg

Input image file path

--output

-o

cvcuda/.cache/cat_advcvtcolor.jpg

Output image file path

Implementation

RGB to YUV and Back

# 1. Convert the RGB image to YUV using the BT.709 color specification.
#    BT.709 is the standard for HDTV content and is a common choice for
#    high-quality color-space transformations.
yuv_image: cvcuda.Tensor = cvcuda.advcvtcolor(
    input_image,
    cvcuda.ColorConversion.RGB2YUV,
    cvcuda.ColorSpec.BT709,
)

# 2. Convert the YUV image back to RGB so the result is a viewable image.
#    Using the same color specification (BT.709) ensures a round-trip that
#    closely reproduces the original colors.
output_image: cvcuda.Tensor = cvcuda.advcvtcolor(
    yuv_image,
    cvcuda.ColorConversion.YUV2RGB,
    cvcuda.ColorSpec.BT709,
)

write_image(output_image, args.output)

Key points:

  1. Color Specification: The spec argument selects the luma/chroma coefficients standard (BT.601 for SD video, BT.709 for HDTV, BT.2020 for UHD/HDR). Mixing specifications between forward and inverse conversions will produce incorrect colors.

  2. Round-trip fidelity: Converting RGB → YUV → RGB with the same ColorSpec closely reproduces the original image; any visible difference is due to quantization in uint8.

  3. Supported layouts: Both HWC (single image) and NHWC (batch) layouts are accepted without any reshaping step.

  4. Output shape preserved: The output tensor always has the same shape and dtype as the input, so no extra allocation or reshape is needed for 444 (3-channel) conversions.

  5. NV12/NV21 variants: For semi-planar YUV (NV12/NV21) conversions the input height must be H * 3 / 2 and channels must be 1; the 444 interleaved path used here keeps the standard (H, W, 3) shape.

Expected Output

After the RGB → YUV → RGB round-trip the image looks nearly identical to the original:

../../_images/tabby_tiger_cat.jpg

Original Input Image
../../_images/cat_advcvtcolor.jpg

Output: RGB → YUV (BT.709) → RGB

CV-CUDA Operators Used

Operator

Purpose

cvcuda.advcvtcolor()

Convert between RGB and YUV color spaces with a selectable color specification

Common Utilities Used

See Also