.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated_examples/migration/torchvision_migration.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_examples_migration_torchvision_migration.py:


========================================
Migrating from TorchVision to TorchCodec
========================================

The image decoders and encoders of ``torchvision.io`` now live in torchcodec.
This is a short guide to porting your code over. Everything you could do with
``torchvision.io`` you can do with TorchCodec, usually with a very similar call.
And TorchCodec supports many more features. To learn more about the image
decoding and encoding features of TorchCodec, refer to the
:ref:`image decoding <sphx_glr_generated_examples_decoding_image_decoding.py>`
and
:ref:`image encoding <sphx_glr_generated_examples_encoding_image_encoding.py>`
tutorials.

TL;DR
-----

- ``decode_image(x)`` -> ``decode_image(x)``, but watch out for the
  :ref:`changed defaults <decoding_defaults>`
- ``decode_jpeg(x, device="cuda")`` -> ``decode_jpeg(x, device="cuda")``, same
  caveat
- ``read_file(path)`` -> not needed, pass ``path`` to the decoder
- ``encode_jpeg(img, quality)`` -> ``JpegEncoder(img).to_tensor(quality=...)``
- ``write_jpeg(img, path, quality)`` -> ``JpegEncoder(img).to_file(path, quality=...)``
- ``encode_png(img, level)`` -> ``PngEncoder(img).to_tensor(compression_level=...)``
- ``write_png(img, path, level)`` -> ``PngEncoder(img).to_file(path, compression_level=...)``
- ``write_file(path, encoded)`` -> not needed, use ``to_file``

The rest of this guide goes over these one by one.

.. GENERATED FROM PYTHON SOURCE LINES 40-42

A bit of boilerplate first: let's make up some encoded image bytes to play
with, by encoding a random image.

.. GENERATED FROM PYTHON SOURCE LINES 42-50

.. code-block:: Python

    import torch

    from torchcodec.encoders import JpegEncoder, PngEncoder

    raw_image_bytes = JpegEncoder(
        torch.randint(0, 256, (3, 256, 256), dtype=torch.uint8)
    ).to_tensor()








.. GENERATED FROM PYTHON SOURCE LINES 51-72

Decoding
--------

``torchvision.io.decode_image`` becomes
:func:`torchcodec.decoders.decode_image`. Both accept raw encoded bytes, a
tensor of encoded bytes, or a path to a file:

.. code-block:: python

    # Before
    from torchvision.io import decode_image
    image = decode_image("image.jpg")

    # After
    from torchcodec.decoders import decode_image
    image = decode_image("image.jpg")

The format-specific decoders map over one-to-one as well:
``decode_jpeg``, ``decode_png``, ``decode_webp``, ``decode_gif``, and
torchcodec adds ``decode_avif`` and ``decode_heic`` without needing the
separate ``torchvision-extra-decoders`` package.

.. GENERATED FROM PYTHON SOURCE LINES 72-78

.. code-block:: Python


    from torchcodec.decoders import decode_image

    image = decode_image(raw_image_bytes)
    print(f"{image.shape = }, {image.dtype = }")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    image.shape = torch.Size([3, 256, 256]), image.dtype = torch.uint8




.. GENERATED FROM PYTHON SOURCE LINES 79-91

``torchvision.io.read_file`` has no equivalent, and you don't need one: pass
the path (a ``str`` or a ``pathlib.Path``) straight to the decoder.

.. code-block:: python

    # Before
    from torchvision.io import decode_image, read_file
    image = decode_image(read_file("image.jpg"))

    # After
    from torchcodec.decoders import decode_image
    image = decode_image("image.jpg")

.. GENERATED FROM PYTHON SOURCE LINES 93-105

.. _decoding_defaults:

A few decoding defaults changed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``mode`` now defaults to ``"RGB"`` instead of ``"UNCHANGED"``. If you were
  relying on the source's own channel layout, pass ``mode="UNCHANGED"``.
- The output is always ``torch.uint8`` by default, even for 16-bit sources.
  To get torchvision's behaviour, where the dtype follows the source, pass
  ``output_dtype="auto"``.
- The ``apply_exif_orientation`` parameter is gone: EXIF orientation is
  always applied.

.. GENERATED FROM PYTHON SOURCE LINES 105-109

.. code-block:: Python


    print(f"{decode_image(raw_image_bytes, mode='GRAY').shape = }")
    print(f"{decode_image(raw_image_bytes, output_dtype=torch.uint16).dtype = }")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    decode_image(raw_image_bytes, mode='GRAY').shape = torch.Size([1, 256, 256])
    decode_image(raw_image_bytes, output_dtype=torch.uint16).dtype = torch.uint16




.. GENERATED FROM PYTHON SOURCE LINES 110-130

Encoding
--------

The encoding functions became classes: instantiate an encoder with the image,
then choose where the encoded bytes should go.

.. code-block:: python

    # Before
    from torchvision.io import encode_jpeg, write_jpeg
    encoded = encode_jpeg(image, quality=80)  # to a tensor
    write_jpeg(image, "image.jpg", quality=80)  # to a file

    # After
    from torchcodec.encoders import JpegEncoder
    encoded = JpegEncoder(image).to_tensor(quality=80)  # to a tensor
    JpegEncoder(image).to_file("image.jpg", quality=80)  # to a file

PNG works the same way with :class:`~torchcodec.encoders.PngEncoder` and
``compression_level``:

.. GENERATED FROM PYTHON SOURCE LINES 130-134

.. code-block:: Python


    print(f"{JpegEncoder(image).to_tensor(quality=80).shape = }")
    print(f"{PngEncoder(image).to_tensor(compression_level=6).shape = }")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    JpegEncoder(image).to_tensor(quality=80).shape = torch.Size([41099])
    PngEncoder(image).to_tensor(compression_level=6).shape = torch.Size([195692])




.. GENERATED FROM PYTHON SOURCE LINES 135-142

There is no batch equivalent to ``encode_jpeg(list_of_images)``: an encoder
takes a single image, so encode a batch with a plain Python loop. You're not
losing any speed:

.. code-block:: python

    encoded = [JpegEncoder(image).to_tensor() for image in images]

.. GENERATED FROM PYTHON SOURCE LINES 144-146

Encoders also support a third destination that torchvision didn't have: a
file-like object, i.e. anything with ``write`` and ``seek``.

.. GENERATED FROM PYTHON SOURCE LINES 146-151

.. code-block:: Python

    import io

    buffer = io.BytesIO()
    JpegEncoder(image).to_file_like(buffer)
    print(f"{len(buffer.getvalue()) = }")




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    len(buffer.getvalue()) = 37359





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.014 seconds)


.. _sphx_glr_download_generated_examples_migration_torchvision_migration.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: torchvision_migration.ipynb <torchvision_migration.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: torchvision_migration.py <torchvision_migration.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: torchvision_migration.zip <torchvision_migration.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_