# Procesadores de imágenes

Los procesadores de imagen convierten las imágenes en valores de píxel, tensores que representan los colores y el tamaño de la imagen. Los valores de píxel son las entradas de un modelo de visión. Para garantizar que un modelo preentrenado reciba la entrada correcta, un procesador de imagen puede realizar las siguientes operaciones para asegurarse de que una imagen sea exactamente como las imágenes con las que se preentrenó el modelo.

- recortar al centro o redimensionar una imagen
- normalizar o reescalar los valores de píxeles

Use [from_pretrained()](/docs/transformers/v5.23.0/es/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) para cargar la configuración de un procesador de imágenes (tamaño de imagen, si normalizar y reescalar, etc.) desde un modelo de visión en el [Hub](https://hf.co) de Hugging Face o desde un directorio local. La configuración de cada modelo preentrenado se guarda en un archivo [preprocessor_config.json](https://huggingface.co/google/vit-base-patch16-224/blob/main/preprocessor_config.json).

Cuando un procesador de imágenes forma parte de un procesador multimodal, su configuración se anida en `processor_config.json`. Consulte [Guardar y cargar un procesador](./processors#save-and-load-a-processor) para obtener más detalles.

```py
from transformers import AutoImageProcessor

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

Pasa una imagen al procesador de imágenes para transformarla en valores de píxeles y establece `return_tensors="pt"` para devolver tensores de PyTorch. Puedes imprimir las entradas para ver cómo se ve la imagen como 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")
```

Esta guía cubre la clase de procesador de imágenes y cómo preprocesar imágenes para modelos de visión.

## Clases de procesadores de imágenes

Los procesadores de imágenes utilizan una arquitectura basada en backends con dos backends:

- [TorchvisionBackend](/docs/transformers/v5.23.0/es/main_classes/image_processor#transformers.TorchvisionBackend) — la implementación predeterminada con [soporte de torchvision](https://pytorch.org/vision/stable/index.html). Acelerada por GPU y hasta 33 veces más rápida que el backend de PIL para lotes de entradas [torch.Tensor](https://pytorch.org/docs/stable/tensors.html). Todos los modelos admiten este backend; los modelos más nuevos solo admiten este.
- [PilBackend](/docs/transformers/v5.23.0/es/main_classes/image_processor#transformers.PilBackend) — la alternativa de PIL/NumPy. Portable y solo para CPU. Solo disponible para modelos más antiguos, donde resulta útil reproducir las salidas numéricas exactas de la implementación original.

El backend activo en un procesador cargado se puede inspeccionar con su atributo `backend` (p. ej., `processor.backend == "torchvision"`). Cada procesador de imágenes es una subclase de [ImageProcessingMixin](/docs/transformers/v5.23.0/es/internal/image_processing_utils#transformers.ImageProcessingMixin), que proporciona los métodos [from_pretrained()](/docs/transformers/v5.23.0/es/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) y [save_pretrained()](/docs/transformers/v5.23.0/es/internal/image_processing_utils#transformers.ImageProcessingMixin.save_pretrained).

Hay dos formas de cargar un procesador de imágenes: con [AutoImageProcessor](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoImageProcessor) o directamente desde una clase específica del modelo.

La API [AutoClass](./model_doc/auto) ofrece un método conveniente para cargar un procesador de imágenes sin especificar directamente el modelo con el que está asociado el procesador.

Use [from_pretrained()](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) con el argumento `backend` para seleccionar el backend. Cuando se omite `backend` (el valor predeterminado), se elige torchvision si está instalado y se usa PIL en caso contrario. Tenga en cuenta que `backend="pil"` solo se admite para modelos más antiguos; los modelos más nuevos solo exponen el backend de torchvision.

Para obtener el preprocesamiento más cercano al utilizado durante el entrenamiento de un modelo, use el backend especificado en su documentación o código de entrenamiento. Si el pipeline de entrenamiento usa PIL y el modelo admite ambos backends, pase `backend="pil"`. Cambiar de backend puede alterar los valores de píxeles redimensionados, y las actualizaciones de Pillow o torchvision también pueden modificarlos. Para un preprocesamiento reproducible, mantenga fijas las versiones del backend y de la biblioteca de imágenes.

> [!NOTE]
> Un pequeño conjunto de modelos más antiguos (Chameleon, Flava, Idefics3, SmolVLM) utiliza interpolación Lanczos. Su backend predeterminado depende de tu versión de torchvision. Con torchvision > 0.27, Lanczos se admite de forma nativa y estos modelos usan torchvision por defecto. Las versiones anteriores de torchvision recurren a BICUBIC, por lo que el valor predeterminado es PIL para preservar las salidas originales. Pasa `backend="torchvision"` explícitamente para anular el valor predeterminado.

```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 procesador de imágenes está asociado con un modelo de visión preentrenado específico, y su configuración contiene el tamaño esperado del modelo y los parámetros de normalización.

Cargue el procesador del backend torchvision directamente desde la clase específica del modelo.

```py
from transformers import ViTImageProcessor

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

Para los modelos que lo admiten, puedes cargar el backend PIL con la clase con el sufijo `Pil`. Esto es útil cuando necesitas una paridad numérica exacta con la implementación original.

```py
from transformers import ViTImageProcessorPil

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

## Procesadores de backends de Torchvision

[TorchvisionBackend](/docs/transformers/v5.23.0/es/main_classes/image_processor#transformers.TorchvisionBackend) es el backend **predeterminado**. Asegúrate de que [torchvision](https://pytorch.org/get-started/locally/#mac-installation) esté instalado y luego cárgalo con `backend="torchvision"` (o simplemente omite `backend`, ya que torchvision se selecciona automáticamente cuando está disponible).

```py
from transformers import AutoImageProcessor

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

Controle en qué dispositivo se realiza el procesamiento con el argumento `device`. Por defecto, el procesamiento se realiza en el mismo dispositivo que la entrada si las entradas son tensores; de lo contrario, se recurre a la CPU. El ejemplo siguiente ejecuta el procesamiento en un 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

Los benchmarks se obtienen de una instancia [AWS EC2 g5.2xlarge](https://aws.amazon.com/ec2/instance-types/g5/) con una GPU NVIDIA A10G Tensor Core.

  

  

  

  

## Resolución dinámica

La mayoría de los procesadores de imagen redimensionan cada imagen a una resolución fija. La resolución dinámica permite que algunos modelos conserven la relación de aspecto original y que la cantidad de datos preprocesados crezca con la imagen, de modo que una foto detallada recibe más parches que un icono pequeño y el modelo destina su capacidad de cómputo a donde hay algo que observar.

La forma en que se divide la imagen depende del modelo. Algunos modelos recortan la imagen en un número variable de parches de tamaño fijo, limitado por parámetros como `min_patches` y `max_patches`. Otros modelos redimensionan la imagen a la resolución que mejor se ajuste, ya sea elegida de una lista predefinida de relaciones de aspecto o derivada de un presupuesto de píxeles.

Consulte la página de documentación del modelo para conocer sus parámetros, valores predeterminados y formas de salida.

## Preprocesar

Los modelos de visión de Transformers esperan la entrada como tensores de PyTorch con valores de píxeles. Un procesador de imágenes gestiona la conversión de imágenes a valores de píxeles, representados por el tamaño del lote, el número de canales, la altura y el ancho. Para lograrlo, la imagen se redimensiona (con recorte centrado) y los valores de píxeles se normalizan y reescalan a los valores esperados por el modelo.

El preprocesamiento de imágenes no es lo mismo que la *ampliación de imágenes*. La ampliación de imágenes realiza modificaciones (brillo, colores, rotación, etc.) en una imagen con el fin de crear nuevos ejemplos de entrenamiento o prevenir el sobreajuste. El preprocesamiento de imágenes realiza modificaciones en una imagen con el fin de adaptarla al formato de entrada esperado por un modelo preentrenado.

Por lo general, las imágenes se aumentan (para mejorar el rendimiento) y luego se preprocesan antes de pasarlas a un modelo. Puede utilizar cualquier 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 el aumento y un procesador de imágenes para el preprocesamiento.

Esta guía utiliza el módulo [transforms](https://pytorch.org/vision/stable/transforms.html) de torchvision para la aumentación.

Comience cargando una pequeña muestra del conjunto de datos [food101](https://hf.co/datasets/food101).

```py
from datasets import load_dataset

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

Desde el módulo [transforms](https://pytorch.org/vision/stable/transforms.html), use la API [Compose](https://pytorch.org/vision/master/generated/torchvision.transforms.Compose.html) para encadenar [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) y [ColorJitter](https://pytorch.org/vision/main/generated/torchvision.transforms.ColorJitter.html). Estas transformaciones recortan y redimensionan una imagen de forma aleatoria, y ajustan los colores de una imagen de forma aleatoria.

El tamaño de imagen al que recortar aleatoriamente se puede obtener del procesador de imágenes. Para algunos modelos se esperan una altura y un ancho exactos, mientras que para otros solo se requiere `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)])
```

Aplica las transformaciones a las imágenes y conviértelas al formato RGB. Luego, pasa las imágenes aumentadas al procesador de imágenes para que devuelva los valores de píxeles.

El parámetro `do_resize` se establece en `False` porque las imágenes ya se han redimensionado en el paso de aumento mediante [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html). Si no se aumentan las imágenes, el procesador de imágenes redimensiona y normaliza automáticamente las imágenes con los valores de `image_mean` y `image_std`. Estos valores se encuentran en el archivo de configuración del preprocesador.

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

Aplica la función combinada de aumento y preprocesamiento a todo el conjunto de datos sobre la marcha con [set_transform](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset.set_transform).

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

Convierte los valores de píxeles de nuevo en una imagen para ver cómo se ha aumentado y preprocesado la imagen.

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

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

  
    
    antes
  
  
    
    después
  

Para otras tareas de visión, como la detección de objetos o la segmentación, el procesador de imágenes incluye métodos de posprocesamiento para convertir la salida cruda de un modelo en predicciones significativas, como cajas delimitadoras o mapas de segmentación.

### Relleno

Algunos modelos, como [DETR](./model_doc/detr), aplican [scale augmentation](https://paperswithcode.com/method/image-scale-augmentation) durante el entrenamiento, lo que puede provocar que las imágenes de un lote tengan tamaños diferentes. Las imágenes de tamaños distintos no se pueden agrupar en un mismo lote.

Para solucionarlo, rellena las imágenes con el token de relleno especial `0`. Usa el método [pad](https://github.com/huggingface/transformers/blob/9578c2597e2d88b6f0b304b5a05864fd613ddcc1/src/transformers/models/detr/image_processing_detr.py#L1151) para rellenar las imágenes y define una función de collate personalizada para agruparlas en 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
```

