Deteksi berorientasi

Definisi

Deteksi berorientasi menambahkan satu angka pada deteksi: angle. Setiap instance memperoleh persegi panjang berotasi, kelas, dan skor. Keuntungannya adalah batas yang rapat. Kapal pada sudut 45 derajat, atap gudang, atau deretan truk terparkir akan dikelilingi bounding box sejajar sumbu yang sebagian besar berisi background, dan dua bounding box berdekatan saling tumpang tindih meskipun objeknya tidak. Itulah alasan task ini umum dalam pencitraan aerial dan tata letak dokumen, serta alasan DOTA menjadi dataset referensinya.

obb adalah kunci task kanonis, dan akhiran -obb pada nama berkas checkpoint memilihnya, sehingga task= tidak diperlukan saat memuat bobot terbitan.

predict() mengisi result.obb. .xywhr adalah bentuk kanonis (N, 5): pusat x, pusat y, lebar, tinggi, dan angle dalam radian yang menyatakan rotasi sisi lebar di sekitar pusat. .conf dan .cls memuat skor serta indeks kelas dalam result.names, sedangkan .id memuat track id saat tracking. .xyxyxyxy mengubah setiap baris menjadi empat titik sudut sebagai piksel (N, 4, 2), .xyxyxyxyn menormalisasi sudut tersebut, dan .xyxy memberikan bounding box sejajar sumbu yang melingkupi, untuk digunakan ketika kode downstream hanya memahami persegi panjang. result.boxes juga diisi dengan bentuk sejajar sumbu.

Model

Empat family mendukung task ini.

RF-DETR mendukung pelatihan. Model ini memprediksi, melatih, memvalidasi, dan mengekspor kotak berorientasi, serta memiliki checkpoint berorientasi dalam empat ukuran: n, s, m, dan l. Model ini memerlukan extra tersendiri, pip install "libreyolo[rfdetr]", dan halaman model mencantumkan lisensi serta asal bobotnya.

Baca bagian di bawah tentang hal yang sebenarnya diprediksi checkpoint tersebut sebelum mengandalkannya.

RT-DETRv2 adalah family dengan bobot aerial. Model ini menerbitkan LibreRTDETRv2n-obb.pt hingga LibreRTDETRv2x-obb.pt, yaitu checkpoint single-scale DOTA v1.0 resmi yang dikonversi ke format LibreYOLO, mencakup 15 kelas DOTA pada 1024 px. Tidak diperlukan extra selain paket dasar, graph berorientasi dikenali dari tensor checkpoint sendiri, dan prediksi, validasi, serta ekspor ONNX dan TorchScript didukung. Pelatihan tidak didukung: task berorientasi hanya untuk inferensi pada family ini, train() memunculkan error, dan tidak ada transfer dari bobot deteksinya yang menggunakan backbone berbeda. Tracking dan test-time augmentation juga tidak tersedia untuk bounding box berorientasi.

Pilih kumpulan label checkpoint dan dukungan pelatihan yang sesuai dengan dataset.

YOLO-NAS juga mendukung pelatihan dan inferensi OBB. Bobot pretrained-nya mempertahankan ketentuan nonkomersial upstream.

GTR menerbitkan LibreGTRs-obb.pt dan LibreGTRx-obb.pt, yang memprediksi 15 kelas DOTA v1.0 pada input tetap 1024. Model ini berjalan dengan paket dasar dan mendukung prediksi, pelatihan, validasi, serta ekspor ONNX dan TorchScript.

Prediksi

Bobot diunduh dari Hugging Face saat pertama kali digunakan dan disimpan dalam cache lokal.

# Memerlukan extra rfdetr: pip install "libreyolo[rfdetr]"from libreyolo import LibreYOLO, SAMPLE_IMAGE # Akhiran -obb pada nama berkas memilih task, sehingga argumen task# tidak diperlukan.model = LibreYOLO("LibreRFDETRs-obb.pt")result = model(SAMPLE_IMAGE, save=True) obb = result.obbprint(obb.xywhr)   # (N, 5): pusat x, pusat y, lebar, tinggi, radianprint(obb.conf, obb.cls)

libreyolo predict model=LibreRFDETRs-obb.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE result = LibreYOLO("LibreRFDETRs-obb.pt")(SAMPLE_IMAGE)obb = result.obb print(obb.xyxyxyxy.shape)    # (N, 4, 2) titik sudut dalam pikselprint(obb.xyxyxyxyn.shape)   # hal yang sama, ternormalisasiprint(obb.xyxy.shape)        # (N, 4) bounding box sejajar sumbu yang melingkupi

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreRFDETRn-obb.pt")result = model(SAMPLE_IMAGE) print(result.obb.xywhr.shape)

from libreyolo import LibreYOLO # Bobot DOTA v1.0, 15 kelas aerial pada 1024 px. Graph berorientasi# dikenali dari tensor checkpoint sendiri, jadi tanpa argumen task.model = LibreYOLO("LibreRTDETRv2n-obb.pt")result = model("aerial.png", save=True) obb = result.obbprint(obb.xywhr)print(result.names)   # plane, ship, harbor, helicopter, dan 11 lainnya

Pahami checkpoint RF-DETR yang dipublikasikan sebelum menjalankannya. Meskipun DOTA menjadi benchmark acuan task ini, bobot tersebut tidak dilatih pada DOTA. Keempatnya diinisialisasi dari bobot deteksi RF-DETR dan menjalani fine-tuning pada satu dataset rekaman UAV dengan enam kelas kendaraan: bike, bus, car, other_vehicle, taxi, dan truck. Kartu model menyebutnya bobot pengembangan yang dibuat saat memvalidasi dukungan pelatihan berorientasi, dan menyatakan bahwa bobot tersebut bukan untuk produksi atau benchmark resmi.

Dalam praktiknya, bobot tersebut menjadi titik awal yang berfungsi untuk bounding box berorientasi pada kendaraan yang terlihat dari atas dan untuk memverifikasi bahwa pipeline berjalan end-to-end. Domain lain memerlukan pelatihan pada label berorientasi Anda sendiri, dan untuk kategori aerial yang dikenal dari DOTA, checkpoint RT-DETRv2 adalah yang benar-benar dilatih pada data tersebut. conf dan max_det membentuk output seperti pada deteksi, dan agnostic_nms=True menekan kotak yang tumpang tindih lintas kelas dengan IoU terotasi. Lihat prediksi untuk sumber, streaming, dan penanganan hasil.

Format dataset

Tata letaknya sama dengan deteksi: satu berkas label .txt per gambar, yang ditemukan dengan mengganti images menjadi labels pada path gambar dan mengubah ekstensinya.

dataset/  data.yaml  images/    train/P0001.png    val/P0101.png  labels/    train/P0001.txt    val/P0101.txt

Satu baris berisi tepat sembilan kolom, yaitu indeks kelas yang diikuti empat titik sudut secara berurutan:

<class_id> <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4>

Keempat titik berupa float ternormalisasi dalam [0, 1] dan harus membentuk persegi panjang berorientasi yang tidak degeneratif. Angle tidak disimpan dalam berkas label: loader menurunkan xywhr kanonis dari sudut. Secara default, parser bersifat ketat dan menolak koordinat di luar rentang, sedangkan proses ingestion dataset serta validasi dapat lebih dahulu memotong ke [0, 1] untuk label batas crop yang valid, lalu tetap menolak bounding box degeneratif.

Parsing baris memahami task. Sembilan kolom berarti bounding box berorientasi hanya dalam mode obb; dalam mode segment, baris yang sama dibaca sebagai poligon empat titik.

YAML-nya sama dengan YAML deteksi:

path: datasettrain: images/trainval: images/valnames:  0: plane  1: ship

JSON COCO native juga dapat dimuat, dengan pemetaan annotations dari nama split ke berkas JSON. Anotasi dibaca menurut urutan prioritas: kolom obb berisi delapan sudut dalam ruang piksel, kolom obb berupa [cx, cy, w, h, angle] dengan angle dalam radian, poligon segmentation atau RLE yang dicocokkan ulang ke persegi panjang minimum-area, atau bbox COCO biasa yang diperlakukan sebagai persegi panjang sejajar sumbu dan dikanonisasi menjadi xywhr.

Parser baris kanonis adalah libreyolo.data.parse_yolo_obb_label_line.

Pelatihan

from libreyolo import LibreYOLO # Melanjutkan dari bobot berorientasi terbitan. data harus menunjuk ke# dataset yang baris labelnya memuat empat sudut.model = LibreYOLO("LibreRFDETRs-obb.pt")model.train(data="my-obb-dataset.yaml", epochs=50, imgsz=512, batch=8, lr0=1e-4)

libreyolo train model=LibreRFDETRs-obb.pt data=my-obb-dataset.yaml \  epochs=50 imgsz=512 batch=8 lr0=1e-4

# Bobot deteksi tidak memuat prediksi angle, jadi ini adalah transfer# eksplisit. Meminta task=obb memberikan otorisasi untuknya.libreyolo train model=LibreRFDETRs.pt data=my-obb-dataset.yaml \  task=obb epochs=50 imgsz=512

Pelatihan RF-DETR secara default berlanjut dari checkpoint -obb yang dipublikasikan. Memulai dari bobot deteksi merupakan transfer eksplisit: bobot tersebut tidak memprediksi sudut, dan task=obb mengizinkan penggantian head. Pertahankan lr0 pada atau di bawah 1e-4, seperti task lain dalam family ini. Checkpoint berorientasi RT-DETRv2 tidak dapat menjalani fine-tuning; gunakan apa adanya, atau latih model RF-DETR dengan label sendiri. Lihat pelatihan untuk dataset, augmentasi, multi-GPU, dan logger.

YOLO-NAS OBB memakai assignment dan loss berotasi, augmentasi pembalikan/HSV, dan amp=False secara default. Model ini memilih checkpoint dengan metrics/mAP50-95(OBB).

Validasi

val() mengembalikan dictionary biasa berisi kunci metrics/. Pencocokan menggunakan rotated IoU, yang dihitung antara persegi panjang berorientasi, bukan bounding box sejajar sumbu yang melingkupinya, sehingga prediksi dengan posisi benar dan angle salah dinilai meleset.

from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs-obb.pt") # val() mengembalikan dict biasa, bukan objek.metrics = model.val(data="my-obb-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/precision"], metrics["metrics/recall"])

libreyolo val model=LibreRFDETRs-obb.pt data=my-obb-dataset.yaml

libreyolo val model=LibreRTDETRv2n-obb.pt data=my-obb-dataset.yaml

metrics/mAP50-95 adalah presisi rata-rata yang dirata-ratakan pada ambang batas IoU 0,50 hingga 0,95 dalam langkah 0,05, dan menjadi angka utama. Berbeda dari jalur COCO untuk deteksi, task ini mematuhi iou_thresholds dalam konfigurasi validasi, sehingga sweep dapat diubah. metrics/mAP50 dan metrics/mAP75 adalah versi satu ambang batas. metrics/precision dan metrics/recall merupakan presisi dan recall sebenarnya pada IoU 0,50, dibaca pada titik operasi paling longgar: setiap prediksi yang melewati ambang batas confidence dihitung, dan ambang batas tersebut default ke 0,001 selama validasi. Menaikkan conf akan mengubah keduanya, sedangkan angka mAP yang menggunakan seluruh kurva presisi-recall tetap. Empat kunci diulang dengan akhiran (OBB), yaitu metrics/mAP50-95(OBB), metrics/mAP50(OBB), metrics/precision(OBB), dan metrics/recall(OBB), agar pemanggil dapat membedakan hasil berorientasi dari hasil sejajar sumbu saat keduanya berada dalam tabel yang sama. metrics/mAP75 tidak memiliki pasangan berakhiran.

Dua opsi tidak berpengaruh pada task ini. save_json dan save_plots diterima dan mencatat warning: dump prediksi berorientasi dan plot validasi belum diimplementasikan. agnostic_nms=True memunculkan ValueError di sini; opsi itu hanya mencakup validasi detect dan segment.

Ekspor

from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs-obb.pt")model.export(format="onnx", imgsz=512)

libreyolo export model=LibreRFDETRs-obb.pt format=onnx imgsz=512

# ONNX dan TorchScript adalah target tervalidasi di sini, pada FP32,# batch 1, di kanvas tetap 1024 kali 1024.libreyolo export model=LibreRTDETRv2n-obb.pt format=onnx imgsz=1024libreyolo export model=LibreRTDETRv2n-obb.pt format=torchscript imgsz=1024

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Factory merutekan berdasarkan akhiran berkas, sehingga artefak hasil# ekspor dimuat seperti checkpoint dan mengembalikan objek Results yang sama.model = LibreYOLO("LibreRFDETRs-obb.onnx")result = model(SAMPLE_IMAGE) print(result.obb.xywhr)

Artefak hasil ekspor dimuat kembali melalui LibreYOLO() berdasarkan akhiran filenya, sehingga berkas .onnx atau .engine berperilaku seperti checkpoint dan mengembalikan Results yang sama. Cakupan format berbeda berdasarkan task pada family yang sama, dan matriks halaman model dibuat dari kumpulan tervalidasi serta menyebutkan alasan target tidak tersedia. Lihat ekspor dan deployment untuk format, extra, dan batasannya.