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:

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

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 lain mencerminkan prediksi: iou, imgsz, classes, max_det, vid_stride, show, dan save bersama output_path. Sumber adalah path berkas video. Lihat prediksi untuk penanganan hasil.

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.