Transformers documentation

Segmentasi instance

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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, model instance segmentation berbasis transformer, menggunakan Trainer dari Transformers.
  3. Evaluasi model Anda dengan mean IoU.
  4. Jalankan inferensi dan visualisasikan prediksi.

Kami akan menggunakan dataset satellite-building-segmentation, yang berisi sekitar 9,6k citra satelit yang dianotasi dengan mask instance bangunan.

Untuk melihat semua arsitektur dan checkpoint yang kompatibel dengan tugas ini, kami menyarankan untuk memeriksa halaman tugas.

Sebelum Anda memulai, instal semua pustaka yang diperlukan:

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:

>>> from huggingface_hub import notebook_login

>>> notebook_login()

Muat dataset

Dataset 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
>>> 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:

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

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

Muat model dan pemroses gambar

Gunakan AutoImageProcessor dan 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.

>>> 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 mask 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 untuk menerapkan pra-pemrosesan secara malas (on-the-fly saat sampel dimuat), yang menghindari penyimpanan seluruh dataset yang sudah diproses di memori.

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

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

>>> 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 mask logits dari 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

Query mask pada RF-DETR-Seg tidak di-gate oleh ambang batas skor kelas, sehingga metrik mengabaikan skor kelas dan langsung melakukan union pada logit mask per-query. Query yang tidak cocok menghasilkan mask yang hampir kosong, sehingga tidak mencemari hasil union.

Hal ini menghasilkan metrik per gambar untuk “seberapa baik model mencakup bangunan”, yang dirata-ratakan di seluruh set validasi.

Benchmark segmentasi instance (seperti COCO) biasanya melaporkan mask mean average precision (mAP), yang menilai setiap mask instance yang diprediksi terhadap ground truth pada serangkaian 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: ini 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") dari torchmetrics.

Lewatkan ini ke Trainer sebagai fungsi compute_metrics alih-alih membuat subkelas dari trainer. Dengan eval_do_concat_batches=False (diatur di 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:

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

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

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

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

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

Update on GitHub