# Processadores de imagem

Processadores de imagem convertem imagens em valores de pixels, tensores que representam as cores e o tamanho da imagem. Os valores de pixels são as entradas de um modelo de visão. Para garantir que um modelo pré-treinado receba a entrada correta, um processador de imagem pode executar as seguintes operações para assegurar que a imagem seja exatamente como as imagens nas quais o modelo foi pré-treinado.

- centralizar o recorte ou redimensionar uma imagem
- normalizar ou reescalar os valores de pixels

Use [from_pretrained()](/docs/transformers/main/pt/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) para carregar a configuração de um processador de imagens (tamanho da imagem, se normalizar e reescalar, etc.) a partir de um modelo de visão no [Hub](https://hf.co) do Hugging Face ou em um diretório local. A configuração de cada modelo pré-treinado é salva em um arquivo [preprocessor_config.json](https://huggingface.co/google/vit-base-patch16-224/blob/main/preprocessor_config.json).

Quando um processador de imagem faz parte de um processador multimodal, sua configuração fica aninhada em `processor_config.json`. Consulte [Salvar e carregar um processador](./processors#save-and-load-a-processor) para mais detalhes.

```py
from transformers import AutoImageProcessor

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

Passe uma imagem para o processador de imagens para transformá-la em valores de pixels e defina `return_tensors="pt"` para retornar tensores do PyTorch. Sinta-se à vontade para imprimir as entradas para ver como a imagem se parece como um tensor.

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

Este guia aborda a classe de processador de imagens e como pré-processar imagens para modelos de visão.

## Classes de processador de imagem

Processadores de imagem usam uma arquitetura baseada em backends, com dois backends:

- [TorchvisionBackend](/docs/transformers/main/pt/main_classes/image_processor#transformers.TorchvisionBackend) — a implementação padrão baseada em [torchvision](https://pytorch.org/vision/stable/index.html). Acelerada por GPU e até 33x mais rápida que o backend PIL para lotes de entradas [torch.Tensor](https://pytorch.org/docs/stable/tensors.html). Todos os modelos suportam este backend; os modelos mais recentes suportam apenas este.
- [PilBackend](/docs/transformers/main/pt/main_classes/image_processor#transformers.PilBackend) — a alternativa PIL/NumPy. Portátil e apenas para CPU. Disponível apenas para modelos mais antigos, onde é útil reproduzir as saídas numéricas exatas da implementação original.

O backend ativo em um processador carregado pode ser inspecionado por meio do seu atributo `backend` (por exemplo, `processor.backend == "torchvision"`). Cada processador de imagem é uma subclasse de [ImageProcessingMixin](/docs/transformers/main/pt/internal/image_processing_utils#transformers.ImageProcessingMixin), que fornece os métodos [from_pretrained()](/docs/transformers/main/pt/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) e [save_pretrained()](/docs/transformers/main/pt/internal/image_processing_utils#transformers.ImageProcessingMixin.save_pretrained).

Existem duas maneiras de carregar um processador de imagem: com [AutoImageProcessor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoImageProcessor) ou diretamente de uma classe específica do modelo.

A API [AutoClass](./model_doc/auto) fornece um método conveniente para carregar um processador de imagem sem especificar diretamente o modelo com o qual o processador de imagem está associado.

Use [from_pretrained()](/docs/transformers/main/pt/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) com o argumento `backend` para selecionar o backend. Quando `backend` é omitido (o padrão), o torchvision é escolhido se estiver instalado; caso contrário, o PIL é usado. Observe que `backend="pil"` é suportado apenas para modelos mais antigos; modelos mais novos expõem apenas o backend torchvision.

Para a correspondência mais próxima com o pré-processamento de treinamento de um modelo, use o backend especificado em sua documentação ou código de treinamento. Se o pipeline de treinamento usa PIL e o modelo suporta ambos os backends, passe `backend="pil"`. Alterar o backend pode modificar os valores de pixels redimensionados, e atualizações do Pillow ou do torchvision também podem alterá-los. Para um pré-processamento reproduzível, mantenha as versões do backend e da biblioteca de imagens fixas.

> [!NOTE]
> Um pequeno conjunto de modelos mais antigos (Chameleon, Flava, Idefics3, SmolVLM) usa interpolação Lanczos. O backend padrão deles depende da sua versão do torchvision. Com torchvision > 0.27, o Lanczos é suportado nativamente e esses modelos usam torchvision como padrão. Versões mais antigas do torchvision recorrem ao BICUBIC, então o padrão é PIL para preservar as saídas originais. Passe `backend="torchvision"` explicitamente para sobrescrever o padrão.

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

Cada processador de imagem está associado a um modelo de visão pré-treinado específico, e sua configuração contém o tamanho esperado e os parâmetros de normalização do modelo.

Carregue o processador do backend torchvision diretamente da classe específica do modelo.

```py
from transformers import ViTImageProcessor

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

Para modelos que oferecem suporte, você pode carregar o backend PIL com a classe com o sufixo `Pil`. Isso é útil quando você precisa de paridade numérica exata com a implementação original.

```py
from transformers import ViTImageProcessorPil

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

## Processadores de backend do Torchvision

[TorchvisionBackend](/docs/transformers/main/pt/main_classes/image_processor#transformers.TorchvisionBackend) é o backend **padrão**. Verifique se [torchvision](https://pytorch.org/get-started/locally/#mac-installation) está instalado e, em seguida, carregue-o com `backend="torchvision"` (ou simplesmente omita `backend`, pois o torchvision é selecionado automaticamente quando disponível).

```py
from transformers import AutoImageProcessor

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

Controle em qual dispositivo o processamento é executado com o argumento `device`. Por padrão, o processamento é realizado no mesmo dispositivo da entrada, caso as entradas sejam tensores; caso contrário, o sistema recorre à CPU. O exemplo abaixo executa o processamento em um acelerador.

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

Os benchmarks são obtidos a partir de uma instância [AWS EC2 g5.2xlarge](https://aws.amazon.com/ec2/instance-types/g5/) com uma GPU NVIDIA A10G Tensor Core.

  

  

  

  

## Resolução dinâmica

A maioria dos processadores de imagem redimensiona todas as imagens para uma resolução fixa. A resolução dinâmica permite que alguns modelos preservem a proporção original e deixem a quantidade de dados pré-processados crescer junto com a imagem, de modo que uma foto detalhada recebe mais patches do que um ícone pequeno e o modelo direciona seu poder de computação para onde há algo a ser analisado.

A forma como a imagem é dividida varia conforme o modelo. Alguns modelos recortam a imagem em um número variável de patches de tamanho fixo, limitado por parâmetros como `min_patches` e `max_patches`. Outros modelos redimensionam a imagem para a resolução que melhor a acomoda, seja escolhida de uma lista predefinida de proporções de aspecto ou derivada de um orçamento de pixels.

Consulte a página de documentação do modelo para obter seus parâmetros, valores padrão e formas de saída.

## Pré-processar

Os modelos de visão do Transformers esperam a entrada como tensores do PyTorch de valores de pixels. Um processador de imagens trata a conversão de imagens em valores de pixels, que é representado pelo tamanho do lote, número de canais, altura e largura. Para isso, uma imagem é redimensionada (com recorte central) e os valores de pixels são normalizados e reescalados para os valores esperados pelos modelos.

O pré-processamento de imagens não é a mesma coisa que *ampliação de imagens*. A ampliação de imagens realiza alterações (brilho, cores, rotação, etc.) em uma imagem com o objetivo de criar novos exemplos de treinamento ou de evitar o sobreajuste. O pré-processamento de imagens realiza alterações em uma imagem com o objetivo de corresponder ao formato de entrada esperado por um modelo pré-treinado.

Normalmente, as imagens são aumentadas (para aumentar o desempenho) e, em seguida, pré-processadas antes de serem passadas a um modelo. Você pode usar qualquer biblioteca ([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)) para o aumento e um processador de imagens para o pré-processamento.

Este guia usa o módulo [transforms](https://pytorch.org/vision/stable/transforms.html) do torchvision para aumento de dados.

Comece carregando uma pequena amostra do conjunto de dados [food101](https://hf.co/datasets/food101).

```py
from datasets import load_dataset

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

Do módulo [transforms](https://pytorch.org/vision/stable/transforms.html), use a API [Compose](https://pytorch.org/vision/master/generated/torchvision.transforms.Compose.html) para encadear [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) e [ColorJitter](https://pytorch.org/vision/main/generated/torchvision.transforms.ColorJitter.html). Essas transformações recortam e redimensionam uma imagem aleatoriamente e ajustam as cores de uma imagem de forma aleatória.

O tamanho da imagem para o recorte aleatório pode ser obtido do processador de imagens. Para alguns modelos, são esperados valores exatos de altura e largura, enquanto para outros, apenas o `shortest_edge` é necessário.

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

Aplique as transformações às imagens e converta-as para o formato RGB. Em seguida, passe as imagens aumentadas para o processador de imagens para retornar os valores de pixels.

O parâmetro `do_resize` é definido como `False` porque as imagens já foram redimensionadas na etapa de aumento por [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html). Se você não aumentar as imagens, o processador de imagens redimensiona e normaliza as imagens automaticamente com os valores de `image_mean` e `image_std`. Esses valores são encontrados no arquivo de configuração do pré-processador.

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

Aplique a função combinada de aumento e pré-processamento a todo o conjunto de dados em tempo de execução com [set_transform](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset.set_transform).

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

Convert os valores de pixels de volta para uma imagem para ver como a imagem foi aumentada e pré-processada.

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

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

  
    
    antes
  
  
    
    após
  

Para outras tarefas de visão, como detecção de objetos ou segmentação, o processador de imagens inclui métodos de pós-processamento para converter a saída bruta de um modelo em previsões significativas, como caixas delimitadoras ou mapas de segmentação.

### Preenchimento

Alguns modelos, como o [DETR](./model_doc/detr), aplicam [scale augmentation](https://paperswithcode.com/method/image-scale-augmentation) durante o treinamento, o que pode fazer com que as imagens em um lote tenham tamanhos diferentes. Imagens com tamanhos diferentes não podem ser agrupadas em um lote.

Para corrigir isso, preencha as imagens com o token especial de preenchimento `0`. Use o método [pad](https://github.com/huggingface/transformers/blob/9578c2597e2d88b6f0b304b5a05864fd613ddcc1/src/transformers/models/detr/image_processing_detr.py#L1151) para preencher as imagens e defina uma função de colagem personalizada para agrupá-las em lotes.

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