# Segmentasi instance

Segmentasi instance adalah tugas computer vision untuk mendeteksi objek dalam sebuah gambar dan melakukan segmentasi pada setiap objek di tingkat piksel. Berbeda dengan deteksi objek (yang menghasilkan bounding box), segmentasi instance menghasilkan mask yang presisi untuk setiap objek yang terdeteksi, sehingga memungkinkan Anda membedakan instance individu bahkan ketika mereka saling tumpang tindih.

Dalam panduan ini, Anda akan belajar cara:

 1. Muat dataset segmentasi instance dari Hugging Face Hub.
 2. Lakukan fine-tuning pada [RF-DETR-Seg](https://huggingface.co/Roboflow/rf-detr-seg-medium), model instance segmentation berbasis transformer, menggunakan [Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer) dari Transformers.
 3. Evaluasi model Anda dengan mean IoU.
 4. Jalankan inferensi dan visualisasikan prediksi.

Kami akan menggunakan dataset [satellite-building-segmentation](https://huggingface.co/datasets/merve/satellite-building-segmentation), yang berisi sekitar 9,6k citra satelit yang dianotasi dengan mask instance bangunan.

> [!TIP]
> Untuk melihat semua arsitektur dan checkpoint yang kompatibel dengan tugas ini, kami menyarankan untuk memeriksa [halaman tugas](https://huggingface.co/tasks/image-segmentation).

Sebelum Anda memulai, instal semua pustaka yang diperlukan:

```bash
pip install -Uq "transformers>=5.9" datasets torchvision
```

Kami mendorong Anda untuk membagikan model Anda kepada komunitas. Masuk ke akun Hugging Face Anda untuk mengunggahnya ke Hub setelah pelatihan selesai:

```py
>>> from huggingface_hub import notebook_login

>>> notebook_login()
```

## Muat dataset

Dataset [satellite-building-segmentation](https://huggingface.co/datasets/merve/satellite-building-segmentation) berada dalam format Hugging Face Datasets native, sehingga dapat dimuat langsung dengan `load_dataset`. Setiap baris berisi:

- `image`: citra satelit (PIL)
- `image_id`: pengidentifikasi unik untuk gambar
- `width` / `height`: dimensi gambar
- `objects`: dict anotasi per-instance dengan `id`, `category`, `bbox`, `area`, `segmentation` (koordinat poligon), dan `iscrowd`

```py
>>> from datasets import load_dataset

>>> MODEL_ID = "Roboflow/rf-detr-seg-medium"
>>> DATASET_ID = "merve/satellite-building-segmentation"

>>> ds = load_dataset(DATASET_ID)
>>> train_ds = ds["train"]
>>> valid_ds = ds["validation"]
>>> print(f"Train: {len(train_ds)} images, Valid: {len(valid_ds)} images")
Train: 6764 images, Valid: 1934 images

```

Periksa satu contoh. Setiap rekaman memiliki `image`, `image_id`, dan dict `objects` yang berisi anotasi per-instan. Setiap instan memiliki `bbox` dalam format `[x, y, width, height]` dan field `segmentation` dengan koordinat poligon:

```py
>>> sample = train_ds[0]
>>> print(f"Image ID: {sample['image_id']}")
Image ID: 0
>>> print(f"Image size: {sample['image'].size}")
Image size: (512, 512)
>>> print(f"Number of instances: {len(sample['objects']['id'])}")
Number of instances: 7
>>> print(f"\nObjects keys: {list(sample['objects'].keys())}")
<BLANKLINE>
Objects keys: ['id', 'area', 'bbox', 'segmentation', 'category', 'iscrowd']
>>> print(f"First bbox: {sample['objects']['bbox'][0]}")
First bbox: [80.0, 0.0, 51.0, 51.5]
>>> print(f"First category: {sample['objects']['category'][0]}")
First category: 0

```

Visualisasikan sebuah contoh beserta mask ground-truth-nya:

```py
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from PIL import Image, ImageDraw

>>> sample = train_ds[0]
>>> image = sample["image"].convert("RGB")

>>> fig, axes = plt.subplots(1, 2, figsize=(14, 6))
>>> _ = axes[0].imshow(image)
>>> _ = axes[0].set_title("Original image")
>>> _ = axes[0].axis("off")

>>> overlay = image.copy()
>>> draw = ImageDraw.Draw(overlay, "RGBA")
>>> objects = sample["objects"]
>>> for seg in objects["segmentation"]:
...     for poly in seg:
...         coords = list(zip(poly[0::2], poly[1::2]))
...         color = tuple(np.random.randint(50, 255, 3)) + (100,)
...         draw.polygon(coords, fill=color, outline="red")

>>> _ = axes[1].imshow(overlay)
>>> _ = axes[1].set_title(f"Ground truth ({len(objects['id'])} buildings)")
>>> _ = axes[1].axis("off")
>>> plt.tight_layout()
>>> plt.show()
```

![Dataset Sample](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/satellite-dataset.png)

## Muat model dan pemroses gambar

Gunakan [AutoImageProcessor](/docs/transformers/v5.23.0/id/model_doc/auto#transformers.AutoImageProcessor) dan [AutoModelForInstanceSegmentation](/docs/transformers/v5.23.0/id/model_doc/auto#transformers.AutoModelForInstanceSegmentation) untuk memuat model RF-DETR-Seg. Saat memuat model, berikan pemetaan `id2label` dan `label2id` untuk mengonfigurasi kepala klasifikasi untuk kelas tunggal "building". Karena model pretrained dilatih pada COCO (91 kelas), atur `ignore_mismatched_sizes=True` untuk menginisialisasi ulang kepala klasifikasi dengan jumlah output yang benar.

Image processor menangani semua pra-pemrosesan: mengubah ukuran gambar sambil mempertahankan rasio aspek, menormalisasi dengan statistik ImageNet, melakukan padding ke ukuran seragam, dan — yang sangat penting untuk segmentasi instance — mengonversi anotasi poligon menjadi mask biner, mengubah ukuran mask tersebut, dan menormalisasi kotak batas ke format `[cx, cy, w, h]` dalam rentang `[0, 1]` yang diharapkan oleh model.

```py
>>> from transformers import AutoImageProcessor, AutoModelForInstanceSegmentation

>>> id2label = {0: "building"}
>>> label2id = {"building": 0}

>>> image_processor = AutoImageProcessor.from_pretrained(MODEL_ID)
>>> model = AutoModelForInstanceSegmentation.from_pretrained(
...     MODEL_ID,
...     id2label=id2label,
...     label2id=label2id,
...     ignore_mismatched_sizes=True,
... )
```

## Praproses data

Untuk melakukan fine-tuning pada model, Anda harus memproses data terlebih dahulu agar sesuai dengan format yang diharapkan oleh model. `RfDetrImageProcessor` melakukan semua pekerjaan berat ketika Anda melewatkan gambar dan anotasi dalam format COCO dengan `return_segmentation_masks=True`:

1. Merasterisasi segmentasi poligon menjadi maska biner
2. Mengubah ukuran gambar, kotak pembatas, dan masker ke ukuran input model
3. Menormalisasi nilai piksel dengan mean/std ImageNet
4. Mengonversi kotak pembatas dari `[x, y, w, h]` menjadi `[cx, cy, w, h]` yang dinormalisasi
5. Menambahkan padding pada gambar ke ukuran seragam dan membuat `pixel_mask`

Transform ini merekonstruksi dict anotasi bergaya COCO yang diharapkan oleh image processor dari kolom `objects` dataset.

Gunakan [with_transform](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset.with_transform) untuk menerapkan pra-pemrosesan secara malas (on-the-fly saat sampel dimuat), yang menghindari penyimpanan seluruh dataset yang sudah diproses di memori.

```py
>>> from functools import partial
>>> from typing import Any

>>> def transform_batch(examples: dict[str, Any], image_processor) -> dict[str, Any]:
...     """Convert HF dataset rows into COCO-style dicts and pass to the processor."""
...     images, targets = [], []
...     for image, img_id, objects in zip(
...         examples["image"], examples["image_id"], examples["objects"]
...     ):
...         if not objects["id"]:
...             continue
...         annotations = [
...             {
...                 "id": ann_id,
...                 "image_id": img_id,
...                 "category_id": cat,
...                 "bbox": bbox,
...                 "area": area,
...                 "segmentation": seg,
...                 "iscrowd": crowd,
...             }
...             for ann_id, cat, bbox, area, seg, crowd in zip(
...                 objects["id"],
...                 objects["category"],
...                 objects["bbox"],
...                 objects["area"],
...                 objects["segmentation"],
...                 objects["iscrowd"],
...             )
...         ]
...         images.append(image.convert("RGB"))
...         targets.append({"image_id": img_id, "annotations": annotations})
...
...     if not images:
...         return {}
...     return image_processor(
...         images=images, annotations=targets, return_segmentation_masks=True, return_tensors="pt"
...     )

>>> transform = partial(transform_batch, image_processor=image_processor)
>>> train_ds = train_ds.shuffle(seed=42).with_transform(transform)
>>> valid_ds = valid_ds.with_transform(transform)
```

Verifikasi contoh yang telah diproses. Contoh ini berisi `pixel_values` (tensor gambar ternormalisasi), `pixel_mask` (menunjukkan piksel asli vs padding), dan `labels` (sebuah dict dengan `class_labels`, `boxes` dalam format pusat ternormalisasi, dan `masks` biner):

```py
>>> example = train_ds[0]
>>> print(f"pixel_values shape: {example['pixel_values'].shape}")
pixel_values shape: torch.Size([3, 432, 432])
>>> print(f"pixel_mask shape: {example['pixel_mask'].shape}")
pixel_mask shape: torch.Size([432, 432])
>>> print(f"labels keys: {list(example['labels'].keys())}")
labels keys: ['size', 'image_id', 'class_labels', 'boxes', 'area', 'iscrowd', 'orig_size', 'masks']
>>> print(f"  class_labels: {example['labels']['class_labels']}")
  class_labels: tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0])
>>> print(f"  boxes shape: {example['labels']['boxes'].shape}")
  boxes shape: torch.Size([26, 4])
>>> print(f"  masks shape: {example['labels']['masks'].shape}")
  masks shape: torch.Size([26, 432, 432])

```

## Data collator

Karena setiap gambar memiliki jumlah instance objek yang berbeda, label berupa kamus dengan panjang yang bervariasi dan tidak dapat ditumpuk menjadi satu tensor. Definisikan fungsi collate kustom yang menumpuk `pixel_values` dan `pixel_mask` secara normal, tetapi mempertahankan `labels` sebagai daftar kamus per gambar:

```py
>>> import torch

>>> def collate_fn(batch: list[dict[str, Any]]) -> dict[str, Any]:
...     out = {
...         "pixel_values": torch.stack([x["pixel_values"] for x in batch]),
...         "labels": [x["labels"] for x in batch],
...     }
...     if "pixel_mask" in batch[0]:
...         out["pixel_mask"] = torch.stack([x["pixel_mask"] for x in batch])
...     return out
```

## Definisikan metrik evaluasi

Untuk melacak kualitas segmentasi selama pelatihan, hitung *mean IoU berbasis union* pada setiap epoch evaluasi. Untuk setiap gambar:

1. Gabungkan semua mask instance yang diprediksi menjadi satu peta biner "buildings" (binerkan logits mask setiap query dengan `sigmoid > 0.5`)
2. Gabungkan semua mask instance ground-truth menjadi satu peta biner
3. Hitung Intersection-over-Union antara dua peta

Mask query dari RF-DETR-Seg tidak digate oleh ambang batas skor kelas, sehingga metrik mengabaikan skor kelas dan langsung menyatukan logit mask per query. Query yang tidak cocok menghasilkan mask yang hampir kosong, sehingga tidak mencemari hasil penyatuan.

Ini memberikan metrik per gambar tentang "seberapa baik model mencakup bangunan", yang dirata-ratakan di seluruh set validasi.

> [!TIP]
> Benchmarks segmentasi instance (seperti COCO) biasanya melaporkan mask mean average precision (mAP), yang menilai setiap mask instance yang diprediksi terhadap ground truth di berbagai ambang IoU dan karenanya memberikan penghargaan untuk pemisahan objek individual yang benar. Mean IoU berbasis union yang digunakan di sini adalah proksi yang lebih sederhana dan cepat: ia mengukur cakupan piksel keseluruhan alih-alih kualitas per-instance, yang membuatnya nyaman untuk melacak kemajuan selama pelatihan. Untuk evaluasi standar yang sadar instance, hitung mask mAP sebagai gantinya, misalnya dengan [`MeanAveragePrecision(iou_type="segm")`](https://lightning.ai/docs/torchmetrics/stable/detection/mean_average_precision.html) dari `torchmetrics`.

Lewatkan ini ke [Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer) sebagai fungsi `compute_metrics` alih-alih membuat subkelas dari trainer. Dengan `eval_do_concat_batches=False` (diatur di [TrainingArguments](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.TrainingArguments) di bawah), prediksi dan label yang dihasilkan oleh jalur evaluasi standar diserahkan ke `compute_metrics` sebagai daftar output per-batch, sehingga metrik tersebut dapat menggunakan ulang prediksi tersebut dan tidak diperlukan forward pass kedua pada set validasi. Dalam tuple output model, indeks `3` menyimpan `pred_masks`:

```py
>>> import torch.nn.functional as F

>>> @torch.no_grad()
... def compute_mean_iou(pred_masks, gt_masks, target_size):
...     """Union-based IoU: merge all instances per image, then compute IoU."""
...     pred_masks = F.interpolate(pred_masks[None], size=target_size, mode="bilinear", align_corners=False)[0]
...     pred_union = (pred_masks.sigmoid() > 0.5).any(dim=0)
...
...     gt_union = gt_masks.any(dim=0).bool()
...
...     intersection = (pred_union & gt_union).sum().float()
...     union = (pred_union | gt_union).sum().float()
...     return (intersection / union.clamp(min=1)).item()

>>> @torch.no_grad()
... def compute_metrics(evaluation_results):
...     predictions, targets = evaluation_results.predictions, evaluation_results.label_ids
...     ious = []
...     for pred_batch, target_batch in zip(predictions, targets):
...         batch_masks = pred_batch[3]
...         for i, gt_label in enumerate(target_batch):
...             gt_masks = torch.as_tensor(gt_label["masks"])
...             if gt_masks.numel() == 0:
...                 continue
...             target_size = gt_masks.shape[-2:]
...             pred_masks = torch.as_tensor(batch_masks[i])
...             ious.append(compute_mean_iou(pred_masks, gt_masks, target_size))
...
...     mean_iou = sum(ious) / len(ious) if ious else 0.0
...     return {"mean_iou": mean_iou}
```

[Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer) secara otomatis menambahkan awalan `eval_` pada kunci yang dikembalikan, sehingga menghasilkan metrik `eval_mean_iou` yang digunakan di bawah ini untuk pemilihan checkpoint.

## Pelatihan

Dengan data, model, dan metrik yang sudah siap, atur pelatihan. Beberapa catatan penting mengenai [TrainingArguments](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.TrainingArguments):

- `remove_unused_columns=False`: Diperlukan karena perilaku bawaan akan membuang kolom sebelum transform kami dijalankan.
- `eval_do_concat_batches=False`: Label instance segmentation berupa dict dengan panjang variabel, sehingga tidak dapat digabungkan antar batch. Pengaturan ini juga menjaga agar prediksi tetap dikelompokkan per batch sehingga `compute_metrics` dapat mencocokkannya dengan label yang sesuai.
- `metric_for_best_model="eval_mean_iou"`: Pilih checkpoint terbaik berdasarkan kualitas segmentasi, bukan hanya loss.
- `fp16=True`: Pelatihan presisi campuran secara signifikan mempercepat pelatihan pada GPU modern.

```py
>>> from transformers import Trainer, TrainingArguments

>>> training_args = TrainingArguments(
...     output_dir="rf-detr-seg-satellite-buildings",
...     num_train_epochs=10,
...     per_device_train_batch_size=16,
...     per_device_eval_batch_size=16,
...     learning_rate=1e-4,
...     weight_decay=1e-4,
...     lr_scheduler_type="cosine",
...     warmup_steps=0.1,
...     fp16=True,
...     dataloader_num_workers=4,
...     eval_strategy="epoch",
...     save_strategy="epoch",
...     save_total_limit=2,
...     load_best_model_at_end=True,
...     metric_for_best_model="eval_mean_iou",
...     greater_is_better=True,
...     remove_unused_columns=False,
...     eval_do_concat_batches=False,
...     push_to_hub=False,
... )

>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=train_ds,
...     eval_dataset=valid_ds,
...     processing_class=image_processor,
...     data_collator=collate_fn,
...     compute_metrics=compute_metrics,
... )

>>> trainer.train()
```

Jika Anda mengatur `push_to_hub=True` dalam argumen pelatihan, checkpoint pelatihan akan didorong ke Hugging Face Hub. Setelah pelatihan selesai, dorong juga model akhir ke Hub dengan memanggil metode [push_to_hub()](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer.push_to_hub).

```py
>>> trainer.push_to_hub(
...     dataset=DATASET_ID,
...     tags=["instance-segmentation", "rf-detr-seg", "vision", "satellite", "building"],
... )
```

## Inferensi

Sekarang Anda memiliki model yang telah di-*fine-tune*, gunakan model tersebut untuk inferensi pada citra satelit baru. Alur kerjanya adalah:

1. Praproses gambar dengan image processor
2. Jalankan forward pass melalui model
3. Lakukan pascapemrosesan output dengan `post_process_instance_segmentation` untuk mendapatkan mask pada tingkat piksel

Langkah pascapemrosesan mengubah keluaran kueri mentah (logits + mask beresolusi rendah) menjadi peta segmentasi instance beresolusi penuh, dengan menerapkan ambang batas skor dan binarisasi mask.

```py
>>> from datasets import load_dataset

>>> test_ds = load_dataset(DATASET_ID, split="test")
>>> sample = test_ds[0]
>>> image = sample["image"].convert("RGB")

>>> device = next(model.parameters()).device
>>> inputs = image_processor(images=image, return_tensors="pt").to(device)

>>> with torch.no_grad():
...     outputs = model(**inputs)

>>> results = image_processor.post_process_instance_segmentation(
...     outputs, threshold=0.5, target_sizes=[(image.height, image.width)]
... )[0]

>>> print(f"Detected {len(results['segments_info'])} buildings")
Detected 0 buildings
>>> for seg_info in results["segments_info"][:5]:
...     print(f"  Building (score: {seg_info['score']:.3f})")
```

Visualisasikan prediksi. Peta segmentasi memberikan setiap piksel sebuah ID segmen (-1 untuk latar belakang). Tampilkan setiap bangunan yang terdeteksi dengan warna acak:

```py
>>> fig, axes = plt.subplots(1, 2, figsize=(14, 6))

>>> _ = axes[0].imshow(image)
>>> _ = axes[0].set_title("Input satellite image")
>>> _ = axes[0].axis("off")

>>> seg_map = results["segmentation"].cpu().numpy()
>>> overlay = np.array(image).copy()
>>> for seg_info in results["segments_info"]:
...     mask = seg_map == seg_info["id"]
...     color = np.random.randint(0, 255, 3)
...     overlay[mask] = (overlay[mask] * 0.4 + color * 0.6).astype(np.uint8)

>>> _ = axes[1].imshow(overlay)
>>> _ = axes[1].set_title(f"Predicted masks ({len(results['segments_info'])} buildings)")
>>> _ = axes[1].axis("off")
>>> plt.tight_layout()
>>> plt.show()
```

![Fine-tuning Result](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/finetuned-results.png)

