# SAM-HQ

## Resumen

SAM-HQ (High-Quality Segment Anything Model) fue propuesto en [Segment Anything in High Quality](https://huggingface.co/papers/2306.01567) por Lei Ke, Mingqiao Ye, Martin Danelljan, Yifan Liu, Yu-Wing Tai, Chi-Keung Tang, Fisher Yu.

El modelo es una mejora del modelo SAM original que produce máscaras de segmentación de calidad significativamente superior, al tiempo que mantiene el diseño con prompts, la eficiencia y la capacidad de generalización cero del SAM original.

![example image](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-output.png)

SAM-HQ introduce varias mejoras clave con respecto al modelo SAM original:

1. Token de salida de alta calidad: un token aprendible inyectado en el decodificador de máscaras de SAM para una predicción de máscaras de mayor calidad
2. Fusión de características globales y locales: Combina características de diferentes etapas del modelo para mejorar los detalles de la máscara
3. Datos de entrenamiento: Utiliza un conjunto de datos cuidadosamente seleccionado de 44K máscaras de alta calidad en lugar de SA-1B
4. Eficiencia: Añade solo un 0,5 % de parámetros adicionales mientras mejora significativamente la calidad de la máscara
5. Capacidad de cero ejemplos: Mantiene el sólido rendimiento de cero ejemplos de SAM mientras mejora la precisión

El resumen del artículo es el siguiente:

*El reciente Segment Anything Model (SAM) representa un gran avance en la escalabilidad de los modelos de segmentación, lo que permite capacidades potentes de cero disparo (zero-shot) y un prompting flexible. A pesar de haber sido entrenado con 1.100 millones de máscaras, la calidad de predicción de máscaras de SAM es deficiente en muchos casos, especialmente al tratar con objetos que tienen estructuras intrincadas. Proponemos HQ-SAM, que dota a SAM de la capacidad de segmentar con precisión cualquier objeto, al tiempo que mantiene el diseño original de SAM, su eficiencia y su capacidad de generalización de cero disparo. Nuestro diseño cuidadoso reutiliza y preserva los pesos del modelo preentrenado de SAM, introduciendo solo parámetros y computación adicionales mínimos. Diseñamos un token de salida de alta calidad (High-Quality Output Token) aprendible, que se inyecta en el decodificador de máscaras de SAM y es responsable de predecir la máscara de alta calidad. En lugar de aplicarlo solo a las características del decodificador de máscaras, primero las fusionamos con las características iniciales y finales de ViT para mejorar los detalles de la máscara. Para entrenar los parámetros aprendibles que introdujimos, componemos un conjunto de datos de 44K máscaras de gran granularidad a partir de varias fuentes. HQ-SAM solo se entrena en el conjunto de datos introducido de 44k máscaras, lo que toma solo 4 horas en 8 GPUs.*

Consejos:

- SAM-HQ produce máscaras de mayor calidad que el modelo SAM original, especialmente para objetos con estructuras intrincadas y detalles finos
- El modelo predice máscaras binarias con bordes más precisos y un mejor manejo de estructuras delgadas
- Al igual que SAM, el modelo rinde mejor con puntos 2D de entrada y/o cajas delimitadoras de entrada
- Puedes indicar varios puntos para la misma imagen y predecir una única máscara de alta calidad
- El modelo mantiene las capacidades de generalización zero-shot de SAM
- SAM-HQ solo añade aproximadamente un 0,5% de parámetros adicionales en comparación con SAM
- El ajuste fino del modelo aún no está admitido

Este modelo fue aportado por [sushmanth](https://huggingface.co/sushmanth). El código original se puede encontrar [aquí](https://github.com/SysCV/SAM-HQ).

A continuación se muestra un ejemplo de cómo ejecutar la generación de máscaras a partir de una imagen y un punto 2D:

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

También puede procesar sus propias máscaras junto con las imágenes de entrada en el procesador para pasarlas al modelo:

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
mask_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
segmentation_map = Image.open(requests.get(mask_url, stream=True).raw).convert("1")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, segmentation_maps=segmentation_map, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

## Recursos

Una lista de recursos oficiales de Hugging Face y de la comunidad (indicados por 🌎) para ayudarte a empezar con SAM-HQ:

- Cuaderno de demostración para usar el modelo (próximamente)
- Implementación del paper y código: [Repositorio de GitHub de SAM-HQ](https://github.com/SysCV/SAM-HQ)

## SamHQConfig[[transformers.SamHQConfig]]

#### transformers.SamHQConfig[[transformers.SamHQConfig]]

```python
transformers.SamHQConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, tie_word_embeddings: bool = True)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L155)

**Parámetros:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : El objeto de configuración o el diccionario del backbone de visión.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *opcional*) : Diccionario de opciones de configuración utilizado para inicializar [SamHQPromptEncoderConfig](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *opcional*) : Diccionario de opciones de configuración utilizado para inicializar [SamHQMaskDecoderConfig](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

initializer_range (`float`, *opcional*, valor predeterminado `0.02`) : La desviación estándar de truncated_normal_initializer para inicializar todas las matrices de pesos.

tie_word_embeddings (`bool`, *opcional*, valor predeterminado `True`) : Indica si se deben vincular las incrustaciones de pesos según el mapeo `tied_weights_keys` del modelo.

Esta es la clase de configuración para almacenar la configuración de un SamHQModel. Se utiliza para instanciar un modelo Sam Hq según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

## SamHQVisionConfig[[transformers.SamHQVisionConfig]]

#### transformers.SamHQVisionConfig[[transformers.SamHQVisionConfig]]

```python
transformers.SamHQVisionConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 768, output_channels: int = 256, num_hidden_layers: int = 12, num_attention_heads: int = 12, num_channels: int = 3, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, attention_dropout: float | int = 0.0, initializer_range: float = 1e-10, qkv_bias: bool = True, mlp_ratio: float = 4.0, use_abs_pos: bool = True, use_rel_pos: bool = True, window_size: int = 14, global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11), num_pos_feats: int = 128, mlp_dim: int | None = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L55)

**Parámetros:**

hidden_size (`int`, *opcional*, valor predeterminado `768`) : Dimensión de las representaciones ocultas.

output_channels (`int`, *opcional*, valor predeterminado 256) : Dimensionalidad de los canales de salida en el Patch Encoder.

num_hidden_layers (`int`, *opcional*, valor predeterminado `12`) : Número de capas ocultas en el decodificador del Transformer.

num_attention_heads (`int`, *opcional*, valor predeterminado `12`) : Número de cabezas de atención para cada capa de atención en el decodificador Transformer.

num_channels (`int`, *opcional*, valor predeterminado `3`) : El número de canales de entrada.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `1024`) : El tamaño (resolución) de cada imagen.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `16`) : El tamaño (resolución) de cada parche.

hidden_act (`str`, *opcional*, valor predeterminado `gelu`) : La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *opcional*, valor predeterminado `1e-06`) : El epsilon utilizado por las capas de normalización de capas.

attention_dropout (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción de dropout para las probabilidades de atención.

initializer_range (`float`, *opcional*, valor predeterminado `1e-10`) : La desviación estándar de truncated_normal_initializer para inicializar todas las matrices de pesos.

qkv_bias (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe añadir un sesgo a las consultas, claves y valores.

mlp_ratio (`float`, *opcional*, valor predeterminado `4.0`) : Proporción entre la dimensión oculta del MLP y la dimensión de incrustación.

use_abs_pos (`bool`, *opcional*, valor predeterminado `True`) : Si se deben usar incrustaciones de posición absoluta.

use_rel_pos (`bool`, *opcional*, valor predeterminado `True`) : Si se debe usar la incrustación de posición relativa.

window_size (`int`, *opcional*, valor predeterminado 14) : Tamaño de la ventana para la posición relativa.

global_attn_indexes (`list[int]`, *opcional*, valor predeterminado `[2, 5, 8, 11]`) : Los índices de las capas de atención global.

num_pos_feats (`int`, *opcional*, valor predeterminado 128) : La dimensionalidad del embedding de posición.

mlp_dim (`int`, *opcional*) : La dimensionalidad de la capa MLP en el codificador Transformer. Si es `None`, el valor predeterminado es `mlp_ratio * hidden_size`.

Esta es la clase de configuración para almacenar la configuración de un SamHQModel. Se utiliza para instanciar un modelo Sam Hq según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:

```python
>>> from transformers import (
...     SamHQVisionConfig,
...     SamHQVisionModel,
... )

>>> # Initializing a SamHQVisionConfig with `"facebook/sam_hq-vit-huge"` style configuration
>>> configuration = SamHQVisionConfig()

>>> # Initializing a SamHQVisionModel (with random weights) from the `"facebook/sam_hq-vit-huge"` style configuration
>>> model = SamHQVisionModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

#### transformers.SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

```python
transformers.SamHQMaskDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, hidden_act: str = 'relu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, layer_norm_eps: float = 1e-06, vit_dim: int = 768)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L120)

**Parámetros:**

hidden_size (`int`, *opcional*, valor predeterminado `256`) : Dimensión de las representaciones ocultas.

hidden_act (`str`, *opcional*, valor predeterminado `relu`) : La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

mlp_dim (`int`, *opcional*, valor predeterminado 2048) : Dimensionalidad de la capa "intermedia" (es decir, de retroalimentación) en el codificador Transformer.

num_hidden_layers (`int`, *opcional*, valor predeterminado `2`) : Número de capas ocultas en el decodificador del Transformer.

num_attention_heads (`int`, *opcional*, valor predeterminado `8`) : Número de cabezas de atención para cada capa de atención en el decodificador del Transformer.

attention_downsample_rate (`int`, *opcional*, valor predeterminado 2) : La tasa de submuestreo de la capa de atención.

num_multimask_outputs (`int`, *opcional*, valor predeterminado 3) : El número de salidas del módulo `SamMaskDecoder`. En el paper de Segment Anything, este valor se establece en 3.

iou_head_depth (`int`, *opcional*, valor predeterminado 3) : El número de capas en el módulo de la cabeza IoU.

iou_head_hidden_dim (`int`, *opcional*, valor predeterminado 256) : La dimensionalidad de los estados ocultos en el módulo de la cabeza IoU.

layer_norm_eps (`float`, *opcional*, valor predeterminado `1e-06`) : El epsilon utilizado por las capas de normalización de capas.

vit_dim (`int`, *opcional*, valor predeterminado 768) : Dimensionalidad del Vision Transformer (ViT) utilizado en el módulo `SamHQMaskDecoder`.

Esta es la clase de configuración para almacenar la configuración de un SamHQModel. Se utiliza para instanciar un modelo Sam Hq según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

## SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

#### transformers.SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

```python
transformers.SamHQPromptEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L29)

**Parámetros:**

hidden_size (`int`, *opcional*, valor predeterminado `256`) : Dimensión de las representaciones ocultas.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `1024`) : El tamaño (resolución) de cada imagen.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `16`) : El tamaño (resolución) de cada parche.

mask_input_channels (`int`, *opcional*, valor predeterminado 16) : El número de canales que se enviarán al módulo `MaskDecoder`.

num_point_embeddings (`int`, *opcional*, valor predeterminado: 4) : El número de embeddings de puntos que se utilizarán.

hidden_act (`str`, *opcional*, valor predeterminado `gelu`) : La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *opcional*, valor predeterminado `1e-06`) : El epsilon utilizado por las capas de normalización de capas.

Esta es la clase de configuración para almacenar la configuración de un SamHQModel. Se utiliza para instanciar un modelo Sam Hq según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

## SamHQProcessor[[transformers.SamHQProcessor]]

#### transformers.SamHQProcessor[[transformers.SamHQProcessor]]

```python
transformers.SamHQProcessor(image_processor)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L83)

**Parámetros:**

image_processor (`SamImageProcessor`) : El procesador de imágenes es un parámetro de entrada obligatorio.

Construye un SamHQProcessor que envuelve un procesador de imágenes en un único procesador.

[SamHQProcessor](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQProcessor) ofrece todas las funcionalidades de [SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor). Consulte [~SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor) para obtener más información.

#### __llamada__[[transformers.SamHQProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L93)

**Parámetros:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opcional*) : Imagen para preprocesar. Espera una imagen única o un lote de imágenes con valores de píxeles que van de 0 a 255. Si se pasan imágenes con valores de píxeles entre 0 y 1, establezca `do_rescale=False`.

segmentation_maps (`ImageInput`, *kwargs*, *opcional*) : Mapas de segmentación de referencia para procesar junto con las imágenes de entrada. Estos mapas se utilizan con fines de entrenamiento o evaluación y se redimensionan y normalizan para que coincidan con las dimensiones de la imagen procesada.

input_points (`NestedList`, *kwargs*, *opcional*) : Puntos de entrada para la segmentación basada en prompts. Debe ser una lista anidada con la estructura `[image_level, object_level, point_level, [x, y]]` donde cada punto se especifica como coordenadas `[x, y]` en el espacio de la imagen original. Los puntos se normalizan al tamaño de la imagen objetivo antes de pasarse al modelo.

input_labels (`NestedList`, *kwargs*, *opcional*) : Etiquetas para los puntos de entrada, que indican si cada punto es de primer plano (1) o de fondo (0). Debe ser una lista anidada con la estructura `[image_level, object_level, point_level]`. Debe tener la misma estructura que `input_points` (excluyendo la dimensión de coordenadas).

input_boxes (`NestedList`, *kwargs*, *opcional*) : Cajas delimitadoras para segmentación basada en prompts. Debe ser una lista anidada con la estructura `[image_level, box_level, [x1, y1, x2, y2]]` donde cada caja se especifica como coordenadas `[x1, y1, x2, y2]` en el espacio de la imagen original. Las cajas se normalizan al tamaño de la imagen objetivo antes de pasarse al modelo.

point_pad_value (`int`, *kwargs*, *opcional*, valor predeterminado `None`) : El valor utilizado para rellenar los puntos de entrada al agrupar secuencias de diferentes longitudes. Este valor marca las posiciones rellenas y se conserva durante la normalización de coordenadas para distinguir los puntos reales del relleno. Si es `None`, se utiliza el valor de relleno predeterminado de la configuración del procesador.

mask_size (`dict[str, *kwargs*, int]`, *opcional*) : Diccionario que especifica el tamaño de la máscara objetivo con las claves `"height"` y `"width"`. Esto determina la resolución de las máscaras de segmentación de salida generadas por el modelo.

mask_pad_size (`dict[str, *kwargs*, int]`, *opcional*) : Diccionario que especifica el tamaño de relleno para las máscaras, con las claves `"height"` y `"width"`. Se utiliza al agrupar máscaras de diferentes tamaños para garantizar dimensiones consistentes.

return_tensors (`str` o [TensorType](/docs/transformers/main/es/internal/file_utils#transformers.TensorType), *opcional*) : Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:  - `'pt'`: Devuelve objetos `torch.Tensor` de PyTorch. - `'np'`: Devuelve objetos `np.ndarray` de NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/es/main_classes/processors#transformers.ProcessingKwargs), *opcional*) : Opciones de procesamiento adicionales para cada modalidad (texto, imágenes, vídeos, audio). Los parámetros específicos del modelo se enumeran arriba; consulte la clase TypedDict para obtener la lista completa de argumentos admitidos.

**Devuelve:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *opcional*) -- Diccionario de listas/arrays/tensores devueltos por los métodos __call__/pad ('input_values', 'attention_mask', etc.).
- **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Puede especificar un tensor_type aquí para convertir las listas de enteros en Tensors de PyTorch/Numpy durante la inicialización.
- **skip_tensor_conversion** (`list[str]` o `set[str]`, *opcional*) -- Lista o conjunto de claves que NO deben convertirse en tensores, incluso cuando se especifica `tensor_type`.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

#### transformers.SamHQVisionModel[[transformers.SamHQVisionModel]]

```python
transformers.SamHQVisionModel(config: SamHQVisionConfig)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1076)

**Parámetros:**

config ([SamHQVisionConfig](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQVisionConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

El modelo de visión de SamHQ sin ninguna cabeza ni proyección en la parte superior.

Este modelo hereda de [PreTrainedModel](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

#### forward[[transformers.SamHQVisionModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1088)

**Parámetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener usando [SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor). Consulte [SamImageProcessor.__call__()](/docs/transformers/main/es/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para más detalles ([SamHQProcessor](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQProcessor) utiliza [SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor) para procesar las imágenes).

**Devuelve:** `SamHQVisionEncoderOutput` o `tuple(torch.Tensor)`

Un `SamHQVisionEncoderOutput` o una tupla de `torch.Tensor` (si se pasa `return_dict=False` o cuando `config.return_dict=False`) que comprende varios elementos según la configuración ([SamHQConfig](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQConfig)) y las entradas.

El método forward de [SamHQVisionModel](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQVisionModel) sobrescribe el método especial `__call__`.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **image_embeds** (`torch.Tensor` de forma `(batch_size, output_dim)` *opcional* devuelta cuando el modelo se inicializa con `with_projection=True`) -- Las incrustaciones de imagen obtenidas al aplicar la capa de proyección a pooler_output.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Secuencia de estados ocultos en la salida de la última capa del modelo.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
- **attentions** (`tuple[torch.Tensor, ...]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **intermediate_embeddings** (`list(torch.Tensor)`, *opcional*) -- Una lista de embeddings intermedios recopilados de ciertos bloques dentro del modelo, típicamente aquellos sin atención con ventana. Cada elemento de la lista tiene forma `(batch_size, sequence_length, hidden_size)`. Esto es específico de SAM-HQ y no está presente en SAM base.

## SamHQModel[[transformers.SamHQModel]]

#### transformers.SamHQModel[[transformers.SamHQModel]]

```python
transformers.SamHQModel(config: SamHQConfig)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1234)

**Parámetros:**

config ([SamHQConfig](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

Segment Anything Model HQ (SAM-HQ) para generar máscaras, a partir de una imagen de entrada y ubicaciones 2D y cajas delimitadoras opcionales.

Este modelo hereda de [PreTrainedModel](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

#### forward[[transformers.SamHQModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_points: typing.Optional[torch.Tensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.Tensor] = None, multimask_output: bool = True, hq_token_only: bool = False, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, intermediate_embeddings: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1318)

**Parámetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener usando [SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor). Consulte [SamImageProcessor.__call__()](/docs/transformers/main/es/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para más detalles ([SamHQProcessor](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQProcessor) utiliza [SamImageProcessor](/docs/transformers/main/es/model_doc/sam#transformers.SamImageProcessor) para procesar las imágenes).

input_points (`torch.Tensor` de forma `(batch_size, num_points, 2)`) : Puntos espaciales 2D de entrada, que se utilizan en el codificador de prompts para codificar el prompt. Generalmente, produce resultados mucho mejores. Los puntos se pueden obtener pasando una lista de listas de listas al procesador, que creará los correspondientes tensores `torch` de dimensión 4. La primera dimensión es el tamaño del lote de imágenes, la segunda dimensión es el tamaño del lote de puntos (es decir, cuántas máscaras de segmentación queremos que el modelo prediga por cada punto de entrada), la tercera dimensión es el número de puntos por máscara de segmentación (es posible pasar varios puntos para una sola máscara) y la última dimensión son las coordenadas x (vertical) y y (horizontal) del punto. Si se pasa un número diferente de puntos para cada imagen o para cada máscara, el procesador creará puntos "PAD" que corresponderán a la coordenada (0, 0) y se omitirá el cálculo del embedding para estos puntos usando las etiquetas.

input_labels (`torch.LongTensor` de forma `(batch_size, point_batch_size, num_points)`) : Etiquetas de entrada para los puntos, que se utilizan en el codificador de prompts para codificar el prompt. Según la implementación oficial, existen 3 tipos de etiquetas: - `1`: el punto contiene el objeto de interés - `0`: el punto no contiene el objeto de interés - `-1`: el punto corresponde al fondo  Añadimos la etiqueta: - `-10`: el punto es un punto de relleno, por lo que debe ser ignorado por el codificador de prompts  Las etiquetas de relleno deben generarse automáticamente mediante el procesador.

input_boxes (`torch.Tensor` de forma `(batch_size, num_boxes, 4)`) : Cajas de entrada para los puntos, que se utilizan en el codificador de prompts para codificar el prompt. Generalmente, esto produce máscaras generadas mucho mejores. Las cajas se pueden obtener pasando una lista de listas de listas al procesador, que generará un tensor de `torch`, donde cada dimensión corresponde respectivamente al tamaño del lote de imágenes, al número de cajas por imagen y a las coordenadas del punto superior izquierdo y del punto inferior derecho de la caja. En el orden (`x1`, `y1`, `x2`, `y2`):  - `x1`: la coordenada x del punto superior izquierdo de la caja de entrada - `y1`: la coordenada y del punto superior izquierdo de la caja de entrada - `x2`: la coordenada x del punto inferior derecho de la caja de entrada - `y2`: la coordenada y del punto inferior derecho de la caja de entrada

input_masks (`torch.Tensor` de forma `(batch_size, image_size, image_size)`) : el modelo SAM_HQ también acepta máscaras de segmentación como entrada. La máscara se incrustará mediante el codificador de prompts para generar una incrustación correspondiente, que se enviará más adelante al decodificador de máscaras. Estas máscaras deben ser proporcionadas manualmente por el usuario y deben tener la forma (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` de forma `(batch_size, output_channels, window_size, window_size)`) : Incrustaciones de imagen, se utilizan en el decodificador de máscaras para generar máscaras y puntuaciones iou. Para un cálculo más eficiente en memoria, los usuarios pueden obtener primero las incrustaciones de imagen mediante el método `get_image_embeddings` y luego pasarlas al método `forward` en lugar de pasar `pixel_values`.

multimask_output (`bool`, *opcional*) : En la implementación y el artículo originales, el modelo siempre genera 3 máscaras por imagen (o por punto / por cuadro delimitador, si corresponde). Sin embargo, es posible generar una sola máscara, que corresponde a la máscara "óptima", especificando `multimask_output=False`.

hq_token_only (`bool`, *opcional*, valor predeterminado `False`) : Indica si se debe utilizar únicamente la ruta de tokens HQ para la generación de máscaras. Cuando es False, combina ambas rutas, la estándar y la HQ. Esto es específico de la arquitectura de SAM-HQ.

attention_similarity (`torch.Tensor`, *opcional*) : Tensor de similitud de atención, que debe proporcionarse al decodificador de máscaras para la atención guiada por objetivos en caso de que el modelo se utilice para personalización, tal como se introduce en [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *opcional*) : Incrustación del concepto objetivo, que debe proporcionarse al decodificador de máscaras para el prompting semántico del objetivo en caso de que el modelo se utilice para personalización, tal como se introduce en [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`, *opcional*) : Incrustaciones intermedias de los bloques sin ventana del codificador de visión, utilizadas por SAM-HQ para mejorar la calidad de las máscaras. Es obligatorio cuando se proporcionan image_embeddings precalculados en lugar de pixel_values.

**Devuelve:**

`list[dict[str, torch.Tensor]]`

El método forward de [SamHQModel](/docs/transformers/main/es/model_doc/sam_hq#transformers.SamHQModel) reemplaza el método especial `__call__`.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

Ejemplo:

```python
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("sushmanth/sam_hq_vit_b")
>>> processor = AutoProcessor.from_pretrained("sushmanth/sam_hq_vit_b")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=image, input_points=input_points, return_tensors="pt")

>>> # Get high-quality segmentation mask
>>> outputs = model(**inputs)

>>> # For high-quality mask only
>>> outputs = model(**inputs, hq_token_only=True)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"], inputs["reshaped_input_sizes"]
... )
```