# Processeurs d'images

Les processeurs d’images convertissent les images en valeurs de pixels, des tenseurs qui représentent les couleurs et la taille des images. Les valeurs de pixels constituent les entrées d’un modèle de vision. Pour s’assurer qu’un modèle pré-entraîné reçoit la bonne entrée, un processeur d’images peut effectuer les opérations suivantes afin de garantir qu’une image est exactement identique aux images sur lesquelles le modèle a été pré-entraîné.

- centrer-cadrer ou redimensionner une image
- normaliser ou rééchelonner les valeurs des pixels

Utilisez [from_pretrained()](/docs/transformers/v5.23.0/fr/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) pour charger la configuration d'un processeur d'images (taille de l'image, normalisation et mise à l'échelle, etc.) à partir d'un modèle de vision sur le [Hub](https://hf.co) Hugging Face ou d'un répertoire local. La configuration de chaque modèle pré-entraîné est enregistrée dans un fichier [preprocessor_config.json](https://huggingface.co/google/vit-base-patch16-224/blob/main/preprocessor_config.json).

Lorsqu'un processeur d'images fait partie d'un processeur multimodal, sa configuration est imbriquée dans `processor_config.json`. Consultez [Enregistrer et charger un processeur](./processors#save-and-load-a-processor) pour plus de détails.

```py
from transformers import AutoImageProcessor

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

Passez une image au processeur d'images pour la transformer en valeurs de pixels, et définissez `return_tensors="pt"` pour retourner des tenseurs PyTorch. N'hésitez pas à afficher les entrées pour voir à quoi ressemble l'image en tant que tenseur.

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

Ce guide présente la classe de processeur d'images et explique comment prétraiter les images pour les modèles de vision.

## Classes de processeur d'images

Les processeurs d’images utilisent une architecture basée sur des backends avec deux backends :

- [TorchvisionBackend](/docs/transformers/v5.23.0/fr/main_classes/image_processor#transformers.TorchvisionBackend) — l’implémentation par défaut basée sur [torchvision](https://pytorch.org/vision/stable/index.html). Accélérée par GPU et jusqu’à 33 fois plus rapide que le backend PIL pour des lots d’entrées [torch.Tensor](https://pytorch.org/docs/stable/tensors.html). Tous les modèles prennent en charge ce backend ; les modèles plus récents n’en prennent en charge que celui-ci.
- [PilBackend](/docs/transformers/v5.23.0/fr/main_classes/image_processor#transformers.PilBackend) — l’alternative PIL/NumPy. Portable et limitée au CPU. Disponible uniquement pour les anciens modèles, où il est utile de reproduire les sorties numériques exactes de l’implémentation d’origine.

Le backend actif d'un processeur chargé peut être inspecté via son attribut `backend` (par exemple, `processor.backend == "torchvision"`). Chaque processeur d'images est une sous-classe de [ImageProcessingMixin](/docs/transformers/v5.23.0/fr/internal/image_processing_utils#transformers.ImageProcessingMixin), qui fournit les méthodes [from_pretrained()](/docs/transformers/v5.23.0/fr/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) et [save_pretrained()](/docs/transformers/v5.23.0/fr/internal/image_processing_utils#transformers.ImageProcessingMixin.save_pretrained).

Il existe deux façons de charger un processeur d'images : avec [AutoImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoImageProcessor) ou directement depuis une classe spécifique à un modèle.

L'API [AutoClass](./model_doc/auto) fournit une méthode pratique pour charger un processeur d'images sans spécifier directement le modèle auquel ce processeur est associé.

Utilisez [from_pretrained()](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) avec l'argument `backend` pour sélectionner le backend. Lorsque `backend` est omis (par défaut), torchvision est choisi s'il est installé, sinon PIL est utilisé. Notez que `backend="pil"` n'est pris en charge que pour les anciens modèles ; les nouveaux modèles n'exposent que le backend torchvision.

Pour obtenir le prétraitement le plus proche de celui utilisé lors de l'entraînement d'un modèle, utilisez le backend spécifié dans sa documentation ou son code d'entraînement. Si le pipeline d'entraînement utilise PIL et que le modèle prend en charge les deux backends, passez `backend="pil"`. Le changement de backend peut modifier les valeurs des pixels redimensionnés, et les mises à jour de Pillow ou de torchvision peuvent également les modifier. Pour un prétraitement reproductible, maintenez les versions du backend et de la bibliothèque d'images fixes.

> [!NOTE]
> Un petit ensemble de modèles plus anciens (Chameleon, Flava, Idefics3, SmolVLM) utilise l'interpolation Lanczos. Leur backend par défaut dépend de votre version de torchvision. Avec torchvision > 0.27, Lanczos est pris en charge nativement et ces modèles utilisent torchvision par défaut. Les versions plus anciennes de torchvision basculent sur BICUBIC, de sorte que le backend par défaut est PIL afin de préserver les sorties d'origine. Passez explicitement `backend="torchvision"` pour outrepasser le défaut.

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

Chaque processeur d'image est associé à un modèle de vision préentraîné spécifique, et sa configuration contient la taille attendue par le modèle ainsi que ses paramètres de normalisation.

Chargez le processeur du backend torchvision directement depuis la classe spécifique au modèle.

```py
from transformers import ViTImageProcessor

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

Pour les modèles qui le prennent en charge, vous pouvez charger le backend PIL avec la classe suffixée par `Pil`. Cela est utile lorsque vous avez besoin d'une parité numérique exacte avec l'implémentation d'origine.

```py
from transformers import ViTImageProcessorPil

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

## Processeurs de backend Torchvision

[TorchvisionBackend](/docs/transformers/v5.23.0/fr/main_classes/image_processor#transformers.TorchvisionBackend) est le backend **par défaut**. Assurez-vous que [torchvision](https://pytorch.org/get-started/locally/#mac-installation) est installé, puis chargez-le avec `backend="torchvision"` (ou omettez simplement `backend`, car torchvision est sélectionné automatiquement lorsqu’il est disponible).

```py
from transformers import AutoImageProcessor

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

Contrôlez le dispositif sur lequel le traitement est effectué à l'aide de l'argument `device`. Par défaut, le traitement est effectué sur le même dispositif que l'entrée si les entrées sont des tenseurs, sinon il bascule sur le CPU. L'exemple ci-dessous exécute le traitement sur un accélérateur.

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

Benchmarks

Les benchmarks sont obtenus à partir d'une instance [AWS EC2 g5.2xlarge](https://aws.amazon.com/ec2/instance-types/g5/) équipée d'un GPU NVIDIA A10G Tensor Core.

  

  

  

  

## Résolution dynamique

La plupart des processeurs d’images redimensionnent chaque image vers une résolution fixe. La résolution dynamique permet à certains modèles de conserver le ratio d’aspect d’origine et de laisser la quantité de données prétraitées croître avec l’image, de sorte qu’une photo détaillée génère plus de patches qu’une petite icône et que le modèle consacre ses calculs là où il y a quelque chose à analyser.

La manière dont l'image est découpée dépend du modèle. Certains modèles découpent l'image en un nombre variable de patches de taille fixe, borné par des paramètres tels que `min_patches` et `max_patches`. D'autres modèles redimensionnent l'image à la résolution qui lui convient le mieux, choisie dans une liste prédéfinie de rapports d'aspect ou dérivée d'un budget de pixels.

Reportez-vous à la page de documentation du modèle pour connaître ses paramètres, valeurs par défaut et formes de sortie.

## Prétraitement

Les modèles de vision de Transformers s'attendent à recevoir l'entrée sous forme de tenseurs PyTorch de valeurs de pixels. Un processeur d'images gère la conversion des images en valeurs de pixels, représentées par la taille du lot, le nombre de canaux, la hauteur et la largeur. Pour ce faire, l'image est redimensionnée (recadrée au centre) et les valeurs de pixels sont normalisées et rééchelonnées aux valeurs attendues par le modèle.

Le prétraitement d'images ne se confond pas avec l'*augmentation d'images*. L'augmentation d'images consiste à apporter des modifications (luminosité, couleurs, rotation, etc.) à une image dans le but de créer de nouveaux exemples d'entraînement ou de prévenir le surapprentissage. Le prétraitement d'images, quant à lui, modifie une image afin de la mettre en conformité avec le format d'entrée attendu par un modèle pré-entraîné.

En général, les images sont augmentées (pour améliorer les performances) puis prétraitées avant d’être transmises à un modèle. Vous pouvez utiliser n’importe quelle bibliothèque ([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)) pour l’augmentation et un processeur d’images pour le prétraitement.

Ce guide utilise le module [transforms](https://pytorch.org/vision/stable/transforms.html) de torchvision pour l'augmentation.

Commencez par charger un petit échantillon du jeu de données [food101](https://hf.co/datasets/food101).

```py
from datasets import load_dataset

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

À partir du module [transforms](https://pytorch.org/vision/stable/transforms.html), utilisez l'API [Compose](https://pytorch.org/vision/master/generated/torchvision.transforms.Compose.html) pour enchaîner [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) et [ColorJitter](https://pytorch.org/vision/main/generated/torchvision.transforms.ColorJitter.html). Ces transformations effectuent un recadrage et un redimensionnement aléatoires d'une image, ainsi qu'un ajustement aléatoire de ses couleurs.

La taille de l’image vers laquelle effectuer un recadrage aléatoire peut être récupérée depuis le processeur d’images. Pour certains modèles, une hauteur et une largeur exactes sont attendues, tandis que pour d’autres, seule la `shortest_edge` est requise.

```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)])
```

Appliquez les transformations aux images et convertissez-les au format RGB. Puis, transmettez les images augmentées au processeur d'images pour obtenir les valeurs de pixels.

Le paramètre `do_resize` est défini sur `False` car les images ont déjà été redimensionnées à l'étape d'augmentation par [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html). Si vous n'augmentez pas les images, le processeur d'images redimensionne et normalise automatiquement les images à l'aide des valeurs `image_mean` et `image_std`. Ces valeurs sont trouvées dans le fichier de configuration du préprocesseur.

```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
```

Appliquez la fonction d'augmentation et de prétraitement combinée à l'ensemble du jeu de données à la volée avec [set_transform](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset.set_transform).

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

Convertissez les valeurs de pixels en image pour voir comment l'image a été augmentée et prétraitée.

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

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

  
    
    avant
  
  
    
    après
  

Pour d'autres tâches de vision comme la détection d'objets ou la segmentation, le processeur d'images inclut des méthodes de post-traitement pour convertir la sortie brute d'un modèle en prédictions significatives, telles que des boîtes englobantes ou des cartes de segmentation.

### Remplissage

Certains modèles, comme [DETR](./model_doc/detr), appliquent une [scale augmentation](https://paperswithcode.com/method/image-scale-augmentation) pendant l’entraînement, ce qui peut entraîner des images de tailles différentes au sein d’un même lot. Les images de tailles différentes ne peuvent pas être regroupées dans un même lot.

Pour corriger cela, remplacez les images par le jeton de bourrage spécial `0`. Utilisez la méthode [pad](https://github.com/huggingface/transformers/blob/9578c2597e2d88b6f0b304b5a05864fd613ddcc1/src/transformers/models/detr/image_processing_detr.py#L1151) pour bourrer les images et définissez une fonction de collation personnalisée pour les regrouper en lot.

```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
```

