[torchvision] transforms.v2, transforms.v2.functional, 그리고 kernel

torchvision.transforms는 PyTorch에서 제공하는 이미지 preprocessing 및 data augmentation을 위한 module.

 

이 모듈은 현재 v2 서브모듈의 사용을 권함:

• v2 transforms는 image뿐만 아니라
• bounding boxes, masks, videos도 변환할 수 있어 더 많은 작업을 지원

 

v2 서브모듈은 크게 다음과 같은 3가지 형태 (kernel을 제외하고 2가지로 애기하기도 함)로 구성됨 .

• v2:
  • 고수준 추상화의 transform 클래스 및 Pipeline 구성을 위한 클래스 제공.
  • torch.nn.Module 클래스 처럼 동작: callable 객체를 통해 작업. 
• v2.functional:
  • 함수형 trnasform 을 지원 (사용자가 호출시 argument를 직접 지정).
• kernel:
  • 별도의 독립적인 구성 요소는 아님. 
  • v2.functional 모듈의 내부 저수준 함수(앞서의 v2와 v2.functional의 내부에서 사용되는 함수들)를 가리킴.
  • v2.functional namespace에 속해 있음.

이러한 이유로 torchvision 0.15가 공개된 2023년 3월부터 기존 torchvision.transforms 대신 transforms.v2 사용이 공식적으로 권장되기 시작했으며, 이후의 기능 추가와 API 개선, 새로운 변환들의 도입 역시 v2를 중심으로 이루어지고 있어 현재는 v2가 사실상의 표준 transform API로 자리 잡음.

Transform API에 대한 보다 자세한 글: 2025.01.12 - [Python] - [PyTorch] torchvision.transforms 사용법 - transforms란?

[PyTorch] torchvision.transforms 사용법 - transforms란?

---

1. torchvision.transforms.v2

torchvision.transforms.v2는 PyTorch의 최신 이미지 변환(transform) API임.

• Image Classification 뿐 아니라
• Object Detection, Segmentation, Video 등의
• 보다 다양한 vision task를 위한 지원이 풍부함.

특징:

• tv_tensor.Image, tv_tensor.BoundingBoxes, tv_tensor.Mask, tvb_tensor.Video 등 다양한 타입을 지원
• 이들 타입들로 구성된 복합 입력(list 혹은 dict)를 동시에 변환 처리하도록 설계됨.
  • 예를 들어, { "img": Image, "bbox": BoundingBoxes, "mask": Mask }와 같은
  • 복합 구조를 그대로 받아서, 각 타입에 맞는 변환을 자동으로 적용
• 기존(v1이라고 칭해지며, torchvision.transforms 모듈로 지원) 구현물 대비 더 빠르고 다양한 기능 제공함.
• 앞으로의 기능 추가 및 개선은 v2에서만 이루어질 예정임.

---

2. torchvision.transforms.v2.functional

torchvision.transforms.v2.functional은

• trochvision.transforms.v2의 transform 클래스들이 제공하는 변환 기능을
• 객체를 만들지 않고, 함수형 API로 직접 사용하도록 지원하는 모듈임.

특징:

• 각 변환을 객체 생성없이 함수 호출로 직접 적용할 수 있음
  • 예시: F.resize(img, )처럼 함수로 바로 사용.
• 단, 랜덤 변환의 경우,
  • 클래스(transform) 버전은 내부적으로 파라미터를 샘플링하지만,
  • functional 버전은 파라미터를 직접 지정해야 함.
  • transform 클래스 객체의 get_param 메서드와 함께 사용될 수 있음.
• TorchScript(JIT) 등에서 함수형이 더 호환성이 좋음.
  • 현재 TrochScript로 v2의 기능을 사용하려면 v2.functional로 사용해야함.
  • v2 클래스의 경우에, 이전 v1 클래스를 이용한다는 튜토리얼 언급이 있음.

https://docs.pytorch.org/vision/main/transforms.html#torchscript-support

Transforming and augmenting images — Torchvision main documentation

---

3. torchvision에서 말하는 kernel

torchvision에서 말하는 kernel은 transforms 의 기능을 구현한 가장 저수준 구현체를 가리킴.

 

이는 실제 데이터 타입별로 동작하는 내부 함수임.

 

특징:

• 예를 들어, resize, crop, permute_channels 등 변환의 핵심 연산을 담당하는 함수들을 kernel이라고 부름.
• functional 함수들은 내부적으로 입력 타입에 따라 적합한 kernel을 호출해 동작함.
• 공식 문서에서는 “kernel”을 저수준 함수로 지칭하며, 주로 bounding box나 mask 등 특수 타입을 다룰 때 유용하게 사용됨
• 대부분의 사용자는 functional까지만 사용하고, kernel은 커스텀 타입이나 고급 사용에만 다루기 때문에 documentation 이 없음.

kernel은 문서화가 되어 있지 않으며, 다음 source를 통해 확인하라고 튜토리얼에서 애기하고 있음.

https://github.com/pytorch/vision/blob/main/torchvision/transforms/v2/functional/__init__.py

vision/torchvision/transforms/v2/functional/__init__.py at main · pytorch/vision

---

같이보면 좋은 자료

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

Transforming and augmenting images — Torchvision main documentation

2025.06.16 - [Python] - [PyTorch] torchvision.transforms.v2 - Summary (작성중)

[PyTorch] torchvision.transforms.v2 - Summary (작성중)