# SAM-HQ

## Visão geral

O SAM-HQ (High-Quality Segment Anything Model) foi proposto em [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.

O modelo é uma melhoria em relação ao modelo SAM original, produzindo máscaras de segmentação de qualidade significativamente superior, ao mesmo tempo em que mantém o design promptável original do SAM, sua eficiência e sua generalização zero-shot.

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

O SAM-HQ introduz várias melhorias importantes em relação ao modelo SAM original:

1. Token de Saída de Alta Qualidade: Um token aprendível injetado no decodificador de máscaras do SAM para uma previsão de máscara de maior qualidade
2. Fusão de recursos globais e locais: Combina recursos de diferentes estágios do modelo para melhorar os detalhes da máscara
3. Dados de treinamento: Utiliza um conjunto de dados cuidadosamente curado com 44K máscaras de alta qualidade, em vez do SA-1B
4. Eficiência: Adiciona apenas 0,5% de parâmetros extras, melhorando significativamente a qualidade da máscara
5. Capacidade zero-shot: Mantém o forte desempenho zero-shot do SAM, ao mesmo tempo em que melhora a precisão

O resumo do artigo é o seguinte:

*O recente Segment Anything Model (SAM) representa um grande avanço na escalabilidade de modelos de segmentação, permitindo capacidades poderosas de zero-shot e prompting flexível. Apesar de ter sido treinado com 1,1 bilhão de máscaras, a qualidade da predição de máscaras do SAM fica aquém em muitos casos, particularmente ao lidar com objetos que possuem estruturas intrincadas. Propomos o HQ-SAM, que equipa o SAM com a capacidade de segmentar qualquer objeto com precisão, mantendo o design original do SAM baseado em prompts, sua eficiência e sua generalização zero-shot. Nosso design cuidadoso reutiliza e preserva os pesos do modelo pré-treinado do SAM, introduzindo apenas parâmetros e computação adicionais mínimos. Projetamos um Token de Saída de Alta Qualidade aprendível, que é injetado no decodificador de máscaras do SAM e é responsável por prever a máscara de alta qualidade. Em vez de aplicá-lo apenas nos recursos do decodificador de máscaras, primeiro os fundimos com os recursos iniciais e finais do ViT para melhorar os detalhes da máscara. Para treinar os parâmetros aprendíveis introduzidos, compomos um conjunto de dados com 44 mil máscaras de granularidade fina a partir de várias fontes. O HQ-SAM é treinado apenas no conjunto de dados introduzido de 44 mil máscaras, o que leva apenas 4 horas em 8 GPUs.*

Dicas:

- O SAM-HQ produz máscaras de maior qualidade do que o modelo SAM original, especialmente para objetos com estruturas intrincadas e detalhes finos
- O modelo prevê máscaras binárias com bordas mais precisas e um melhor tratamento de estruturas finas
- Assim como o SAM, o modelo apresenta melhor desempenho com pontos 2D de entrada e/ou caixas delimitadoras de entrada
- Você pode inserir múltiplos pontos para a mesma imagem e prever uma única máscara de alta qualidade
- O modelo mantém as capacidades de generalização zero-shot do SAM
- O SAM-HQ adiciona apenas ~0,5% de parâmetros adicionais em comparação com o SAM
- O ajuste fino do modelo ainda não é suportado

Este modelo foi contribuído por [sushmanth](https://huggingface.co/sushmanth). O código original pode ser encontrado [aqui](https://github.com/SysCV/SAM-HQ).

Abaixo, há um exemplo de como executar a geração de máscaras a partir de uma imagem e de um ponto 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
```

Você também pode processar suas próprias máscaras junto com as imagens de entrada no processador para serem passadas ao 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

Uma lista de recursos oficiais da Hugging Face e da comunidade (indicados por 🌎) para ajudar você a começar com o SAM-HQ:

- Notebook de demonstração para usar o modelo (em breve)
- Implementação do paper e código: [Repositório GitHub do 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)
```

[Origem](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*) : O objeto de configuração ou dicionário do backbone de visão.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *opcional*) : Dicionário de opções de configuração usadas para inicializar [SamHQPromptEncoderConfig](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *opcional*) : Dicionário de opções de configuração usadas para inicializar [SamHQMaskDecoderConfig](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

Esta é a classe de configuração para armazenar a configuração de um SamHQModel. Ela é usada para instanciar um modelo Sam Hq de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

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

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

**Parâmetros:**

hidden_size (`int`, *opcional*, padrão `768`) : Dimensão das representações ocultas.

output_channels (`int`, *opcional*, padrão 256) : Dimensionalidade dos canais de saída no Patch Encoder.

num_hidden_layers (`int`, *opcional*, padrão `12`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `12`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

num_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `1024`) : O tamanho (resolução) de cada imagem.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch.

hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização de camada.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

initializer_range (`float`, *opcional*, padrão `1e-10`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

qkv_bias (`bool`, *opcional*, padrão `True`) : Se deve adicionar um viés às queries, keys e values.

mlp_ratio (`float`, *opcional*, padrão `4.0`) : Razão entre a dimensão oculta do MLP e a dimensão de incorporação.

use_abs_pos (`bool`, *opcional*, padrão `True`) : Se deve usar embeddings de posição absoluta.

use_rel_pos (`bool`, *opcional*, padrão `True`) : Se deve usar incorporação de posição relativa.

window_size (`int`, *opcional*, padrão 14) : Tamanho da janela para posição relativa.

global_attn_indexes (`list[int]`, *opcional*, padrão `[2, 5, 8, 11]`) : Os índices das camadas de atenção global.

num_pos_feats (`int`, *opcional*, padrão 128) : A dimensionalidade do embedding de posição.

mlp_dim (`int`, *opcional*) : A dimensionalidade da camada MLP no codificador do Transformer. Se `None`, o valor padrão é `mlp_ratio * hidden_size`.

Esta é a classe de configuração para armazenar a configuração de um SamHQModel. Ela é usada para instanciar um modelo Sam Hq de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

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

**Parâmetros:**

hidden_size (`int`, *opcional*, padrão `256`) : Dimensão das representações ocultas.

hidden_act (`str`, *opcional*, padrão `relu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

mlp_dim (`int`, *opcional*, padrão 2048) : Dimensionalidade da camada "intermediária" (ou seja, feed-forward) no codificador do Transformer.

num_hidden_layers (`int`, *opcional*, padrão `2`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `8`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

attention_downsample_rate (`int`, *opcional*, padrão 2) : A taxa de redução de amostragem da camada de atenção.

num_multimask_outputs (`int`, *opcional*, padrão 3) : O número de saídas do módulo `SamMaskDecoder`. No paper Segment Anything, esse valor é definido como 3.

iou_head_depth (`int`, *opcional*, padrão 3) : O número de camadas no módulo de cabeça de IoU.

iou_head_hidden_dim (`int`, *opcional*, padrão 256) : A dimensionalidade dos estados ocultos no módulo de cabeça de IoU.

layer_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização de camada.

vit_dim (`int`, *opcional*, padrão 768) : Dimensionalidade do Vision Transformer (ViT) usado no módulo `SamHQMaskDecoder`.

Esta é a classe de configuração para armazenar a configuração de um SamHQModel. Ela é usada para instanciar um modelo Sam Hq de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

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

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

**Parâmetros:**

hidden_size (`int`, *opcional*, padrão `256`) : Dimensão das representações ocultas.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `1024`) : O tamanho (resolução) de cada imagem.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch.

mask_input_channels (`int`, *opcional*, padrão 16) : O número de canais a serem enviados para o módulo `MaskDecoder`.

num_point_embeddings (`int`, *opcional*, padrão 4) : O número de embeddings de pontos a serem usados.

hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização de camada.

Esta é a classe de configuração para armazenar a configuração de um SamHQModel. Ela é usada para instanciar um modelo Sam Hq de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## SamHQProcessor[[transformers.SamHQProcessor]]

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

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

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

**Parâmetros:**

image_processor (`SamImageProcessor`) : O processador de imagem é uma entrada obrigatória.

Constrói um SamHQProcessor que encapsula um processador de imagem em um único processador.

[SamHQProcessor](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQProcessor) oferece todas as funcionalidades de [SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor). Consulte [~SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor) para mais informações.

#### __call__[[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'>)
```

[Origem](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*) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`.

segmentation_maps (`ImageInput`, *kwargs*, *opcional*) : Mapas de segmentação de verdade fundamental para processar junto com as imagens de entrada. Esses mapas são usados para fins de treinamento ou avaliação e são redimensionados e normalizados para corresponder às dimensões da imagem processada.

input_points (`NestedList`, *kwargs*, *opcional*) : Pontos de entrada para segmentação baseada em prompt. Deve ser uma lista aninhada com a estrutura `[image_level, object_level, point_level, [x, y]]` em que cada ponto é especificado como coordenadas `[x, y]` no espaço da imagem original. Os pontos são normalizados para o tamanho da imagem de destino antes de serem passados ao modelo.

input_labels (`NestedList`, *kwargs*, *opcional*) : Rótulos para os pontos de entrada, indicando se cada ponto é de primeiro plano (1) ou de segundo plano (0). Deve ser uma lista aninhada com a estrutura `[image_level, object_level, point_level]`. Deve ter a mesma estrutura que `input_points` (excluindo a dimensão de coordenadas).

input_boxes (`NestedList`, *kwargs*, *opcional*) : Caixas delimitadoras para segmentação baseada em prompt. Deve ser uma lista aninhada com a estrutura `[image_level, box_level, [x1, y1, x2, y2]]` em que cada caixa é especificada pelas coordenadas `[x1, y1, x2, y2]` no espaço da imagem original. As caixas são normalizadas para o tamanho da imagem de destino antes de serem passadas ao modelo.

point_pad_value (`int`, *kwargs*, *opcional*, padrão é `None`) : O valor usado para preencher os pontos de entrada ao agrupar sequências de comprimentos diferentes. Este valor marca as posições preenchidas e é preservado durante a normalização de coordenadas para distinguir pontos reais de preenchimento. Se `None`, o valor de preenchimento padrão da configuração do processador é usado.

mask_size (`dict[str, *kwargs*, int]`, *opcional*) : Dicionário que especifica o tamanho da máscara de destino com as chaves `"height"` e `"width"`. Isso determina a resolução das máscaras de segmentação de saída geradas pelo modelo.

mask_pad_size (`dict[str, *kwargs*, int]`, *opcional*) : Dicionário que especifica o tamanho do preenchimento para máscaras, com as chaves `"height"` e `"width"`. Isso é usado ao agrupar máscaras de tamanhos diferentes para garantir dimensões consistentes.

return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores de um framework específico. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessingKwargs), *opcional*) : Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

**Retorna:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *opcional*) -- Dicionário de listas/arrays/tensors retornados pelos métodos __call__/pad ('input_values', 'attention_mask', etc.).
- **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização.
- **skip_tensor_conversion** (`list[str]` ou `set[str]`, *opcional*) -- Lista ou conjunto de chaves que NÃO devem ser convertidas em tensores, mesmo quando `tensor_type` for especificado.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

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

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

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

**Parâmetros:**

config ([SamHQVisionConfig](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQVisionConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo de visão do SamHQ, sem nenhum cabeçalho ou projeção no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

[Origem](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*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor). Veja [SamImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([SamHQProcessor](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQProcessor) usa [SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor) para processar imagens).

**Retorna:** `SamHQVisionEncoderOutput` ou `tuple(torch.Tensor)`

Uma `SamHQVisionEncoderOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([SamHQConfig](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQConfig)) e das entradas.

O método forward do [SamHQVisionModel](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQVisionModel) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **image_embeds** (`torch.Tensor` de forma `(batch_size, output_dim)` *opcional* retornado quando o modelo é inicializado com `with_projection=True`) -- Os embeddings de imagem obtidos ao aplicar a camada de projeção ao pooler_output.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de hidden-states na saída da última camada do modelo.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple[torch.Tensor, ...]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **intermediate_embeddings** (`list(torch.Tensor)`, *opcional*) -- Uma lista de embeddings intermediários coletados de determinados blocos dentro do modelo, tipicamente aqueles sem atenção em janela. Cada elemento da lista tem a forma `(batch_size, sequence_length, hidden_size)`. Isso é específico do SAM-HQ e não está presente no SAM base.

## SamHQModel[[transformers.SamHQModel]]

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

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

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

**Parâmetros:**

config ([SamHQConfig](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Segment Anything Model HQ (SAM-HQ) para gerar máscaras, dado uma imagem de entrada e localizações 2D e caixas delimitadoras opcionais.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](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*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor). Veja [SamImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([SamHQProcessor](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQProcessor) usa [SamImageProcessor](/docs/transformers/main/pt/model_doc/sam#transformers.SamImageProcessor) para processar imagens).

input_points (`torch.Tensor` de forma `(batch_size, num_points, 2)`) : Pontos espaciais 2D de entrada, usados pelo codificador de prompt para codificar o prompt. Geralmente, isso resulta em muito melhores resultados. Os pontos podem ser obtidos passando uma lista de listas de listas para o processador, que criará os correspondentes `torch` tensores de dimensão 4. A primeira dimensão é o tamanho do lote de imagens, a segunda dimensão é o tamanho do lote de pontos (ou seja, quantas máscaras de segmentação queremos que o modelo preveja por ponto de entrada), a terceira dimensão é o número de pontos por máscara de segmentação (é possível passar múltiplos pontos para uma única máscara) e a última dimensão são as coordenadas x (vertical) e y (horizontal) do ponto. Se um número diferente de pontos for passado para cada imagem ou para cada máscara, o processador criará pontos "PAD" que corresponderão à coordenada (0, 0), e o cálculo do embedding será ignorado para esses pontos usando os rótulos.

input_labels (`torch.LongTensor` de forma `(batch_size, point_batch_size, num_points)`) : Rótulos de entrada para os pontos, usados pelo codificador de prompt para codificar o prompt. De acordo com a implementação oficial, existem 3 tipos de rótulos  - `1`: o ponto contém o objeto de interesse - `0`: o ponto não contém o objeto de interesse - `-1`: o ponto corresponde ao fundo  Adicionamos o rótulo:  - `-10`: o ponto é um ponto de preenchimento (padding) e, portanto, deve ser ignorado pelo codificador de prompt  Os rótulos de preenchimento devem ser aplicados automaticamente pelo processador.

input_boxes (`torch.Tensor` de forma `(batch_size, num_boxes, 4)`) : Caixas de entrada para os pontos, usadas pelo codificador de prompt para codificar o prompt. Geralmente resulta em máscaras geradas muito melhores. As caixas podem ser obtidas passando uma lista de listas de listas para o processador, que gerará um tensor `torch`, com cada dimensão correspondendo, respectivamente, ao tamanho do lote de imagens, ao número de caixas por imagem e às coordenadas do ponto superior esquerdo e do ponto inferior direito da caixa. Na ordem (`x1`, `y1`, `x2`, `y2`):  - `x1`: a coordenada x do ponto superior esquerdo da caixa de entrada - `y1`: a coordenada y do ponto superior esquerdo da caixa de entrada - `x2`: a coordenada x do ponto inferior direito da caixa de entrada - `y2`: a coordenada y do ponto inferior direito da caixa de entrada

input_masks (`torch.Tensor` de forma `(batch_size, image_size, image_size)`) : o modelo SAM_HQ também aceita máscaras de segmentação como entrada. A máscara será incorporada pelo codificador de prompt para gerar uma incorporação correspondente, que será fornecida posteriormente ao decodificador de máscara. Essas máscaras precisam ser fornecidas manualmente pelo usuário e precisam ter a forma (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` de forma `(batch_size, output_channels, window_size, window_size)`) : Incorporações de imagem, usadas pelo decodificador de máscara para gerar máscaras e pontuações de iou. Para um cálculo mais eficiente em termos de memória, os usuários podem primeiro recuperar as incorporações de imagem usando o método `get_image_embeddings` e, em seguida, fornecê-las ao método `forward` em vez de fornecer os `pixel_values`.

multimask_output (`bool`, *opcional*) : Na implementação e no artigo originais, o modelo sempre produz 3 máscaras por imagem (ou por ponto / por bounding box, quando aplicável). No entanto, é possível produzir apenas uma única máscara, que corresponde à máscara "melhor", especificando `multimask_output=False`.

hq_token_only (`bool`, *opcional*, padrão `False`) : Se deve usar apenas o caminho de token HQ para a geração da máscara. Quando False, combina ambos os caminhos padrão e HQ. Isso é específico da arquitetura do SAM-HQ.

attention_similarity (`torch.Tensor`, *opcional*) : Tensor de similaridade de atenção, a ser fornecido ao decodificador de máscara para atenção guiada por alvo, caso o modelo seja usado para personalização, conforme introduzido em [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *opcional*) : Incorporação do conceito-alvo, a ser fornecida ao decodificador de máscara para prompting semântico-alvo, caso o modelo seja usado para personalização, conforme introduzido em [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`, *opcional*) : Embebidings intermediários dos blocos sem janela do codificador de visão, usados pelo SAM-HQ para melhorar a qualidade das máscaras. Obrigatório ao fornecer image_embeddings pré-computados em vez de pixel_values.

**Retorna:**

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

O método forward do [SamHQModel](/docs/transformers/main/pt/model_doc/sam_hq#transformers.SamHQModel) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

Exemplo:

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