[DEPRECATED] Decoding and Encoding images

.. currentmodule:: torchvision.io

.. warning::

The image decoding and encoding capabilities of TorchVision are deprecated
since torchvision 0.29 and will be removed in a future release. They are
superseded by the more complete decoders and encoders of TorchCodec (from
torchcodec 0.16). Please see `this migration guide
<https://meta-pytorch.org/torchcodec/0.16/generated_examples/migration/torchvision_migration.html>`__
on how to migrate your code.

The :mod:torchvision.io module provides utilities for decoding and encoding images. For videos and audio, please use TorchCodec <https://github.com/meta-pytorch/torchcodec>__.

Image Decoding

Torchvision currently supports decoding JPEG, PNG, WEBP, GIF, AVIF, and HEIC images. JPEG decoding can also be done on CUDA GPUs.

The main entry point is the :func:~torchvision.io.decode_image function, which you can use as an alternative to PIL.Image.open(). It will decode images straight into image Tensors, thus saving you the conversion and allowing you to run transforms/preproc natively on tensors.

.. code::

from torchvision.io import decode_image

img = decode_image("path_to_image", mode="RGB")
img.dtype  # torch.uint8

# Or
raw_encoded_bytes = ...  # read encoded bytes from your file system
img = decode_image(raw_encoded_bytes, mode="RGB")

:func:~torchvision.io.decode_image will automatically detect the image format, and call the corresponding decoder (except for HEIC and AVIF images, see details in :func:~torchvision.io.decode_avif and :func:~torchvision.io.decode_heic). You can also use the lower-level format-specific decoders which can be more powerful, e.g. if you want to encode/decode JPEGs on CUDA.

.. autosummary:: :toctree: generated/ :template: function.rst

decode_image
decode_jpeg
decode_png
decode_webp
decode_avif
decode_heic
decode_gif

.. autosummary:: :toctree: generated/ :template: class.rst

ImageReadMode

Obsolete decoding function:

.. autosummary:: :toctree: generated/ :template: function.rst

read_image

Image Encoding

For encoding, JPEG (cpu and CUDA) and PNG are supported.

.. autosummary:: :toctree: generated/ :template: function.rst

encode_jpeg
write_jpeg
encode_png
write_png

IO operations

.. autosummary:: :toctree: generated/ :template: function.rst

read_file
write_file