# UPerNet

## Visão geral

O modelo UPerNet foi proposto em [Unified Perceptual Parsing for Scene Understanding](https://huggingface.co/papers/1807.10221) por Tete Xiao, Yingcheng Liu, Bolei Zhou, Yuning Jiang, Jian Sun. O UPerNet é um framework geral para segmentar eficazmente uma ampla variedade de conceitos a partir de imagens, aproveitando qualquer backbone de visão, como [ConvNeXt](convnext) ou [Swin](swin).

O resumo do artigo é o seguinte:

*Os seres humanos reconhecem o mundo visual em múltiplos níveis: categorizamos cenas e detectamos objetos nelas com facilidade, ao mesmo tempo em que identificamos as texturas e superfícies dos objetos, bem como suas diferentes partes constitutivas. Neste artigo, estudamos uma nova tarefa chamada Unified Perceptual Parsing, que exige que os sistemas de visão computacional reconheçam o máximo possível de conceitos visuais a partir de uma imagem dada. Desenvolvemos um framework multitarefa chamado UPerNet e uma estratégia de treinamento para aprender a partir de anotações de imagem heterogêneas. Avaliamos nosso framework em Unified Perceptual Parsing e demonstramos que ele é capaz de segmentar eficazmente uma ampla gama de conceitos a partir de imagens. As redes treinadas são, em seguida, aplicadas para descobrir conhecimento visual em cenas naturais.*

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

 Framework UPerNet. Retirado do artigo original.

Este modelo foi contribuído por [nielsr](https://huggingface.co/nielsr). O código original é baseado no mmsegmentation do OpenMMLab [aqui](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/models/decode_heads/uper_head.py).

## Exemplos de uso

UPerNet é um framework geral para segmentação semântica. Ele pode ser usado com qualquer backbone de visão, da seguinte forma:

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

Para usar outro backbone de visão, como [ConvNeXt](convnext), basta instanciar o modelo com o backbone apropriado:

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

Observe que isso inicializará aleatoriamente todos os pesos do modelo.

## Recursos

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

- Os notebooks de demonstração para UPerNet podem ser encontrados [aqui](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UPerNet).
- [UperNetForSemanticSegmentation](/docs/transformers/main/pt/model_doc/upernet#transformers.UperNetForSemanticSegmentation) é suportado por este [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/semantic_segmentation.ipynb).
- Veja também: [Guia da tarefa de segmentação semântica](../tasks/semantic_segmentation)

Se você tiver interesse em enviar um recurso para ser incluído aqui, sinta-se à vontade para abrir um Pull Request e faremos a revisão! O recurso deve, idealmente, demonstrar algo novo, em vez de duplicar um recurso existente.

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

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

**Parâmetros:**

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : A configuração do modelo backbone.

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

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

pool_scales (`tuple[int]`, *opcional*, padrão `[1, 2, 3, 6]`) : Escalas de pooling usadas no Pooling Pyramid Module aplicadas ao último mapa de características.

use_auxiliary_head (`bool`, *opcional*, padrão `True`) : Se deve usar uma cabeça auxiliar durante o treinamento.

auxiliary_loss_weight (`float`, *opcional*, padrão 0.4) : Peso da perda de entropia cruzada da cabeça auxiliar.

auxiliary_in_channels (`int`, *opcional*, padrão 256) : Número de canais de entrada na cabeça auxiliar.

auxiliary_channels (`int`, *opcional*, padrão 256) : Número de canais a serem usados na cabeça auxiliar.

auxiliary_num_convs (`int`, *opcional*, padrão 1) : Número de camadas convolucionais a serem usadas na cabeça auxiliar.

auxiliary_concat_input (`bool`, *opcional*, padrão `False`) : Indica se a saída da cabeça auxiliar deve ser concatenada com a entrada antes da camada de classificação.

loss_ignore_index (`int`, *opcional*, padrão 255) : O índice que é ignorado pela função de perda.

Esta é a classe de configuração para armazenar a configuração de um UpernetModel. Ela é usada para instanciar um modelo Upernet 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 [openmmlab/upernet-convnext-tiny](https://huggingface.co/openmmlab/upernet-convnext-tiny)

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.

Exemplos:

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

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

**Parâmetros:**

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

Framework UperNet que aproveita qualquer backbone de visão, por exemplo, para ADE20k, CityScapes.

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

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

**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 [SegformerImageProcessor](/docs/transformers/main/pt/model_doc/segformer#transformers.SegformerImageProcessor). Veja [SegformerImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [SegformerImageProcessor](/docs/transformers/main/pt/model_doc/segformer#transformers.SegformerImageProcessor) para processar imagens).

output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes.

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

labels (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Mapas de segmentação semântica de verdade para o cálculo da perda. Os índices devem estar em `[0, ..., config.num_labels - 1]`. Se `config.num_labels > 1`, uma perda de classificação é calculada (Cross-Entropy).

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

**Retorna:** [SemanticSegmenterOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) ou `tuple(torch.Tensor)`

Um [SemanticSegmenterOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) 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 ([UperNetConfig](/docs/transformers/main/pt/model_doc/upernet#transformers.UperNetConfig)) e das entradas.

O método forward de [UperNetForSemanticSegmentation](/docs/transformers/main/pt/model_doc/upernet#transformers.UperNetForSemanticSegmentation) substitui 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.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de classificação (ou de regressão se config.num_labels==1).
- **logits** (`torch.Tensor` de forma `(batch_size, config.num_labels, logits_height, logits_width)`) -- Pontuações de classificação para cada pixel.

  

  Os logits retornados não necessariamente têm o mesmo tamanho que os `pixel_values` passados como entradas. Isso é para evitar realizar duas interpolações e perder alguma qualidade quando um usuário precisa redimensionar os logits para o tamanho da imagem original como pós-processamento. Você deve sempre verificar a forma dos seus logits e redimensioná-los conforme necessário.

  
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, patch_size, 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, patch_size, 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.

Exemplos:
```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]
```