Objekt-Tracking

Definition

Tracking ist keiner der Aufgabenschlüssel von LibreYOLO, und es gibt keinen Tracking-Checkpoint zum Herunterladen. Es ist eine Modellmethode namens model.track(source), die in jedem Frame Erkennungen ausführt und die Ergebnisse zeitlich zuordnet. Die Methode ist ein Generator. Sie liefert pro verarbeitetem Frame ein Results-Objekt, in dem result.track_id auf einen an result.boxes ausgerichteten ganzzahligen Tensor der Form (N,) gesetzt ist. Dieselben IDs stehen auch in result.boxes.id.

Nur bestätigte und aktuell verfolgte Objekte werden ausgegeben. Ein Track, den die Zuordnung verliert, bleibt für eine konfigurierte Anzahl von Frames aktiv, bevor er verworfen wird. Diese Option heißt track_buffer bei ByteTrack und BoT-SORT sowie max_age bei den beiden OC-SORT-Varianten. Ein innerhalb dieses Fensters wiedergefundenes Objekt behält daher seine ursprüngliche ID.

Da die Zuordnung nach der Erkennung erfolgt, bleiben die anderen Payloads des Frames erhalten. Das verfolgte Results-Objekt ist die auf die zugeordneten Zeilen beschränkte Erkennungsausgabe. Masken und Keypoints werden daher zusammen mit den Boxen übernommen.

Modelle

Ein Tracking-Lauf umfasst zwei unabhängige Entscheidungen: das Modell, das in jedem Frame Boxen erzeugt, und den Tracker, der sie verknüpft.

Jedes native LibreYOLO-Modell für Erkennung, Segmentierung oder Pose stellt track() bereit. Der Detektor wird daher wie üblich ausgewählt. Eine vollständige Liste findest du im Modellindex. Du kannst auch mit YOLO9, RF-DETR, D-FINE oder RTMDet beginnen. Aufgaben ohne zuordenbare Box lehnen den Aufruf ab, statt bedeutungslose IDs zurückzugeben. Klassifikation, orientierte Boxen, Punkte, Tiefe, Oberflächennormalen, Kanten, semantische und panoptische Segmentierung, Restaurierung, OCR und Body Mesh lösen jeweils in track() einen Fehler aus.

Zwei Modellstufen von LibreYOLO lehnen den Aufruf ebenfalls ab. Über LibreSAM geladene Modelle sind Bildsegmentierer, und über LibreOpenVocab geladene Modelle sind frameweise Detektoren. Bei beiden löst track() einen Fehler aus. Verwende stattdessen für jeden Frame predict().

Tracking läuft auf nativen PyTorch-Modellen. Ein exportiertes und mit LibreYOLO("model.onnx") geladenes Artefakt gibt ein Runtime-Backend-Objekt zurück. Dieses stellt predict(), aber nicht track() bereit.

Die Bibliothek enthält vier Tracker, die du mit dem Argument tracker auswählst. Die .yaml-Schreibweisen wie "bytetrack.yaml" wählen dieselben eingebauten Tracker aus; LibreYOLO liest keine Tracker-YAML-Dateien und löst einen Fehler aus, wenn im Arbeitsverzeichnis eine Datei dieses Namens existiert.

"bytetrack" ist der Standard. Es verwendet ausschließlich Bewegung, einen Kalman-Filter und eine dreistufige Zuordnung: zuerst Erkennungen mit hoher Confidence, anschließend einen zweiten Durchlauf, in dem Erkennungen mit niedriger Confidence einem bestehenden Track zugeordnet werden können, bevor sie verworfen werden, und zuletzt unbestätigte Tracks. Die Konfiguration erfolgt mit TrackConfig.

"botsort" übernimmt den dreistufigen Lebenszyklus von ByteTrack, verwendet aber einen Kalman-Zustand aus Mittelpunkt, Breite und Höhe. Vor der Zuordnung kompensiert es die vorhergesagten Tracks um die Kamerabewegung. Dies ist die nur bewegungsbasierte Variante von BoT-SORT und verwendet kein Erscheinungsmodell. Die Konfiguration erfolgt mit BoTSortConfig, das enable_cmc, cmc_method und cmc_downscale ergänzt.

"ocsort" verwendet ebenfalls nur Bewegung. Es ergänzt die Zuordnungskosten um einen Term für die Geschwindigkeitsrichtung, führt einen zweiten Zuordnungsdurchlauf anhand der letzten echten Beobachtung jedes Tracks aus und glättet beim Wiederfinden eines Tracks den Kalman-Zustand entlang einer virtuellen Trajektorie. Die Konfiguration erfolgt mit OCSortConfig.

"deepocsort" ergänzt OC-SORT um Erscheinungsmerkmale. Jeder Track hält einen nach Confidence gewichteten gleitenden Mittelwert aus Re-Identification-Embeddings. Ein Term für Kosinusähnlichkeit geht in die Zuordnungskosten ein, damit Identitäten lange Verdeckungen und sich kreuzende Ziele überstehen. Dafür ist pro Frame ein Forward Pass durch ein kleines Embedding-Netz erforderlich. Seine OSNet-Gewichte werden bei der ersten Verwendung heruntergeladen. Die Konfiguration erfolgt mit DeepOCSortConfig.

Vorhersage

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # track() ist ein Generator: ein Results-Objekt je verarbeitetem Frame.for result in model.track("video.mp4"):    print(result.track_id)        # (N,) Int-Tensor, an Boxen ausgerichtet    print(result.boxes.xyxy)

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

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Ohne output_path landet die Datei in 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") # Der Konfigurationstyp wählt den Tracker, tracker= ist hier redundant.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) # Oder dieselben Felder als Keyword-Argumente übergeben.for result in model.track("video.mp4", tracker="botsort", track_buffer=60):    print(result.track_id)

track_conf legt den Schwellenwert für die erste Zuordnungsstufe fest: track_high_thresh für ByteTrack und BoT-SORT sowie det_thresh für OC-SORT und Deep OC-SORT. Dies ist nicht conf von predict(). Bei ByteTrack, BoT-SORT und OC-SORT läuft der Detektor intern mit einem niedrigeren Schwellenwert, damit schwache Erkennungen für den Wiederherstellungsdurchlauf verfügbar bleiben. Deep OC-SORT führt den Detektor mit det_thresh selbst aus. Bei ByteTrack und BoT-SORT muss track_conf mindestens track_low_thresh entsprechen, dessen Standardwert 0.1 ist.

conf ist, sofern angegeben, der Detektionsschwellenwert von predict(): Erkennungen darunter erreichen den Tracker nie. Ohne conf läuft der Detektor mit den oben genannten Schwellenwerten.

Tracker-Einstellungen können auf zwei Arten übergeben werden. Übergib eine Konfigurationsinstanz als tracker_config=. Ihr Typ wählt den Tracker aus und macht tracker= überflüssig. Alternativ übergibst du die Felder als Keyword-Argumente und lässt track() die Konfiguration für den benannten Tracker erstellen. Bei unbekannten Schlüsseln wird eine Warnung ausgegeben, statt sie unbemerkt anzuwenden. In beiden Fällen wird track_conf ignoriert, sobald der entsprechende Schlüssel explizit gesetzt ist.

Die übrigen Argumente entsprechen der Vorhersage: iou, imgsz, classes, max_det, vid_stride, show und save mit output_path. persist=True behält den Tracker und seine IDs aus dem vorherigen track()-Aufruf auf demselben Modell bei, für eine Schleife, die einen Frame pro Aufruf übergibt, etwa model.track(frame, persist=True). Die Quelle kann ein Video oder eine geordnete Bildsequenz sein. Siehe Vorhersage für die Ergebnisverarbeitung.

Bilder, nach Dateinamen sortierte Ordner, Listen, Tupel und verzögerte Bilditeratoren können aufeinanderfolgende Frames liefern. fps=30.0 legt deren Zeitabstand fest und color_format="auto" die Interpretation der Eingabe. vid_stride senkt die beibehaltene Rate auf fps / vid_stride.

Übergib eine eigene Tracker-Instanz über tracker=. Sie implementiert reset() und update(results, image=None) aus libreyolo.tracking.Tracker. Ein Lauf setzt sie einmal zurück und übergibt den ursprünglichen RGB-PIL-Frame. Das zurückgegebene track_id muss ein eindimensionales Integer-Array oder ein Tensor sein, ausgerichtet an den Boxen und auf demselben Backend/Gerät. Eigene Instanzen verwenden standardmäßig track_conf=0.25; konfiguriere die Instanz direkt, statt Tracker-Schlüsselwortargumente oder tracker_config zu übergeben.

Training

Tracker werden nicht trainiert. Drei der vier sind reine Bewegungsmodelle ohne gelernte Parameter. Das Erscheinungsnetz von Deep OC-SORT ist ein veröffentlichter Re-Identification-Checkpoint, der bei der ersten Verwendung heruntergeladen wird. Verbessere für eine höhere Tracking-Qualität den Detektor oder stimme die oben genannten Zuordnungsschwellenwerte ab.