# 画像プロセッサ

Image processorは、画像をピクセル値に変換します。ピクセル値は、画像の色とサイズを表すテンソルであり、ビジョンモデルへの入力となります。事前学習済みモデルが正しい入力を確実に受け取れるようにするため、Image processorは、画像がモデルの事前学習に使用された画像と完全に一致するよう、以下の操作を実行できます。

- 画像を中央クロップまたはリサイズする
- ピクセル値を正規化または再スケーリング

[from_pretrained()](/docs/transformers/main/ja/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) を使用して、Hugging Face [Hub](https://hf.co) またはローカルディレクトリ上のビジョンモデルから、イメージプロセッサの設定（イメージサイズ、正規化やリスケールを行うかどうかなど）を読み込みます。各事前学習済みモデルの設定は、[preprocessor_config.json](https://huggingface.co/google/vit-base-patch16-224/blob/main/preprocessor_config.json) ファイルに保存されています。

画像プロセッサがマルチモーダルプロセッサの一部である場合、その設定は代わりに`processor_config.json`にネストされます。詳細については、[プロセッサの保存と読み込み](./processors#save-and-load-a-processor)を参照してください。

```py
from transformers import AutoImageProcessor

image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")
```

画像を画像プロセッサに渡してピクセル値に変換し、`return_tensors="pt"` を設定して PyTorch テンソルを返します。テンソルとして画像がどのように見えるかを確認するために、入力を出力しても構いません。

```py
from PIL import Image
import requests

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/image_processor_example.png"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
inputs = image_processor(image, return_tensors="pt")
```

このガイドでは、画像プロセッサクラスと、ビジョンモデル用の画像の前処理方法について説明します。

## 画像プロセッサクラス

Image processor は、2 つのバックエンドを持つバックエンドベースのアーキテクチャを使用します:

- [TorchvisionBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.TorchvisionBackend) — デフォルトの [torchvision ベース](https://pytorch.org/vision/stable/index.html) の実装です。GPU 加速に対応しており、[torch.Tensor](https://pytorch.org/docs/stable/tensors.html) 入力のバッチ処理では PIL バックエンドと比較して最大 33 倍高速です。すべてのモデルがこのバックエンドをサポートしています。新しいモデルは、このバックエンドのみをサポートします。
- [PilBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.PilBackend) — PIL/NumPy による代替実装。ポータブルで CPU のみ対応です。元の実装と完全に一致する数値出力を再現する必要がある場合、古いモデルでのみ利用可能です。

読み込まれたプロセッサのアクティブなバックエンドは、その`backend`属性（例: `processor.backend == "torchvision"`）で確認できます。各イメージプロセッサは[ImageProcessingMixin](/docs/transformers/main/ja/internal/image_processing_utils#transformers.ImageProcessingMixin)をサブクラス化しており、[from_pretrained()](/docs/transformers/main/ja/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained)および[save_pretrained()](/docs/transformers/main/ja/internal/image_processing_utils#transformers.ImageProcessingMixin.save_pretrained)メソッドが提供されています。

画像プロセッサを読み込む方法には2つあります。[AutoImageProcessor](/docs/transformers/main/ja/model_doc/auto#transformers.AutoImageProcessor)を使用する方法と、モデル固有のクラスから直接読み込む方法です。

[AutoClass](./model_doc/auto) APIは、画像プロセッサに関連付けられているモデルを直接指定せずに、画像プロセッサを読み込むための便利な方法を提供します。

Use [from_pretrained()](/docs/transformers/main/ja/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) with the `backend` argument to select the backend. When `backend` is omitted (the default), torchvision is picked when it is installed and PIL is used otherwise. Note that `backend="pil"` is only supported for older models; newer models only expose the torchvision backend.

モデルの学習時の前処理に最も近いものを実現するには、そのモデルのドキュメントや学習コードで指定されているバックエンドを使用してください。学習パイプラインで PIL が使用されており、モデルが両方のバックエンドをサポートしている場合は、`backend="pil"` を渡してください。バックエンドを切り替えるとリサイズ後のピクセル値が変わる可能性があり、Pillow や torchvision の更新によっても値が変わる可能性があります。再現可能な前処理を実現するには、バックエンドと画像ライブラリのバージョンを固定してください。

> [!NOTE]
> 一部の旧モデル（Chameleon、Flava、Idefics3、SmolVLM）は Lanczos 補間を使用しています。これらのモデルのデフォルトのバックエンドは、お使いの torchvision のバージョンによって異なります。torchvision > 0.27 の場合、Lanczos がネイティブでサポートされるため、これらのモデルは torchvision をデフォルトとして使用します。古い torchvision のバージョンでは BICUBIC にフォールバックするため、元の出力を維持するためにデフォルトは PIL になります。デフォルトを上書きするには、`backend="torchvision"` を明示的に指定してください。

```py
from transformers import AutoImageProcessor

# Default: picks torchvision if available, otherwise pil
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")

# Explicitly request the torchvision backend
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="torchvision")

# Explicitly request the PIL backend (only for models that support it)
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="pil")
```

各 image processor は特定の事前学習済みビジョンモデルに関連付けられており、その設定には、モデルが想定するサイズと正規化パラメータが含まれています。

モデル固有のクラスから、torchvision バックエンドのプロセッサを直接読み込みます。

```py
from transformers import ViTImageProcessor

image_processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")
```

対応するモデルでは、`Pil`サフィックス付きのクラスを指定してPILバックエンドを読み込むことができます。これは、元の実装と数値的に完全に一致させる必要がある場合に便利です。

```py
from transformers import ViTImageProcessorPil

image_processor = ViTImageProcessorPil.from_pretrained("google/vit-base-patch16-224")
```

## Torchvision バックエンドのプロセッサ

[TorchvisionBackend](/docs/transformers/main/ja/main_classes/image_processor#transformers.TorchvisionBackend) は **デフォルト**のバックエンドです。[torchvision](https://pytorch.org/get-started/locally/#mac-installation) がインストールされていることを確認し、`backend="torchvision"` を指定して読み込みます（`backend` を省略しても構いません。利用可能な場合、torchvision は自動的に選択されるためです）。

```py
from transformers import AutoImageProcessor

processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="torchvision")
```

`device` 引数で、処理を実行するデバイスを制御できます。入力がテンソルの場合、デフォルトでは入力と同じデバイスで処理が実行され、それ以外の場合は CPU にフォールバックします。以下の例では、アクセラレーター上で処理を実行しています。

```py
import torch
from torchvision.io import read_image
from transformers import DetrImageProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

images = read_image("image.jpg")
processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
images_processed = processor(images, return_tensors="pt", device=device)
```

ベンチマーク

ベンチマークは、NVIDIA A10G Tensor Core GPUを搭載した[AWS EC2 g5.2xlarge](https://aws.amazon.com/ec2/instance-types/g5/)インスタンスから取得されています。

  

  

  

  

## 動的解像度

ほとんどの画像プロセッサは、すべての画像を1つの固定解像度にリサイズします。動的解像度により、一部のモデルは元の縦横比を維持でき、前処理データの量が画像の大きさに応じて増加します。これにより、詳細な写真には小さなアイコンよりも多くのパッチが割り当てられ、モデルは注目すべき内容がある箇所に計算リソースを集中させることができます。

画像の分割方法はモデルによって異なります。一部のモデルでは、`min_patches`や`max_patches`などのパラメータで範囲が定められた可変数の固定サイズのパッチに画像をクロップします。その他のモデルでは、あらかじめ定義されたアスペクト比のリストから選択するか、ピクセル予算から導出される解像度に画像をリサイズします。

パラメータ、デフォルト値、出力の形状については、該当するモデルのドキュメントページを参照してください。

## 前処理

Transformers のビジョンモデルは、ピクセル値の PyTorch テンソルを入力として期待します。画像プロセッサは、画像をピクセル値への変換を担当します。ピクセル値は、バッチサイズ、チャネル数、高さ、幅で表されます。この変換を実現するために、画像はリサイズ（中央クロップ）され、ピクセル値はモデルが期待する値に合わせて正規化および再スケーリングされます。

画像の前処理は、*画像拡張*とは異なります。画像拡張は、新しい学習例を作成したり、過学習を防いだりするために、画像に対して変更（明るさ、色、回転など）を加えます。一方、画像の前処理は、事前学習済みモデルが期待する入力形式に合わせることを目的として、画像に対して変更を加えます。

通常、画像はパフォーマンスを向上させるために拡張（データ拡張）され、その後、モデルに渡される前に前処理されます。拡張には任意のライブラリ（[Albumentations](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification_albumentations.ipynb)、[Kornia](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification_kornia.ipynb)）を使用でき、前処理には画像プロセッサを使用します。

このガイドでは、拡張のために torchvision の [transforms](https://pytorch.org/vision/stable/transforms.html) モジュールを使用します。

[food101](https://hf.co/datasets/food101) データセットの小さなサンプルを読み込むことから始めます。

```py
from datasets import load_dataset

dataset = load_dataset("ethz/food101", split="train[:100]")
```

[transforms](https://pytorch.org/vision/stable/transforms.html) モジュールから [Compose](https://pytorch.org/vision/master/generated/torchvision.transforms.Compose.html) API を使用して、[RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) と [ColorJitter](https://pytorch.org/vision/main/generated/torchvision.transforms.ColorJitter.html) をチェーンします。これらのトランスフォームは、画像をランダムにクロップしてリサイズし、画像の色をランダムに調整します。

画像プロセッサから、ランダムにクロップする画像サイズを取得できます。モデルによっては正確な高さおよび幅が期待されますが、他のモデルでは`shortest_edge`のみで十分です。

```py
from torchvision.transforms import RandomResizedCrop, ColorJitter, Compose

size = (
    image_processor.size["shortest_edge"]
    if "shortest_edge" in image_processor.size
    else (image_processor.size["height"], image_processor.size["width"])
)
_transforms = Compose([RandomResizedCrop(size), ColorJitter(brightness=0.5, hue=0.5)])
```

変換を画像に適用し、RGB形式に変換します。次に、拡張された画像をimage processorに渡し、ピクセル値を返します。

`do_resize` パラメータは `False` に設定されています。これは、画像が拡張ステップで [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) によってすでにリサイズされているためです。画像を拡張しない場合、画像プロセッサは `image_mean` と `image_std` の値を使用して、画像を自動的にリサイズし正規化します。これらの値は、プリプロセッサの設定ファイルに記載されています。

```py
def transforms(examples):
    images = [_transforms(img.convert("RGB")) for img in examples["image"]]
    examples["pixel_values"] = image_processor(images, do_resize=False, return_tensors="pt")["pixel_values"]
    return examples
```

[set_transform](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset.set_transform) を使用して、拡張と前処理を組み合わせる関数を、データセット全体に対してオンザフライで適用します。

```py
dataset.set_transform(transforms)
```

ピクセル値を画像に戻して、画像がどのように拡張・前処理されたかを確認します。

```py
import numpy as np
import matplotlib.pyplot as plt

img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
```

  
    
    前
  
  
    
    後
  

オブジェクト検出やセグメンテーションなどの他のビジョンタスクでは、image processorには、モデルの生出力をバウンディングボックスやセグメンテーションマップといった意味のある予測に変換する後処理メソッドが含まれています。

### パディング

[DETR](./model_doc/detr)などの一部のモデルでは、[scale augmentation](https://paperswithcode.com/method/image-scale-augmentation)をトレーニング中に適用するため、バッチ内の画像のサイズが異なる場合があります。サイズが異なる画像は、まとめてバッチ化できません。

この問題を修正するには、特殊なパディングトークン `0` で画像をパディングします。[pad](https://github.com/huggingface/transformers/blob/9578c2597e2d88b6f0b304b5a05864fd613ddcc1/src/transformers/models/detr/image_processing_detr.py#L1151) メソッドを使用して画像をパディングし、それらをバッチ化するカスタム collate 関数を定義します。

```py
def collate_fn(batch):
    pixel_values = [item["pixel_values"] for item in batch]
    encoding = image_processor.pad(pixel_values, return_tensors="pt")
    labels = [item["labels"] for item in batch]
    batch = {}
    batch["pixel_values"] = encoding["pixel_values"]
    batch["pixel_mask"] = encoding["pixel_mask"]
    batch["labels"] = labels
    return batch
```