# UPerNet

## Ikhtisar

Model UPerNet diusulkan dalam [Unified Perceptual Parsing for Scene Understanding](https://huggingface.co/papers/1807.10221) oleh Tete Xiao, Yingcheng Liu, Bolei Zhou, Yuning Jiang, Jian Sun. UPerNet adalah kerangka kerja umum untuk secara efektif melakukan segmentasi berbagai konsep dari gambar, dengan memanfaatkan backbone visi apa pun seperti [ConvNeXt](convnext) atau [Swin](swin).

Abstrak dari makalah tersebut adalah sebagai berikut:

*Manusia mengenali dunia visual pada beberapa tingkatan: kita dengan mudah mengategorikan adegan dan mendeteksi objek di dalamnya, sekaligus mengidentifikasi tekstur dan permukaan objek beserta bagian-bagian komposisional yang berbeda. Dalam makalah ini, kami mempelajari tugas baru yang disebut Unified Perceptual Parsing, yang mensyaratkan sistem visi mesin untuk mengenali sebanyak mungkin konsep visual dari sebuah gambar. Kerangka kerja multi-tugas bernama UPerNet dan strategi pelatihan dikembangkan untuk belajar dari anotasi gambar yang heterogen. Kami melakukan benchmark kerangka kerja kami pada Unified Perceptual Parsing dan menunjukkan bahwa kerangka kerja ini mampu melakukan segmentasi berbagai konsep dari gambar secara efektif. Jaringan yang telah dilatih kemudian diterapkan untuk menemukan pengetahuan visual dalam adegan alami.*

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

 Framework UPerNet. Diambil dari paper aslinya.

Model ini disumbangkan oleh [nielsr](https://huggingface.co/nielsr). Kode aslinya didasarkan pada mmsegmentation dari OpenMMLab [di sini](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/models/decode_heads/uper_head.py).

## Contoh penggunaan

UPerNet adalah kerangka kerja umum untuk segmentasi semantik. Kerangka kerja ini dapat digunakan dengan backbone visi apa pun, seperti berikut:

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

Untuk menggunakan backbone visi lain, seperti [ConvNeXt](convnext), cukup instansiasi model dengan backbone yang sesuai:

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

Perhatikan bahwa ini akan menginisialisasi secara acak semua bobot dari model.

## Sumber daya

Daftar sumber resmi Hugging Face dan komunitas (ditandai dengan 🌎) untuk membantu Anda memulai dengan UPerNet.

- Notebook demo untuk UPerNet dapat ditemukan [di sini](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/UPerNet).
- [UperNetForSemanticSegmentation](/docs/transformers/main/id/model_doc/upernet#transformers.UperNetForSemanticSegmentation) didukung oleh [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/semantic_segmentation.ipynb) ini.
- Lihat juga: [Panduan tugas segmentasi semantik](../tasks/semantic_segmentation)

Jika Anda tertarik untuk mengirimkan sumber daya agar disertakan di sini, silakan buka Pull Request dan kami akan meninjaunya! Sumber daya tersebut sebaiknya mendemonstrasikan sesuatu yang baru, bukan menduplikasi sumber daya yang sudah ada.

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

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

**Parameter:**

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opsional*) : Konfigurasi dari model backbone.

hidden_size (`int`, *opsional*, defaultnya `512`) : Dimensi dari representasi tersembunyi.

initializer_range (`float`, *opsional*, defaultnya `0.02`) : Deviasi standar dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

pool_scales (`tuple[int]`, *opsional*, defaultnya `[1, 2, 3, 6]`) : Skala pooling yang digunakan dalam Pooling Pyramid Module yang diterapkan pada peta fitur terakhir.

use_auxiliary_head (`bool`, *opsional*, defaultnya `True`) : Apakah akan menggunakan kepala bantu selama pelatihan.

auxiliary_loss_weight (`float`, *opsional*, default 0.4) : Bobot dari cross-entropy loss dari auxiliary head.

auxiliary_in_channels (`int`, *opsional*, default 256) : Jumlah saluran input di kepala bantu.

auxiliary_channels (`int`, *opsional*, default 256) : Jumlah channel yang digunakan di kepala bantu.

auxiliary_num_convs (`int`, *opsional*, default 1) : Jumlah lapisan konvolusional yang digunakan di kepala bantu.

auxiliary_concat_input (`bool`, *opsional*, defaultnya `False`) : Apakah akan menggabungkan output dari kepala bantu dengan input sebelum lapisan klasifikasi.

loss_ignore_index (`int`, *opsional*, defaultnya 255) : Indeks yang diabaikan oleh fungsi loss.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari UpernetModel. Kelas ini digunakan untuk membuat instans model Upernet sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [openmmlab/upernet-convnext-tiny](https://huggingface.co/openmmlab/upernet-convnext-tiny)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

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

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

**Parameter:**

config ([UperNetConfig](/docs/transformers/main/id/model_doc/upernet#transformers.UperNetConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Framework UperNet yang memanfaatkan backbone visi apa pun, misalnya untuk ADE20k, CityScapes.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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

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

**Parameter:**

pixel_values (`torch.Tensor` dengan bentuk `(batch_size, num_channels, image_size, image_size)`, *opsional*) : Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan [SegformerImageProcessor](/docs/transformers/main/id/model_doc/segformer#transformers.SegformerImageProcessor). Lihat [SegformerImageProcessor.__call__()](/docs/transformers/main/id/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) untuk detailnya (`processor_class` menggunakan [SegformerImageProcessor](/docs/transformers/main/id/model_doc/segformer#transformers.SegformerImageProcessor) untuk memproses gambar).

output_attentions (`bool`, *opsional*) : Apakah akan mengembalikan tensor perhatian dari semua lapisan perhatian. Lihat `attentions` di bawah tensor yang dikembalikan untuk detail lebih lanjut.

output_hidden_states (`bool`, *opsional*) : Apakah akan mengembalikan hidden states dari semua lapisan. Lihat `hidden_states` di bawah tensor yang dikembalikan untuk detail lebih lanjut.

labels (`torch.LongTensor` dengan bentuk `(batch_size, height, width)`, *opsional*) : Peta segmentasi semantik ground truth untuk menghitung loss. Indeks harus berada dalam `[0, ..., config.num_labels - 1]`. Jika `config.num_labels > 1`, loss klasifikasi dihitung (Cross-Entropy).

return_dict (`bool`, *opsional*) : Apakah akan mengembalikan [ModelOutput](/docs/transformers/main/id/main_classes/output#transformers.utils.ModelOutput) alih-alih tuple biasa.

**Mengembalikan:** [SemanticSegmenterOutput](/docs/transformers/main/id/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) atau `tuple(torch.Tensor)`

Sebuah [SemanticSegmenterOutput](/docs/transformers/main/id/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) atau tuple dari `torch.Tensor` (jika `return_dict=False` diteruskan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi ([UperNetConfig](/docs/transformers/main/id/model_doc/upernet#transformers.UperNetConfig)) dan input.

Metode forward dari [UperNetForSemanticSegmentation](/docs/transformers/main/id/model_doc/upernet#transformers.UperNetForSemanticSegmentation) menimpa metode khusus `__call__`.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance `Module` setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

- **loss** (`torch.Tensor` dengan bentuk `(1,)`, *opsional*, dikembalikan saat `labels` disediakan) -- Loss klasifikasi (atau regresi jika config.num_labels==1).
- **logits** (`torch.Tensor` dengan bentuk `(batch_size, config.num_labels, logits_height, logits_width)`) -- Skor klasifikasi untuk setiap piksel.

  

  Logits yang dikembalikan tidak selalu memiliki ukuran yang sama dengan `pixel_values` yang diberikan sebagai input. Hal ini dilakukan untuk menghindari dua kali interpolasi dan kehilangan kualitas ketika pengguna perlu mengubah ukuran logits ke ukuran gambar asli sebagai pascapemrosesan. Anda harus selalu memeriksa bentuk logits Anda dan mengubah ukurannya sesuai kebutuhan.

  
- **hidden_states** (`tuple(torch.Tensor)`, *opsional*, dikembalikan saat `output_hidden_states=True` dilewatkan atau saat `config.output_hidden_states=True`) -- Tuple dari `torch.Tensor` (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk `(batch_size, patch_size, hidden_size)`.

  Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
- **attentions** (`tuple(torch.Tensor)`, *opsional*, dikembalikan ketika `output_attentions=True` dilewatkan atau ketika `config.output_attentions=True`) -- Tuple dari `torch.Tensor` (satu untuk setiap layer) dengan bentuk `(batch_size, num_heads, patch_size, sequence_length)`.

  Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala self-attention.

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