[torchvision] image로부터 torch.tensor 객체 얻기

0. torchvision.io.read_image

 

torchvision.io.read_image는
현재 Obsolete 상태로 유지되고 있으며,
파일 경로나 raw byte 데이터 모두를 처리할 수 있는 decode_image가
공식적으로 권장되는 이미지 로딩 API임.

obsolete

• 이미 구식이며 더 이상 권장되지 않음
• 기능적으로는 남아 있을 수 있으나, 유지·확장 대상이 아님
• 사실상 역사적/호환성 목적으로만 존재

프로그래밍의 특정 기능의 사용가능 여부 상태를 나타내는 용어는 다음과 같음:

Active => Deprecated => Obsolete => Removed

torchvision.io.read_image 함수는 이미지 파일 경로를 입력으로 받아, 파일을 읽고 디코딩까지 수행하여 PyTorch Tensor 객체로 반환하는 함수 였음.

• torchvision에서 이미지 파일을 직접 로딩하여 PyTorch Tensor를 얻는 가장 일반적인 방법으로 사용되며,
• PIL을 거치지 않고 네이티브 Tensor 기반 이미지 로딩을 제공한다.

official documentation url: https://docs.pytorch.org/vision/main/generated/torchvision.io.read_image.html

read_image — Torchvision main documentation

---

1. torchvision.io.decode_image

torchvision.io.decode_image 함수는 이미지 파일(경로 또는 raw 바이트 데이터)을 PyTorch 텐서로 디코딩하는 함수.

• torchvision에서 실제 이미지를 로딩하여 PyTorch Tensor 객체를 얻는 데 사용됨.
• 다양한 이미지 포맷을 지원
• 이미지를 바로 텐서로 변환해 딥러닝 모델에 사용할 수 있음.

official documentation url: https://docs.pytorch.org/vision/main/generated/torchvision.io.decode_image.html

decode_image — Torchvision main documentation

gist: https://gist.github.com/dsaint31x/db784cb64f539b33e38ee5b2a9feab2d

dl_torchvision_decode_image.ipynb

---

2. 주요 특징

• 입력:
  • 이미지 파일의 경로(str, pathlib.Path) 또는
  • raw 바이트 데이터가 담긴 1차원 uint8 텐서
• 출력:
  • [C, H, W] 형태의
  • PyTorch 텐서
  • 대부분 uint8 (16비트 PNG는 uint16)
• Parameters
  • mode:
    • 읽어올 이미지의 모드 지정(RGB 등)
    • 기본값: UNCHANGED
  • apply_exif_orientation:
    • JPEG, PNG에서 EXIF 방향 정보 적용 여부
    • 기본값: False

성능 에서 PIL의 Image 객체보다 빠르며,
대용량 데이터셋 처리나 DataLoader에서 여러 worker를 사용할 때 유리함

---

3. 지원 이미지 포맷 및 설명

기본적으로 자동으로 포맷을 감지하여 적절한 디코더를 사용함.

• 'JPEG' : CUDA GPU에서 디코딩 지원한다는 장점 가짐.
• 'PNG' : 16비트 PNG는 uint16 텐서로 반환
• 'GIF' : 단일 프레임은 3D, 애니메이션은 4D 텐서로 반환
• 'WEBP' : 구글에서 개발한 고효율 이미지 포맷. RGB 또는 RGBA 텐서로 반환

torchvision-extra-decoders 패키지 설치할 경우, 'AVIF'와 'HEIC' (iOS 용) 도 지원함.

pip install torchvision-extra-decoders

https://docs.pytorch.org/vision/main/generated/torchvision.io.decode_avif.html#torchvision.io.decode_avif

decode_avif — Torchvision main documentation

https://github.com/pytorch-labs/torchvision-extra-decoders/

GitHub - pytorch-labs/torchvision-extra-decoders: An extension of `torchvision` for decoding AVIF and HEIC images.

 

다양한 image encoding format에 대해선 다음을 참고: https://dsaint31.tistory.com/402

[DIP] Image Format (summary)

---

4. Example0: 기본 사용법

import torch
from torchvision.io import decode_image

# ==============================================
# 이미지 파일 경로로 읽기
img_tensor = decode_image("image.jpg")
# decode_image의 출력은 보통 uint8이며 값 범위는 [0, 255].
print(img_tensor.dtype, img_tensor.shape, img_tensor.min().item(), img_tensor.max().item())

# ==============================================
# 이미지 바이트 데이터로 읽기
with open("image.jpg", "rb") as f:
    img_bytes = f.read()

img_tensor = decode_image(
    torch.frombuffer(
        img_bytes,
        dtype=torch.uint8,
    )
)
# 역시 uint8, 범위 [0, 255]
print(img_tensor.dtype, img_tensor.shape, img_tensor.min().item(), img_tensor.max().item())

 

BloodImage_00107.jpg

0.02MB

---

5. Example: ImageFolder에서 사용하기

ImageFolder에서 다음과 같이  사용할 경우, PIL의 이미지 객체를 거치지 않고 torch의 텐서로 이미지를 곧바로 로딩할 수 있음:

import torch
from torchvision.datasets import ImageFolder
from torchvision.io import decode_image
from torchvision.transforms import v2

# 1) loader: 파일 경로 -> Tensor[C,H,W] (uint8, [0,255])
def tensor_loader(path: str) -> torch.Tensor:
    return decode_image(path)  # read_image는 문서상 OBSOLETE

# 2) v2 파이프라인(권장): dtype/범위 변환은 transform에서 처리
transform = v2.Compose([
    v2.ToDtype(torch.float32, scale=True),  # uint8 [0,255] -> float32 [0,1]
    # 필요하면 여기서 Resize/Normalize 등 추가
    # v2.Resize((224, 224)),
    # v2.Normalize(mean=..., std=...),
])

dataset = ImageFolder(
    root="data",
    loader=tensor_loader,
    transform=transform,
    target_transform=None,
)

 

과거 방식

import torch
import torchvision.io as io

def tensor_loader(path: str) -> torch.Tensor:
    # uint8 Tensor [C,H,W], range [0,255]
    return io.read_image(path)
    # float32 Tensor [C,H,W], range [0,1]
    return img.to(torch.float32) / 255.0

dataset = ImageFolder(
    root="data",
    loader=tensor_loader,
    transform=None,   # 이미 Tensor이므로 ToTensor 불필요
)

 

2025.06.17 - [Python] - torchvision.datasets.ImageFolder 사용하기.

torchvision.datasets.ImageFolder 사용하기.

---

같이 보면 좋은 자료

https://docs.pytorch.org/vision/main/io.html

Decoding / Encoding images and videos — Torchvision main documentation