# UPerNet

## Aperçu

Le modèle UPerNet a été proposé dans [Unified Perceptual Parsing for Scene Understanding](https://huggingface.co/papers/1807.10221) par Tete Xiao, Yingcheng Liu, Bolei Zhou, Yuning Jiang, Jian Sun. UPerNet est un cadre général permettant de segmenter efficacement une large gamme de concepts à partir d’images, en s’appuyant sur n’importe quel backbone de vision tel que [ConvNeXt](convnext) ou [Swin](swin).

L'abstract de l'article est le suivant :

*Les humains reconnaissent le monde visuel à plusieurs niveaux : nous catégorisons sans effort les scènes et détectons les objets qui s’y trouvent, tout en identifiant les textures et les surfaces de ces objets ainsi que leurs différentes parties compositionnelles. Dans cet article, nous étudions une nouvelle tâche appelée Unified Perceptual Parsing, qui exige des systèmes de vision par ordinateur de reconnaître le plus grand nombre de concepts visuels possible à partir d’une image donnée. Un cadre multitâche appelé UPerNet et une stratégie d’entraînement sont développés pour apprendre à partir d’annotations d’images hétérogènes. Nous évaluons notre cadre sur Unified Perceptual Parsing et montrons qu’il est capable de segmenter efficacement une large gamme de concepts à partir d’images. Les réseaux entraînés sont ensuite appliqués pour découvrir des connaissances visuelles dans des scènes naturelles.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/upernet_architecture.jpg"
alt="drawing" width="600"/>

 Cadre UPerNet. Tiré de l'article original.

Ce modèle a été contribué par [nielsr](https://huggingface.co/nielsr). Le code d'origine est basé sur mmsegmentation d'OpenMMLab, disponible [ici](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/models/decode_heads/uper_head.py).

## Exemples d'utilisation

UPerNet est un cadre général pour la segmentation sémantique. Il peut être utilisé avec n'importe quel backbone de vision, comme suit :

```python
from transformers import SwinConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = SwinConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

Pour utiliser un autre backbone de vision, comme [ConvNeXt](convnext), il suffit d’instancier le modèle avec le backbone approprié :

```python
from transformers import ConvNextConfig, UperNetConfig, UperNetForSemanticSegmentation

backbone_config = ConvNextConfig(out_features=["stage1", "stage2", "stage3", "stage4"])

config = UperNetConfig(backbone_config=backbone_config)
model = UperNetForSemanticSegmentation(config)
```

Notez que cela initialisera aléatoirement tous les poids du modèle.

## Ressources

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

- Des notebooks de démonstration pour UPerNet sont disponibles [ici](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UPerNet).
- [UperNetForSemanticSegmentation](/docs/transformers/v5.23.0/fr/model_doc/upernet#transformers.UperNetForSemanticSegmentation) est pris en charge par ce [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/semantic_segmentation.ipynb).
- Voir aussi : [Guide de la tâche de segmentation sémantique](../tasks/semantic_segmentation)

Si vous souhaitez soumettre une ressource pour qu'elle soit incluse ici, n'hésitez pas à ouvrir une Pull Request et nous la examinerons ! La ressource devrait idéalement démontrer quelque chose de nouveau plutôt que de dupliquer une ressource existante.

## UperNetConfig[[transformers.UperNetConfig]]

#### transformers.UperNetConfig[[transformers.UperNetConfig]]

```python
transformers.UperNetConfig(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, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, hidden_size: int = 512, initializer_range: float = 0.02, pool_scales: list[int] | tuple[int, ...] = (1, 2, 3, 6), use_auxiliary_head: bool = True, auxiliary_loss_weight: float = 0.4, auxiliary_in_channels: int | None = None, auxiliary_channels: int = 256, auxiliary_num_convs: int = 1, auxiliary_concat_input: bool = False, loss_ignore_index: int = 255)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/configuration_upernet.py#L25)

**Paramètres :**

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : La configuration du modèle de base.

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

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.

pool_scales (`tuple[int]`, *facultatif*, valeur par défaut `[1, 2, 3, 6]`) : Échelles de pooling utilisées dans le Pooling Pyramid Module appliquées à la dernière carte de caractéristiques.

use_auxiliary_head (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut utiliser une tête auxiliaire pendant l'entraînement.

auxiliary_loss_weight (`float`, *facultatif*, valeur par défaut 0,4) : Poids de la perte d'entropie croisée de la tête auxiliaire.

auxiliary_in_channels (`int`, *facultatif*, par défaut 256) : Nombre de canaux d'entrée dans la tête auxiliaire.

auxiliary_channels (`int`, *facultatif*, valeur par défaut : 256) : Nombre de canaux à utiliser dans la tête auxiliaire.

auxiliary_num_convs (`int`, *facultatif*, par défaut 1) : Nombre de couches convolutives à utiliser dans la tête auxiliaire.

auxiliary_concat_input (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut concaténer la sortie de la tête auxiliaire avec l'entrée avant la couche de classification.

loss_ignore_index (`int`, *facultatif*, valeur par défaut : 255) : L'index ignoré par la fonction de perte.

Ceci est la classe de configuration destinée à stocker la configuration d'un UpernetModel. Elle est utilisée pour instancier un modèle Upernet 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 [openmmlab/upernet-convnext-tiny](https://huggingface.co/openmmlab/upernet-convnext-tiny)

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.

Exemples :

```python
>>> from transformers import UperNetConfig, UperNetForSemanticSegmentation

>>> # Initializing a configuration
>>> configuration = UperNetConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = UperNetForSemanticSegmentation(configuration)

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

## UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

#### transformers.UperNetForSemanticSegmentation[[transformers.UperNetForSemanticSegmentation]]

```python
transformers.UperNetForSemanticSegmentation(config: UperNetConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L278)

**Paramètres :**

config ([UperNetConfig](/docs/transformers/v5.23.0/fr/model_doc/upernet#transformers.UperNetConfig)) : 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.

Cadre UperNet exploitant n’importe quel backbone de vision, par exemple pour ADE20k, CityScapes.

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.UperNetForSemanticSegmentation.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, labels: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/upernet/modeling_upernet.py#L293)

**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 [SegformerImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/segformer#transformers.SegformerImageProcessor). Voir [SegformerImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails (`processor_class` utilise [SegformerImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/segformer#transformers.SegformerImageProcessor) pour le traitement des images).

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

labels (`torch.LongTensor` de forme `(batch_size, height, width)`, *facultatif*) : Cartes de segmentation sémantique de référence pour le calcul de la perte. Les indices doivent être dans `[0, ..., config.num_labels - 1]`. Si `config.num_labels > 1`, une perte de classification est calculée (entropie croisée).

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

**Retourne :** [SemanticSegmenterOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) ou `tuple(torch.Tensor)`

Un [SemanticSegmenterOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) 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 ([UperNetConfig](/docs/transformers/v5.23.0/fr/model_doc/upernet#transformers.UperNetConfig)) et les entrées.

La méthode forward de [UperNetForSemanticSegmentation](/docs/transformers/v5.23.0/fr/model_doc/upernet#transformers.UperNetForSemanticSegmentation) 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.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de classification (ou de régression si config.num_labels==1).
- **logits** (`torch.Tensor` de forme `(batch_size, config.num_labels, logits_height, logits_width)`) -- Scores de classification pour chaque pixel.

  

  Les logits retournés n'ont pas nécessairement la même taille que les `pixel_values` passés en entrée. Cela permet d'éviter de réaliser deux interpolations et de perdre en qualité lorsqu'un utilisateur doit redimensionner les logits à la taille de l'image d'origine en post-traitement. Vous devez toujours vérifier la forme de vos logits et les redimensionner au besoin.

  
- **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, patch_size, 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, patch_size, 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.

Exemples :
```python
>>> from transformers import AutoImageProcessor, UperNetForSemanticSegmentation
>>> from PIL import Image
>>> from huggingface_hub import hf_hub_download

>>> image_processor = AutoImageProcessor.from_pretrained("openmmlab/upernet-convnext-tiny")
>>> model = UperNetForSemanticSegmentation.from_pretrained("openmmlab/upernet-convnext-tiny")

>>> filepath = hf_hub_download(
...     repo_id="hf-internal-testing/fixtures_ade20k", filename="ADE_val_00000001.jpg", repo_type="dataset"
... )
>>> image = Image.open(filepath).convert("RGB")

>>> inputs = image_processor(images=image, return_tensors="pt")

>>> outputs = model(**inputs)

>>> logits = outputs.logits  # shape (batch_size, num_labels, height, width)
>>> list(logits.shape)
[1, 150, 512, 512]
```