Tracking objek

Definisi

Tracking bukan salah satu kunci task LibreYOLO dan tidak ada checkpoint tracking untuk diunduh. Tracking adalah metode pada model, model.track(source), yang menjalankan deteksi pada setiap frame dan mengasosiasikan hasil lintas waktu. Metode ini berupa generator: menghasilkan satu Results per frame yang diproses, dengan result.track_id berupa tensor bilangan bulat (N,) yang selaras dengan result.boxes. Id yang sama juga tersedia pada result.boxes.id.

Hanya objek terkonfirmasi yang sedang dilacak yang dihasilkan. Track yang kehilangan asosiasi tetap hidup selama jumlah frame yang dikonfigurasi sebelum dihapus, track_buffer untuk ByteTrack dan BoT-SORT serta max_age untuk dua varian OC-SORT, sehingga objek yang ditemukan kembali dalam window tersebut mempertahankan id asli.

Karena asosiasi terjadi setelah deteksi, payload lain pada frame tetap tersedia: Results tracking adalah Results deteksi yang dipotong ke baris cocok, sehingga mask dan keypoint diteruskan bersama bounding box.

Model

Dua pilihan independen membentuk run tracking: model yang menghasilkan bounding box per frame dan tracker yang menghubungkannya.

Setiap model LibreYOLO native dengan task deteksi, segmentation, atau pose menyediakan track(). Lihat indeks model untuk list lengkap, atau mulai dari YOLO9, RF-DETR, D-FINE, atau RTMDet. Task tanpa bounding box untuk diasosiasikan menolak pemanggilan: classification, oriented bounding box, point, depth, surface normal, edge, semantic dan panoptic segmentation, restoration, OCR, serta body mesh.

Dua tier model juga menolaknya. Model LibreSAM adalah gambar segmenter dan model LibreOpenVocab adalah detektor per frame; keduanya memunculkan error dari track() dan menggunakan predict() per frame.

Tracking berjalan pada model PyTorch native. Artefak hasil ekspor yang dimuat melalui LibreYOLO("model.onnx") mengembalikan objek backend runtime dengan predict(), tetapi tanpa track().

Empat tracker disertakan dan dipilih melalui argumen tracker. Ejaan .yaml, seperti "bytetrack.yaml", memilih tracker bawaan yang sama; LibreYOLO tidak membaca berkas YAML tracker, dan memunculkan error jika berkas dengan nama itu ada di direktori kerja.

"bytetrack" adalah default. Tracker ini hanya menggunakan motion, dengan Kalman filter dan asosiasi tiga tahap: deteksi confidence tinggi, pass kedua yang memberi deteksi confidence rendah kesempatan mencocokkan track sebelum dibuang, lalu track belum terkonfirmasi. Dikonfigurasi dengan TrackConfig.

"botsort" mempertahankan lifecycle tiga tahap ByteTrack, tetapi memakai status Kalman center-width-height dan mengompensasi track prediksi terhadap gerakan kamera sebelum pencocokan. Ini adalah varian motion-only BoT-SORT tanpa model appearance. Dikonfigurasi dengan BoTSortConfig, yang menambahkan enable_cmc, cmc_method, dan cmc_downscale.

"ocsort" juga hanya memakai motion dan menambahkan term arah velocity ke biaya asosiasi, pass asosiasi kedua terhadap observasi nyata terakhir setiap track, serta smoothing status Kalman sepanjang trajectory virtual ketika track ditemukan kembali. Dikonfigurasi dengan OCSortConfig.

"deepocsort" memperluas OC-SORT dengan appearance. Setiap track mempertahankan moving average embedding re-identification yang dibobot confidence, dan cosine similarity masuk biaya asosiasi, sehingga identitas bertahan melalui occlusion panjang dan target yang bersilangan. Biayanya satu forward jaringan embedding kecil per frame, dan bobot OSNet diunduh saat penggunaan pertama. Dikonfigurasi dengan DeepOCSortConfig.

Prediksi

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # track() adalah generator: satu Results per frame yang diproses.for result in model.track("video.mp4"):    print(result.track_id)        # tensor int (N,), selaras dengan bounding box    print(result.boxes.xyxy)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # "bytetrack" (default), "botsort", "ocsort", atau "deepocsort".for result in model.track("video.mp4", tracker="botsort"):    print(result.track_id)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Tanpa output_path, berkas berada di runs/track/<video_stem>.mp4.for result in model.track("video.mp4", save=True, vid_stride=2):    pass

from libreyolo import BoTSortConfig, LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Jenis konfigurasi memilih tracker, sehingga tracker= redundan di sini.config = BoTSortConfig(track_buffer=60, frame_rate=25, enable_cmc=False)for result in model.track("video.mp4", tracker_config=config):    print(result.track_id) # Atau berikan kolom yang sama sebagai keyword argument dan biarkan track() membuatnya.for result in model.track("video.mp4", tracker="botsort", track_buffer=60):    print(result.track_id)

track_conf menetapkan ambang batas tahap asosiasi pertama: track_high_thresh untuk ByteTrack dan BoT-SORT, det_thresh untuk OC-SORT dan Deep OC-SORT. Nilai ini bukan conf milik predict(). Untuk ByteTrack, BoT-SORT, dan OC-SORT, detektor berjalan pada ambang batas lebih rendah secara internal agar deteksi lemah tersedia bagi recovery pass. Deep OC-SORT menjalankan detektor pada det_thresh. Untuk ByteTrack dan BoT-SORT, track_conf harus sama dengan atau di atas track_low_thresh, dengan default 0.1.

conf, bila diberikan, adalah ambang batas deteksi milik predict(): deteksi di bawahnya tidak pernah sampai ke tracker. Tanpanya, detektor berjalan pada ambang batas di atas.

Pengaturan tracker masuk melalui dua cara. Berikan instance konfigurasi ke tracker_config=, dan jenisnya memilih tracker sehingga tracker= redundan. Atau berikan kolom sebagai keyword argument dan biarkan track() membuat konfigurasi untuk tracker terpilih; kunci tidak dikenal menghasilkan peringatan. Dalam kedua cara, track_conf diabaikan setelah kunci pencocokan ditetapkan eksplisit.

Argumen lainnya sama dengan prediksi: iou, imgsz, classes, max_det, vid_stride, show, dan save dengan output_path. persist=True mempertahankan tracker beserta ID-nya dari pemanggilan track() sebelumnya pada model yang sama, untuk loop yang memberikan satu frame per pemanggilan, seperti model.track(frame, persist=True). Sumber dapat berupa video atau urutan gambar. Lihat prediksi untuk penanganan hasil.

Gambar, folder yang diurutkan berdasarkan nama berkas, daftar, tuple, dan iterator gambar lazy dapat menyediakan frame berurutan. fps=30.0 menentukan waktunya dan color_format="auto" memilih interpretasi input. vid_stride mengurangi laju frame yang dipertahankan menjadi fps / vid_stride.

Berikan instance tracker kustom melalui tracker=. Instance tersebut mengimplementasikan reset() dan update(results, image=None) dari libreyolo.tracking.Tracker. Satu proses meresetnya sekali dan meneruskan frame PIL RGB asli. track_id yang dikembalikan harus berupa array atau tensor integer satu dimensi yang sejajar dengan kotak pada backend/perangkat yang sama. Instance kustom memakai track_conf=0.25 secara default; konfigurasikan instance secara langsung, bukan melalui argumen kata kunci tracker atau tracker_config.

Pelatihan

Tracker tidak dilatih. Tiga dari empat tracker merupakan model motion murni tanpa parameter terpelajari, sedangkan jaringan appearance Deep OC-SORT adalah checkpoint re-identification terbitan yang diunduh saat penggunaan pertama. Peningkatan kualitas tracking berarti memperbaiki detektor atau menyesuaikan ambang batas asosiasi di atas.