decode_image

torchcodec.decoders.decode_image(source: str | Path | bytes | Tensor, *, mode: Literal['UNCHANGED', 'GRAY', 'GRAY_ALPHA', 'RGB', 'RGB_ALPHA'] | ImageReadMode = 'RGB', output_dtype: dtype | Literal['auto'] = torch.uint8) → Tensor

Decode an image into a [N]CHW tensor, detecting the format automatically.

The format is detected from the encoded data (not the file extension), and decoding is delegated to the matching format-specific decoder. Supported formats are JPEG, PNG, WebP, GIF, AVIF and HEIC (requires libheif). The output shape is (C, H, W) for a single image and (N, C, H, W) for animated or multi-image formats (WebP, GIF, AVIF, HEIC).

For finer control, or for format-specific options (e.g. device for CUDA JPEG decoding, num_threads for AVIF), use the dedicated decoders directly: decode_jpeg(), decode_png(), decode_webp(), decode_gif(), decode_avif(), decode_heic().

Example

from torchcodec.decoders import decode_image

jpeg_img = decode_image("image.jpg")
png_img = decode_image("image.png")

Parameters:

• source (str, pathlib.Path, bytes, or torch.Tensor) – The encoded image data: a path (str or pathlib.Path), a bytes object, or a 1-D uint8 torch.Tensor of the raw encoded bytes.

• mode (str or ImageReadMode, optional) – Desired color mode of the output image. Can be one of "UNCHANGED", "GRAY", "GRAY_ALPHA", "RGB", or "RGB_ALPHA". Default is "RGB".

• output_dtype (torch.dtype or "auto", optional) – desired dtype of the output image tensor. Accepted values are torch.uint8 (default), torch.uint16, and "auto". Formats that can carry more than 8 bits per channel (PNG, AVIF, HEIC) preserve that precision with torch.uint16 and "auto". See the format-specific decoders for details.

Returns:

The decoded image, of shape [N]CHW.

Return type:

torch.Tensor

Examples using decode_image:

Decoding images

Decoding images

Encoding images

Encoding images

Migrating from TorchVision to TorchCodec

Migrating from TorchVision to TorchCodec