# SAM-HQ

## Ikhtisar

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

Model ini merupakan peningkatan dari model SAM asli yang menghasilkan mask segmentasi dengan kualitas yang jauh lebih tinggi sambil mempertahankan desain promptable, efisiensi, dan kemampuan generalisasi zero-shot asli dari SAM.

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

SAM-HQ memperkenalkan beberapa peningkatan utama dibandingkan model SAM asli:

1. Token Output Berkualitas Tinggi: Token yang dapat dipelajari (learnable) yang disuntikkan ke dalam dekode masker SAM untuk prediksi masker dengan kualitas yang lebih tinggi
2. Fusi Fitur Global-Lokal: Menggabungkan fitur dari berbagai tahap model untuk meningkatkan detail mask
3. Data Pelatihan: Menggunakan dataset yang dikurasi dengan cermat berisi 44K mask berkualitas tinggi, bukan SA-1B
4. Efisiensi: Hanya menambahkan 0,5% parameter tambahan sambil secara signifikan meningkatkan kualitas mask
5. Kemampuan Zero-shot: Mempertahankan kinerja zero-shot yang kuat dari SAM sambil meningkatkan akurasi

Abstrak dari makalah tersebut adalah sebagai berikut:

*Segment Anything Model (SAM) yang baru-baru ini dirilis merupakan lompatan besar dalam memperluas skala model segmentasi, memungkinkan kemampuan zero-shot yang kuat dan prompting yang fleksibel. Meskipun dilatih dengan 1,1 miliar mask, kualitas prediksi mask SAM masih kurang dalam banyak kasus, terutama ketika berurusan dengan objek yang memiliki struktur rumit. Kami mengusulkan HQ-SAM, yang membekali SAM dengan kemampuan untuk mensegmentasikan objek apa pun secara akurat, sambil mempertahankan desain promptable, efisiensi, dan generalisasi zero-shot asli SAM. Desain kami yang cermat menggunakan ulang dan mempertahankan bobot model terlatih SAM, sambil hanya memperkenalkan parameter dan komputasi tambahan yang minimal. Kami merancang High-Quality Output Token yang dapat dipelajari, yang disuntikkan ke dalam mask decoder SAM dan bertanggung jawab untuk memprediksi mask berkualitas tinggi. Alih-alih hanya menerapkannya pada fitur mask-decoder, kami terlebih dahulu menggabungkannya dengan fitur ViT awal dan akhir untuk detail mask yang lebih baik. Untuk melatih parameter yang dapat dipelajari yang kami perkenalkan, kami menyusun dataset berisi 44K mask bergranularitas tinggi dari beberapa sumber. HQ-SAM hanya dilatih pada dataset 44k mask yang diperkenalkan, yang hanya membutuhkan waktu 4 jam pada 8 GPU.*

Tips:

- SAM-HQ menghasilkan mask dengan kualitas yang lebih tinggi daripada model SAM asli, terutama untuk objek dengan struktur yang rumit dan detail yang halus
- Model memprediksi masker biner dengan batas yang lebih akurat dan penanganan struktur tipis yang lebih baik
- Seperti SAM, model ini memberikan hasil yang lebih baik dengan input titik 2D dan/atau kotak pembatas (bounding box) sebagai input.
- Anda dapat memberikan prompt untuk beberapa titik pada gambar yang sama dan memprediksi satu mask berkualitas tinggi
- Model ini mempertahankan kemampuan generalisasi zero-shot SAM
- SAM-HQ hanya menambahkan sekitar 0,5% parameter tambahan dibandingkan SAM
- Fine-tuning model belum didukung

Model ini disumbangkan oleh [sushmanth](https://huggingface.co/sushmanth). Kode aslinya dapat ditemukan [di sini](https://github.com/SysCV/SAM-HQ).

Berikut adalah contoh cara menjalankan pembuatan mask yang diberikan sebuah gambar dan titik 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
```

Anda juga dapat memproses mask Anda sendiri bersama dengan gambar input di dalam processor untuk diteruskan ke model:

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

## Sumber daya

Berikut adalah daftar sumber resmi Hugging Face dan komunitas (ditandai dengan 🌎) untuk membantu Anda memulai dengan SAM-HQ:

- Notebook demo untuk menggunakan model (segera hadir)
- Implementasi paper dan kode: [Repositori 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)
```

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

**Parameter:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opsional*) : Objek config atau dictionary dari vision backbone.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *opsional*) : Kamus opsi konfigurasi yang digunakan untuk menginisialisasi [SamHQPromptEncoderConfig](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *optional*) : Kamus opsi konfigurasi yang digunakan untuk menginisialisasi [SamHQMaskDecoderConfig](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

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

tie_word_embeddings (`bool`, *opsional*, defaultnya `True`) : Apakah mengikat embedding bobot sesuai dengan pemetaan `tied_weights_keys` model.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari SamHQModel. Kelas ini digunakan untuk membuat instans model Sam Hq berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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.

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

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

**Parameter:**

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

output_channels (`int`, *opsional*, default 256) : Dimensi dari kanal output di Patch Encoder.

num_hidden_layers (`int`, *opsional*, defaultnya `12`) : Jumlah lapisan tersembunyi dalam decoder Transformer.

num_attention_heads (`int`, *opsional*, defaultnya `12`) : Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer.

num_channels (`int`, *opsional*, default `3`) : Jumlah saluran input.

image_size (`Union[int, list[int], tuple[int, int]]`, *opsional*, defaultnya `1024`) : Ukuran (resolusi) dari setiap gambar.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opsional*, defaultnya `16`) : Ukuran (resolusi) dari setiap patch.

hidden_act (`str`, *opsional*, defaultnya `gelu`) : Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, `"gelu"`, `"relu"`, `"silu"`, dan sebagainya.

layer_norm_eps (`float`, *opsional*, defaultnya `1e-06`) : Epsilon yang digunakan oleh lapisan normalisasi lapisan.

attention_dropout (`Union[float, int]`, *opsional*, defaultnya `0.0`) : Rasio dropout untuk probabilitas perhatian.

initializer_range (`float`, *opsional*, defaultnya `1e-10`) : Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

qkv_bias (`bool`, *opsional*, defaultnya `True`) : Apakah akan menambahkan bias ke queries, keys, dan values.

mlp_ratio (`float`, *opsional*, defaultnya `4.0`) : Rasio dimensi tersembunyi MLP terhadap dimensi embedding.

use_abs_pos (`bool`, *opsional*, defaultnya `True`) : Apakah akan menggunakan embedding posisi absolut.

use_rel_pos (`bool`, *opsional*, defaultnya `True`) : Apakah akan menggunakan relative position embedding.

window_size (`int`, *opsional*, default 14) : Ukuran jendela untuk posisi relatif.

global_attn_indexes (`list[int]`, *opsional*, defaultnya `[2, 5, 8, 11]`) : Indeks dari lapisan perhatian global.

num_pos_feats (`int`, *opsional*, default 128) : Dimensi dari position embedding.

mlp_dim (`int`, *opsional*) : Dimensi dari lapisan MLP dalam encoder Transformer. Jika `None`, defaultnya adalah `mlp_ratio * hidden_size`.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari SamHQModel. Kelas ini digunakan untuk membuat instans model Sam Hq berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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

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

**Parameter:**

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

hidden_act (`str`, *opsional*, defaultnya `relu`) : Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, `"gelu"`, `"relu"`, `"silu"`, dan sebagainya.

mlp_dim (`int`, *opsional*, default 2048) : Dimensi dari lapisan "intermediate" (yaitu, feed-forward) dalam encoder Transformer.

num_hidden_layers (`int`, *opsional*, defaultnya `2`) : Jumlah lapisan tersembunyi dalam decoder Transformer.

num_attention_heads (`int`, *opsional*, defaultnya `8`) : Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer.

attention_downsample_rate (`int`, *opsional*, defaultnya 2) : Tingkat downsampling dari lapisan attention.

num_multimask_outputs (`int`, *opsional*, defaultnya 3) : Jumlah output dari modul `SamMaskDecoder`. Dalam paper Segment Anything, nilai ini diatur ke 3.

iou_head_depth (`int`, *opsional*, defaultnya 3) : Jumlah lapisan dalam modul kepala IoU.

iou_head_hidden_dim (`int`, *opsional*, defaultnya 256) : Dimensi dari hidden states di modul IoU head.

layer_norm_eps (`float`, *opsional*, defaultnya `1e-06`) : Epsilon yang digunakan oleh lapisan normalisasi lapisan.

vit_dim (`int`, *opsional*, default 768) : Dimensi dari Vision Transformer (ViT) yang digunakan dalam modul `SamHQMaskDecoder`.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari SamHQModel. Kelas ini digunakan untuk membuat instans model Sam Hq berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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.

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

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

**Parameter:**

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

image_size (`Union[int, list[int], tuple[int, int]]`, *opsional*, defaultnya `1024`) : Ukuran (resolusi) dari setiap gambar.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opsional*, defaultnya `16`) : Ukuran (resolusi) dari setiap patch.

mask_input_channels (`int`, *opsional*, default 16) : Jumlah channel yang akan diberikan ke modul `MaskDecoder`.

num_point_embeddings (`int`, *opsional*, defaultnya 4) : Jumlah point embedding yang akan digunakan.

hidden_act (`str`, *opsional*, defaultnya `gelu`) : Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, `"gelu"`, `"relu"`, `"silu"`, dan sebagainya.

layer_norm_eps (`float`, *opsional*, defaultnya `1e-06`) : Epsilon yang digunakan oleh lapisan normalisasi lapisan.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari SamHQModel. Kelas ini digunakan untuk membuat instans model Sam Hq berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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.

## SamHQProcessor[[transformers.SamHQProcessor]]

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

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

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

**Parameter:**

image_processor (`SamImageProcessor`) : Prosesor gambar adalah input yang wajib.

Membangun SamHQProcessor yang membungkus image processor menjadi satu processor tunggal.

[SamHQProcessor](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQProcessor) menyediakan semua fungsionalitas dari [SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor). Lihat [~SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor) untuk informasi lebih lanjut.

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

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

**Parameter:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opsional*) : Gambar untuk dipreprocess. Mengharapkan satu gambar atau batch gambar dengan nilai piksel berkisar dari 0 hingga 255. Jika memasukkan gambar dengan nilai piksel antara 0 dan 1, atur `do_rescale=False`.

segmentation_maps (`ImageInput`, *kwargs*, *opsional*) : Peta segmentasi ground truth untuk diproses bersama gambar input. Peta-peta ini digunakan untuk keperluan pelatihan atau evaluasi, dan di-resize serta dinormalisasi agar sesuai dengan dimensi gambar yang telah diproses.

input_points (`NestedList`, *kwargs*, *opsional*) : Titik input untuk segmentasi berbasis prompt. Harus berupa daftar bersarang dengan struktur `[image_level, object_level, point_level, [x, y]]` di mana setiap titik ditentukan sebagai koordinat `[x, y]` dalam ruang gambar asli. Titik-titik dinormalisasi ke ukuran gambar target sebelum diteruskan ke model.

input_labels (`NestedList`, *kwargs*, *opsional*) : Label untuk titik input, menunjukkan apakah setiap titik adalah latar depan (1) atau latar belakang (0). Harus berupa nested list dengan struktur `[image_level, object_level, point_level]`. Harus memiliki struktur yang sama dengan `input_points` (kecuali dimensi koordinat).

input_boxes (`NestedList`, *kwargs*, *opsional*) : Kotak pembatas untuk segmentasi berbasis prompt. Harus berupa daftar bersarang dengan struktur `[image_level, box_level, [x1, y1, x2, y2]]` di mana setiap kotak ditentukan sebagai koordinat `[x1, y1, x2, y2]` dalam ruang gambar asli. Kotak-kotak tersebut dinormalisasi ke ukuran gambar target sebelum diteruskan ke model.

point_pad_value (`int`, *kwargs*, *opsional*, defaultnya `None`) : Nilai yang digunakan untuk mengisi titik input saat pengelompokan (batching) sekuens dengan panjang berbeda. Nilai ini menandai posisi yang di-*pad* dan dipertahankan selama normalisasi koordinat untuk membedakan titik asli dari *padding*. Jika `None`, nilai *pad* default dari konfigurasi prosesor akan digunakan.

mask_size (`dict[str, *kwargs*, int]`, *opsional*) : Kamus yang menentukan ukuran target mask dengan kunci `"height"` dan `"width"`. Ini menentukan resolusi dari mask segmentasi output yang dihasilkan oleh model.

mask_pad_size (`dict[str, *kwargs*, int]`, *opsional*) : Kamus yang menentukan ukuran padding untuk mask dengan kunci `"height"` dan `"width"`. Ini digunakan saat melakukan batching mask dengan ukuran berbeda untuk memastikan dimensi yang konsisten.

return_tensors (`str` atau [TensorType](/docs/transformers/main/id/internal/file_utils#transformers.TensorType), *opsional*) : Jika diatur, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:  - `'pt'`: Mengembalikan objek `torch.Tensor` PyTorch. - `'np'`: Mengembalikan objek `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/id/main_classes/processors#transformers.ProcessingKwargs), *opsional*) : Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

**Mengembalikan:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *opsional*) -- Kamus berisi daftar/array/tensor yang dikembalikan oleh metode __call__/pad ('input_values', 'attention_mask', dll.).
- **tensor_type** (`Union[None, str, TensorType]`, *opsional*) -- Anda dapat memberikan tensor_type di sini untuk mengonversi daftar bilangan bulat menjadi Tensor PyTorch/Numpy saat inisialisasi.
- **skip_tensor_conversion** (`list[str]` atau `set[str]`, *opsional*) -- Daftar atau himpunan kunci yang TIDAK boleh dikonversi menjadi tensor, bahkan ketika `tensor_type` ditentukan.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

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

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

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

**Parameter:**

config ([SamHQVisionConfig](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQVisionConfig)) : 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.

Model visi dari SamHQ tanpa head atau proyeksi di atasnya.

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

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

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

**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 [SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor). Lihat [SamImageProcessor.__call__()](/docs/transformers/main/id/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) untuk detailnya ([SamHQProcessor](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQProcessor) menggunakan [SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor) untuk memproses gambar).

**Mengembalikan:** `SamHQVisionEncoderOutput` atau `tuple(torch.Tensor)`

A `SamHQVisionEncoderOutput` atau tuple dari `torch.Tensor` (jika `return_dict=False` dilewatkan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi ([SamHQConfig](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQConfig)) dan input.

Metode forward dari [SamHQVisionModel](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQVisionModel) 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.

- **image_embeds** (`torch.Tensor` dengan bentuk `(batch_size, output_dim)` *opsional* yang dikembalikan saat model diinisialisasi dengan `with_projection=True`) -- Embedding gambar yang diperoleh dengan menerapkan lapisan proyeksi ke pooler_output.
- **last_hidden_state** (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`, *opsional*) -- Urutan hidden-states pada keluaran dari lapisan terakhir model.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *opsional*, dikembalikan ketika `output_hidden_states=True` dilewatkan atau ketika `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, sequence_length, 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, sequence_length, sequence_length)`.

  Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala self-attention.
- **intermediate_embeddings** (`list(torch.Tensor)`, *opsional*) -- Daftar embedding antara yang dikumpulkan dari blok-blok tertentu dalam model, biasanya blok yang tidak menggunakan windowed attention. Setiap elemen dalam daftar ini memiliki bentuk `(batch_size, sequence_length, hidden_size)`. Hal ini khusus untuk SAM-HQ dan tidak ada pada SAM dasar.

## SamHQModel[[transformers.SamHQModel]]

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

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

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

**Parameter:**

config ([SamHQConfig](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQConfig)) : 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.

Segment Anything Model HQ (SAM-HQ) untuk menghasilkan mask, berdasarkan gambar input dan lokasi 2D serta bounding box opsional.

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

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

**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 [SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor). Lihat [SamImageProcessor.__call__()](/docs/transformers/main/id/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) untuk detailnya ([SamHQProcessor](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQProcessor) menggunakan [SamImageProcessor](/docs/transformers/main/id/model_doc/sam#transformers.SamImageProcessor) untuk memproses gambar).

input_points (`torch.Tensor` dengan bentuk `(batch_size, num_points, 2)`) : Titik spasial 2D sebagai input, yang digunakan oleh prompt encoder untuk meng-encode prompt. Umumnya menghasilkan hasil yang jauh lebih baik. Titik-titik ini dapat diperoleh dengan meneruskan list of list of list ke processor, yang akan membuat tensor `torch` berdimensi 4 yang sesuai. Dimensi pertama adalah ukuran batch gambar, dimensi kedua adalah ukuran batch titik (yaitu berapa banyak segmentation mask yang ingin diprediksi model per titik input), dimensi ketiga adalah jumlah titik per segmentation mask (dimungkinkan untuk meneruskan beberapa titik untuk satu mask), dan dimensi terakhir adalah koordinat x (vertikal) dan y (horizontal) dari titik tersebut. Jika jumlah titik yang diteruskan berbeda untuk setiap gambar atau untuk setiap mask, processor akan membuat titik "PAD" yang akan sesuai dengan koordinat (0, 0), dan perhitungan embedding akan dilewati untuk titik-titik ini menggunakan label.

input_labels (`torch.LongTensor` dengan bentuk `(batch_size, point_batch_size, num_points)`) : Label input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Menurut implementasi resmi, terdapat 3 jenis label - `1`: titik tersebut adalah titik yang mengandung objek yang diminati - `0`: titik tersebut adalah titik yang tidak mengandung objek yang diminati - `-1`: titik tersebut sesuai dengan latar belakang  Kami menambahkan label: - `-10`: titik tersebut adalah titik padding, sehingga harus diabaikan oleh prompt encoder Label padding seharusnya dilakukan secara otomatis oleh processor.

input_boxes (`torch.Tensor` dengan bentuk `(batch_size, num_boxes, 4)`) : Kotak input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Umumnya menghasilkan mask yang dihasilkan jauh lebih baik. Kotak-kotak ini dapat diperoleh dengan meneruskan list of list of list ke processor, yang akan menghasilkan tensor `torch`, di mana setiap dimensi secara berturut-turut sesuai dengan ukuran batch gambar, jumlah kotak per gambar, dan koordinat titik kiri atas dan kanan bawah dari kotak. Dalam urutan (`x1`, `y1`, `x2`, `y2`):  - `x1`: koordinat x dari titik kiri atas kotak input - `y1`: koordinat y dari titik kiri atas kotak input - `x2`: koordinat x dari titik kanan bawah kotak input - `y2`: koordinat y dari titik kanan bawah kotak input

input_masks (`torch.Tensor` dengan bentuk `(batch_size, image_size, image_size)`) : Model SAM_HQ juga menerima mask segmentasi sebagai input. Mask akan di-embed oleh prompt encoder untuk menghasilkan embedding yang sesuai, yang kemudian akan diberikan ke mask decoder. Mask-mask ini perlu diberikan secara manual oleh pengguna, dan harus memiliki bentuk (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` dengan bentuk `(batch_size, output_channels, window_size, window_size)`) : Embedding gambar, yang digunakan oleh mask decoder untuk menghasilkan mask dan skor iou. Untuk komputasi yang lebih hemat memori, pengguna dapat terlebih dahulu mengambil embedding gambar menggunakan metode `get_image_embeddings`, lalu memasukkannya ke metode `forward` alih-alih memasukan `pixel_values`.

multimask_output (`bool`, *opsional*) : Pada implementasi dan paper aslinya, model selalu mengoutput 3 mask per gambar (atau per titik / per bounding box jika relevan). Namun, dimungkinkan untuk hanya mengoutput satu mask yang sesuai dengan mask "terbaik" dengan menentukan `multimask_output=False`.

hq_token_only (`bool`, *opsional*, defaultnya `False`) : Apakah hanya menggunakan jalur token HQ untuk pembuatan mask. Jika False, menggabungkan kedua jalur standar dan HQ. Hal ini spesifik untuk arsitektur SAM-HQ.

attention_similarity (`torch.Tensor`, *opsional*) : Tensor kemiripan perhatian, yang akan diberikan ke decoder masker untuk perhatian yang dipandu target dalam kasus model digunakan untuk personalisasi sebagaimana diperkenalkan dalam [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *opsional*) : Embedding dari konsep target, yang harus diberikan ke mask decoder untuk target-semantic prompting jika model digunakan untuk personalisasi seperti yang diperkenalkan dalam [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`, *opsional*) : Embedding antara dari blok non-windowed vision encoder, digunakan oleh SAM-HQ untuk meningkatkan kualitas mask. Wajib diisi saat menyediakan image_embeddings yang sudah dihitung sebelumnya alih-alih pixel_values.

**Mengembalikan:**

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

Metode forward dari [SamHQModel](/docs/transformers/main/id/model_doc/sam_hq#transformers.SamHQModel) 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.

Contoh:

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