# SAM-HQ

## Aperçu

SAM-HQ (High-Quality Segment Anything Model) a été proposé dans [Segment Anything in High Quality](https://huggingface.co/papers/2306.01567) par Lei Ke, Mingqiao Ye, Martin Danelljan, Yifan Liu, Yu-Wing Tai, Chi-Keung Tang, Fisher Yu.

Le modèle est une amélioration du modèle SAM d'origine qui produit des masques de segmentation de qualité nettement supérieure tout en conservant la conception promptable, l'efficacité et la généralisation zéro-shot d'origine de SAM.

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

SAM-HQ introduit plusieurs améliorations clés par rapport au modèle SAM original :

1. Jeton de sortie de haute qualité : un jeton apprenable injecté dans le décodeur de masque de SAM pour une prédiction de masque de meilleure qualité
2. Fusion de caractéristiques globales et locales : combine les caractéristiques issues de différentes étapes du modèle pour améliorer les détails du masque
3. Données d'entraînement : Utilise un jeu de données soigneusement sélectionné de 44K masques de haute qualité au lieu de SA-1B
4. Efficacité : n'ajoute que 0,5 % de paramètres supplémentaires tout en améliorant considérablement la qualité du masque
5. Capacité en zéro-shot : conserve la forte performance en zéro-shot de SAM tout en améliorant la précision

L'abstract de l'article est le suivant :

*Le récent Segment Anything Model (SAM) représente un grand pas en avant dans le passage à l’échelle des modèles de segmentation, offrant de puissantes capacités en zéro tirage et un promptage flexible. Bien qu’il ait été entraîné sur 1,1 milliard de masques, la qualité de prédiction des masques de SAM reste insuffisante dans de nombreux cas, en particulier lorsqu’il s’agit d’objets aux structures complexes. Nous proposons HQ-SAM, qui dote SAM de la capacité à segmenter précisément n’importe quel objet, tout en conservant la conception promptable, l’efficacité et la généralisabilité en zéro tirage d’origine de SAM. Notre conception soignée réutilise et préserve les poids du modèle pré-entraîné de SAM, n’ajoutant que des paramètres et des calculs minimaux. Nous concevons un jeton de sortie de haute qualité apprenable, injecté dans le décodeur de masques de SAM et chargé de prédire le masque de haute qualité. Plutôt que de l’appliquer uniquement aux caractéristiques du décodeur de masques, nous les fusionnons d’abord avec les caractéristiques précoces et finales du ViT pour améliorer les détails du masque. Pour entraîner les paramètres apprenables introduits, nous composons un jeu de données de 44 K masques fins à partir de plusieurs sources. HQ-SAM n’est entraîné que sur le jeu de données de 44 k masques introduit, ce qui ne prend que 4 heures sur 8 GPU.*

Astuces :

- SAM-HQ génère des masques de meilleure qualité que le modèle SAM original, en particulier pour les objets aux structures complexes et aux détails fins
- Le modèle prédit des masques binaires avec des contours plus précis et un meilleur traitement des structures fines
- Comme SAM, le modèle obtient de meilleurs résultats avec des points 2D en entrée et/ou des boîtes englobantes en entrée
- Vous pouvez indiquer plusieurs points pour la même image et prédire un seul masque de haute qualité
- Le modèle conserve les capacités de généralisation en zéro tir de SAM
- SAM-HQ n'ajoute que ~0,5 % de paramètres supplémentaires par rapport à SAM
- Le fine-tuning du modèle n'est pas encore pris en charge

Ce modèle a été contribué par [sushmanth](https://huggingface.co/sushmanth). Le code d'origine peut être trouvé [ici](https://github.com/SysCV/SAM-HQ).

Voici un exemple montrant comment exécuter la génération de masques à partir d'une image et d'un point 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
```

Vous pouvez également traiter vos propres masques en parallèle des images d’entrée dans le processeur, afin de les transmettre au modèle :

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

## Ressources

Une liste de ressources officielles Hugging Face et de la communauté (indiquées par 🌎) pour vous aider à démarrer avec SAM-HQ :

- Cahier de démonstration pour l'utilisation du modèle (bientôt disponible)
- Implémentation de l'article et code : [Dépôt GitHub 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)
```

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

**Paramètres :**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone visuel.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *facultatif*) : Dictionnaire des options de configuration utilisées pour initialiser [SamHQPromptEncoderConfig](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *facultatif*) : Dictionnaire des options de configuration utilisées pour initialiser [SamHQMaskDecoderConfig](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle.

Ceci est la classe de configuration destinée à stocker la configuration d'un SamHQModel. Elle est utilisée pour instancier un modèle Sam Hq en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

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

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

**Paramètres :**

hidden_size (`int`, *facultatif*, par défaut `768`) : Dimension des représentations cachées.

output_channels (`int`, *facultatif*, valeur par défaut : 256) : Dimensionnalité des canaux de sortie dans le Patch Encoder.

num_hidden_layers (`int`, *facultatif*, par défaut `12`) : Nombre de couches cachées dans le décodeur Transformer.

num_attention_heads (`int`, *facultatif*, valeur par défaut `12`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

num_channels (`int`, *facultatif*, par défaut `3`) : Le nombre de canaux d'entrée.

image_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `1024`) : La taille (résolution) de chaque image.

patch_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `16`) : La taille (résolution) de chaque patch.

hidden_act (`str`, *facultatif*, par défaut `gelu`) : La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche.

attention_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout appliqué aux probabilités d'attention.

initializer_range (`float`, *facultatif*, valeur par défaut `1e-10`) : L'écart-type de truncated_normal_initializer pour l'initialisation de toutes les matrices de poids.

qkv_bias (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut ajouter un biais aux requêtes, clés et valeurs.

mlp_ratio (`float`, *facultatif*, par défaut `4.0`) : Ratio de la dimension cachée du MLP par rapport à la dimension d'embedding.

use_abs_pos (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut utiliser des embeddings de position absolue.

use_rel_pos (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut utiliser l'encodage de position relative.

window_size (`int`, *facultatif*, valeur par défaut 14) : Taille de la fenêtre pour la position relative.

global_attn_indexes (`list[int]`, *facultatif*, par défaut `[2, 5, 8, 11]`) : Les index des couches d'attention globale.

num_pos_feats (`int`, *facultatif*, valeur par défaut 128) : La dimension de l'incorporation de position.

mlp_dim (`int`, *facultatif*) : La dimensionnalité de la couche MLP dans l'encodeur Transformer. Si `None`, la valeur par défaut est `mlp_ratio * hidden_size`.

Ceci est la classe de configuration destinée à stocker la configuration d'un SamHQModel. Elle est utilisée pour instancier un modèle Sam Hq en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

hidden_size (`int`, *facultatif*, par défaut `256`) : Dimension des représentations cachées.

hidden_act (`str`, *facultatif*, par défaut `relu`) : Fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

mlp_dim (`int`, *facultatif*, valeur par défaut 2048) : Dimension de la couche « intermédiaire » (c.-à-d. feed-forward) dans l'encodeur Transformer.

num_hidden_layers (`int`, *facultatif*, valeur par défaut `2`) : Nombre de couches cachées dans le décodeur Transformer.

num_attention_heads (`int`, *facultatif*, valeur par défaut `8`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

attention_downsample_rate (`int`, *facultatif*, valeur par défaut : 2) : Le taux de sous-échantillonnage de la couche d'attention.

num_multimask_outputs (`int`, *facultatif*, valeur par défaut : 3) : Le nombre de sorties du module `SamMaskDecoder`. Dans l'article Segment Anything, cette valeur est fixée à 3.

iou_head_depth (`int`, *facultatif*, valeur par défaut : 3) : Le nombre de couches dans le module de tête IoU.

iou_head_hidden_dim (`int`, *facultatif*, par défaut 256) : La dimension des états cachés dans le module de tête IoU.

layer_norm_eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche.

vit_dim (`int`, *facultatif*, valeur par défaut 768) : Dimensionnalité du Vision Transformer (ViT) utilisé dans le module `SamHQMaskDecoder`.

Ceci est la classe de configuration destinée à stocker la configuration d'un SamHQModel. Elle est utilisée pour instancier un modèle Sam Hq en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

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

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

**Paramètres :**

hidden_size (`int`, *facultatif*, par défaut `256`) : Dimension des représentations cachées.

image_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `1024`) : La taille (résolution) de chaque image.

patch_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `16`) : La taille (résolution) de chaque patch.

mask_input_channels (`int`, *facultatif*, valeur par défaut 16) : Le nombre de canaux à transmettre au module `MaskDecoder`.

num_point_embeddings (`int`, *facultatif*, valeur par défaut : 4) : Le nombre d'embeddings de points à utiliser.

hidden_act (`str`, *facultatif*, par défaut `gelu`) : La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche.

Ceci est la classe de configuration destinée à stocker la configuration d'un SamHQModel. Elle est utilisée pour instancier un modèle Sam Hq en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

## SamHQProcessor[[transformers.SamHQProcessor]]

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

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

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam_hq/processing_sam_hq.py#L94)

**Paramètres :**

image_processor (`SamImageProcessor`) : le processeur d'images est une entrée obligatoire.

Construit un SamHQProcessor qui encapsule un processeur d'image dans un processeur unique.

[SamHQProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor) propose toutes les fonctionnalités de [SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor). Consultez [~SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor) pour plus d’informations.

#### __appel__[[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, segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, input_points: NestedList | torch.Tensor | None = None, input_labels: NestedList | int | torch.Tensor | None = None, input_boxes: NestedList | torch.Tensor | None = None, **kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam_hq/processing_sam_hq.py#L108)

**Paramètres :**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *facultatif*) : Image à prétraiter. Attend une image unique ou un lot d'images dont les valeurs de pixels sont comprises entre 0 et 255. Si vous transmettez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissez `do_rescale=False`.

segmentation_maps (`ImageInput`, *facultatif*) : Cartes de segmentation de référence à traiter avec les images d'entrée. Ces cartes sont utilisées à des fins d'entraînement ou d'évaluation et sont redimensionnées et normalisées pour correspondre aux dimensions des images traitées.

input_points (`NestedList`, *facultatif*) : Points d'entrée pour la segmentation basée sur des prompts. Doit être une liste imbriquée avec la structure `[image_level, object_level, point_level, [x, y]]` où chaque point est spécifié par des coordonnées `[x, y]` dans l'espace de l'image d'origine. Les points sont normalisés à la taille de l'image cible avant d'être transmis au modèle.

input_labels (`NestedList`, *facultatif*) : Étiquettes pour les points d'entrée, indiquant si chaque point est un point au premier plan (1) ou en arrière-plan (0). Doit être une liste imbriquée avec la structure `[image_level, object_level, point_level]`. Doit avoir la même structure que `input_points` (à l'exception de la dimension des coordonnées).

input_boxes (`NestedList`, *facultatif*) : Boîtes englobantes pour la segmentation basée sur des prompts. Doit être une liste imbriquée avec la structure `[image_level, box_level, [x1, y1, x2, y2]]` où chaque boîte est spécifiée par les coordonnées `[x1, y1, x2, y2]` dans l'espace de l'image d'origine. Les boîtes sont normalisées à la taille de l'image cible avant d'être transmises au modèle.

segmentation_maps (`ImageInput`, *kwargs*, *facultatif*) : Obsolète, passez directement en tant que `segmentation_maps` à [SamHQProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor.__call__) à la place. Cartes de segmentation de référence à traiter avec les images d'entrée. Ces cartes sont utilisées à des fins d'entraînement ou d'évaluation et sont redimensionnées et normalisées pour correspondre aux dimensions de l'image traitée.

input_points (`NestedList`, *kwargs*, *facultatif*) : Déprécié, passez directement en tant que `input_points` à [SamHQProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor.__call__) à la place. Points d'entrée pour la segmentation basée sur des prompts. Doit être une liste imbriquée avec la structure `[image_level, object_level, point_level, [x, y]]` où chaque point est spécifié par des coordonnées `[x, y]` dans l'espace de l'image d'origine. Les points sont normalisés à la taille de l'image cible avant d'être transmis au modèle.

input_labels (`NestedList`, *kwargs*, *facultatif*) : Obsolète, passez directement en tant que `input_labels` à [SamHQProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor.__call__) à la place. Étiquettes pour les points d'entrée, indiquant si chaque point est un point de premier plan (1) ou d'arrière-plan (0). Doit être une liste imbriquée avec la structure `[image_level, object_level, point_level]`. Doit avoir la même structure que `input_points` (à l'exception de la dimension des coordonnées).

input_boxes (`NestedList`, *kwargs*, *optionnel*) : Déprécié, passez directement en tant que `input_boxes` à [SamHQProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor.__call__) à la place. Boîtes englobantes pour la segmentation basée sur des prompts. Doit être une liste imbriquée avec la structure `[image_level, box_level, [x1, y1, x2, y2]]` où chaque boîte est spécifiée par les coordonnées `[x1, y1, x2, y2]` dans l'espace de l'image d'origine. Les boîtes sont normalisées à la taille de l'image cible avant d'être transmises au modèle.

point_pad_value (`int`, *kwargs*, *facultatif*, valeur par défaut `None`) : Obsolète, utilisez `SamHQProcessorKwargs.point_pad_value` à la place. La valeur utilisée pour le bourrage des points d'entrée lors du groupement de séquences de longueurs différentes. Cette valeur marque les positions bourrées et est conservée lors de la normalisation des coordonnées afin de distinguer les points réels du bourrage. Si `None`, la valeur de bourrage par défaut de la configuration du processeur est utilisée.

mask_size (`dict[str, *kwargs*, int]`, *facultatif*) : Dictionnaire spécifiant la taille de la cible du masque, avec les clés `"height"` et `"width"`. Cela détermine la résolution des masques de segmentation de sortie générés par le modèle.

mask_pad_size (`dict[str, *kwargs*, int]`, *facultatif*) : Dictionnaire spécifiant la taille de bourrage pour les masques, avec les clés `"height"` et `"width"`. Il est utilisé lors du regroupement de masques de tailles différentes afin de garantir des dimensions cohérentes.

return_mm_token_type_ids (`bool`, *kwargs*) : Indique s'il faut retourner les identifiants de type de jeton multimodal indiquant les positions des jetons de substitution multimodaux.

return_text_replacement_offsets (`bool`, *kwargs*) : Indique s'il faut retourner les décalages de caractères pour chaque emplacement multimodal et son remplacement.

point_pad_value (`int`, *kwargs*, *facultatif*, valeur par défaut `None`) : La valeur utilisée pour rembour les points d'entrée lors du regroupement de séquences de longueurs différentes. Cette valeur marque les positions rembourdies et est conservée lors de la normalisation des coordonnées afin de distinguer les points réels du rembourrage.

return_tensors (`str` ou [TensorType](/docs/transformers/v5.23.0/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs d'un framework particulier. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/fr/main_classes/processors#transformers.ProcessingKwargs), *facultatif*) : Options de traitement supplémentaires pour chaque modalité (texte, images, vidéos, audio). Les paramètres spécifiques au modèle sont répertoriés ci-dessus ; consultez la classe TypedDict pour la liste complète des arguments pris en charge.

**Retourne :** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *facultatif*) -- Dictionnaire de listes/tableaux/tenseurs renvoyé par les méthodes __call__/pad (« input_values », « attention_mask », etc.).
- **tensor_type** (`Union[None, str, TensorType]`, *facultatif*) -- Vous pouvez spécifier un tensor_type ici pour convertir les listes d'entiers en tenseurs PyTorch/Numpy lors de l'initialisation.
- **skip_tensor_conversion** (`list[str]` ou `set[str]`, *facultatif*) -- Liste ou ensemble de clés qui ne doivent PAS être converties en tenseurs, même lorsque `tensor_type` est spécifié.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

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

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

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

**Paramètres :**

config ([SamHQVisionConfig](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQVisionConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle de vision de SamHQ, sans aucune tête ni projection au-dessus.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

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

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d’entrée. Les valeurs des pixels peuvent être obtenues à l’aide de [SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor). Voir [SamImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails ([SamHQProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor) utilise [SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor) pour le traitement des images).

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

Un `SamHQVisionEncoderOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([SamHQConfig](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQConfig)) et les entrées.

La méthode forward du modèle [SamHQVisionModel](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQVisionModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **image_embeds** (`torch.Tensor` de forme `(batch_size, output_dim)` *facultatif* renvoyé lorsque le modèle est initialisé avec `with_projection=True`) -- Les embeddings d'image obtenus en appliquant la couche de projection au pooler_output.
- **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche du modèle.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
- **attentions** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pondérations des attentions après le softmax d'attention, utilisées pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **intermediate_embeddings** (`list(torch.Tensor)`, *facultatif*) -- Une liste d'embeddings intermédiaires collectés à partir de certains blocs du modèle, généralement ceux sans attention fenêtrée. Chaque élément de la liste a la forme `(batch_size, sequence_length, hidden_size)`. Cela est spécifique à SAM-HQ et n'est pas présent dans SAM de base.

## SamHQModel[[transformers.SamHQModel]]

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

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

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

**Paramètres :**

config ([SamHQConfig](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Segment Anything Model HQ (SAM-HQ) pour générer des masques, à partir d'une image d'entrée et de localisations 2D et de boîtes englobantes facultatives.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d’entrée. Les valeurs des pixels peuvent être obtenues à l’aide de [SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor). Voir [SamImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails ([SamHQProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQProcessor) utilise [SamImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam#transformers.SamImageProcessor) pour le traitement des images).

input_points (`torch.Tensor` de forme `(batch_size, num_points, 2)`) : Points spatiaux 2D en entrée, utilisés par l'encodeur de prompt pour encoder le prompt. Produit généralement des résultats nettement meilleurs. Les points peuvent être obtenus en transmettant une liste de listes de listes au processeur, qui créera les tenseurs `torch` correspondants de dimension 4. La première dimension correspond à la taille du lot d'images, la deuxième à la taille du lot de points (c'est-à-dire le nombre de masques de segmentation que le modèle doit prédire par point d'entrée), la troisième au nombre de points par masque de segmentation (il est possible de transmettre plusieurs points pour un seul masque), et la dernière aux coordonnées x (verticale) et y (horizontale) du point. Si un nombre différent de points est transmis pour chaque image ou pour chaque masque, le processeur créera des points « PAD » correspondant à la coordonnée (0, 0), et le calcul de l'embedding sera ignoré pour ces points à l'aide des étiquettes.

input_labels (`torch.LongTensor` de forme `(batch_size, point_batch_size, num_points)`) : Étiquettes d'entrée pour les points, utilisées par l'encodeur de prompt pour encoder le prompt. Selon l'implémentation officielle, il existe 3 types d'étiquettes : `1` : le point contient l'objet d'intérêt ; `0` : le point ne contient pas l'objet d'intérêt ; `-1` : le point correspond à l'arrière-plan. Nous avons ajouté l'étiquette : `-10` : le point est un point de bourrage (padding) et doit donc être ignoré par l'encodeur de prompt. Les étiquettes de bourrage doivent être gérées automatiquement par le processeur.

input_boxes (`torch.Tensor` de forme `(batch_size, num_boxes, 4)`) : Boîtes d'entrée pour les points, utilisées par l'encodeur de prompt pour encoder le prompt. Produit généralement des masques générés nettement meilleurs. Les boîtes peuvent être obtenues en transmettant une liste de listes de listes au processeur, qui générera un tenseur `torch`, chaque dimension correspondant respectivement à la taille du lot d'images, au nombre de boîtes par image et aux coordonnées du point en haut à gauche et du point en bas à droite de la boîte. Dans l'ordre (`x1`, `y1`, `x2`, `y2`) : - `x1` : la coordonnée x du point en haut à gauche de la boîte d'entrée - `y1` : la coordonnée y du point en haut à gauche de la boîte d'entrée - `x2` : la coordonnée x du point en bas à droite de la boîte d'entrée - `y2` : la coordonnée y du point en bas à droite de la boîte d'entrée

input_masks (`torch.Tensor` de forme `(batch_size, image_size, image_size)`) : le modèle SAM_HQ accepte également des masques de segmentation en entrée. Le masque sera intégré par l’encodeur de prompt pour générer un embedding correspondant, qui sera ensuite transmis au décodeur de masque. Ces masques doivent être fournis manuellement par l’utilisateur et doivent être de forme (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` de forme `(batch_size, output_channels, window_size, window_size)`) : embeddings d’image, utilisés par le décodeur de masque pour générer les masques et les scores iou. Pour un calcul plus efficace en mémoire, les utilisateurs peuvent d’abord récupérer les embeddings d’image à l’aide de la méthode `get_image_embeddings`, puis les transmettre à la méthode `forward` au lieu de transmettre les `pixel_values`.

multimask_output (`bool`, *facultatif*) : Dans l’implémentation et l’article originaux, le modèle produit toujours 3 masques par image (ou par point / par boîte englobante le cas échéant). Il est toutefois possible de n’en produire qu’un seul, correspondant au masque « optimal », en spécifiant `multimask_output=False`.

hq_token_only (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut utiliser uniquement le chemin de jeton HQ pour la génération du masque. Si la valeur est False, les chemins standard et HQ sont combinés. Cette option est propre à l'architecture de SAM-HQ.

attention_similarity (`torch.Tensor`, *facultatif*) : Tenseur de similarité d'attention, à fournir au décodeur de masque pour une attention guidée par la cible lorsque le modèle est utilisé pour la personnalisation, comme introduit dans [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *facultatif*) : Embedding du concept cible, à fournir au décodeur de masque pour le prompting sémantique de la cible dans le cas où le modèle est utilisé pour la personnalisation, comme introduit dans [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`, *facultatif*) : Embeddings intermédiaires issus des blocs non fenêtrés de l'encodeur visuel, utilisés par SAM-HQ pour améliorer la qualité des masques. Obligatoire lors de la fourniture d'image_embeddings précalculés au lieu de pixel_values.

**Retourne :**

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

La méthode forward de [SamHQModel](/docs/transformers/v5.23.0/fr/model_doc/sam_hq#transformers.SamHQModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

Exemple :

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

