解碼 / 編碼圖片與影片

torchvision.io 模組提供了用於解碼和編碼圖片與影片的工具。

圖片解碼

Torchvision 目前支援解碼 JPEG、PNG、WEBP、GIF、AVIF 和 HEIC 圖片。JPEG 解碼也可以在 CUDA GPU 上進行。

主要的進入點是 decode_image() 函數，您可以將其用作 PIL.Image.open() 的替代方案。它會將圖片直接解碼到圖片 Tensor 中，從而節省您的轉換時間，並允許您在本機於 Tensor 上執行轉換/預處理。

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")

decode_image() 將自動檢測圖片格式，並呼叫相應的解碼器（除了 HEIC 和 AVIF 圖片，詳情請參閱 decode_avif() 和 decode_heic()）。您也可以使用更低階的格式特定解碼器，它們可能更強大，例如，如果您想在 CUDA 上編碼/解碼 JPEG。

decode_image(input[, mode, ...])	從路徑或原始編碼位元組將圖片解碼為 uint8 tensor。
decode_jpeg(input[, mode, device, ...])	在 CPU 或 CUDA 上將 JPEG 圖片解碼為 3D RGB 或灰階 Tensor。
encode_png(input[, compression_level])	採用 CHW 佈局的輸入 tensor，並傳回包含其對應 PNG 檔案內容的緩衝區。
decode_webp(input[, mode])	將 WEBP 圖片解碼為 3 維 RGB[A] Tensor。
decode_avif(input[, mode])	將 AVIF 影像解碼為 3 維 RGB[A] 張量。
decode_heic(input[, mode])	將 HEIC 影像解碼為 3 維 RGB[A] 張量。
decode_gif(input)	將 GIF 影像解碼為 3 或 4 維 RGB 張量。

ImageReadMode(value)

允許在解碼時自動轉換為 RGB、RGBA 等。

已過時的解碼函式

read_image(path[, mode, apply_exif_orientation])

[已過時] 請改用 decode_image()。

影像編碼

在編碼方面，支援 JPEG (CPU 和 CUDA) 和 PNG。

encode_jpeg(input[, quality])	在 CPU 或 CUDA 上將 RGB 張量編碼為原始編碼的 jpeg 位元組。
write_jpeg(input, filename[, quality])	接受 CHW 佈局的輸入張量，並將其儲存為 JPEG 檔案。
encode_png(input[, compression_level])	採用 CHW 佈局的輸入 tensor，並傳回包含其對應 PNG 檔案內容的緩衝區。
write_png(input, filename[, compression_level])	接受 CHW 佈局的輸入張量（如果是灰階影像，則為 HW），並將其儲存為 PNG 檔案。

IO 操作

read_file(path)	將檔案的位元組內容以 uint8 1D 張量形式傳回。
write_file(filename, data)	將 uint8 1D 張量的內容寫入檔案。

影片

警告

Torchvision 透過以下列出的不同 API 支援影片解碼，其中一些 API 仍處於 BETA 階段。 在不久的將來，我們打算將 PyTorch 的影片解碼功能集中在 torchcodec 專案中。 我們鼓勵您試用並分享您的意見，因為 torchvision 影片解碼器最終將被棄用。

read_video(filename[, start_pts, end_pts, ...])	從檔案讀取影片，傳回影片幀和音訊幀
read_video_timestamps(filename[, pts_unit])	列出影片幀的時間戳記。
write_video(filename, video_array, fps[, ...])	將 [T, H, W, C] 格式的 4d 張量寫入影片檔案。

細粒度影片 API

除了 read_video 函式之外，我們還提供了一個高效能的底層 API，與 read_video 函式相比，它可以進行更細粒度的控制。 它在完全支援 torchscript 的同時完成了這一切。

VideoReader(src[, stream, num_threads])

細粒度影片讀取 API。