Verwenden von Objektverfolgungsmodellen von Drittanbietern mit ArcGIS

Mit Image Analyst-Lizenz verfügbar.

Mit der Objektverfolgungsfunktion von Motion Imagery können Sie relevante Objekte suchen, bei der Videowiedergabe ihre Bewegungen verfolgen und verfolgte Objekte während des gesamten Workflow verwalten. Bei dieser Funktion werden Deep-Learning-Modelle verwendet, die dafür trainiert sind, bewegliche oder stationäre Objekte zu verfolgen und Objekte nach Phasen der Verdeckung über Videobilder hinweg erneut zu identifizieren, um eine konsistente Verfolgung während der Videowiedergabe zu gewährleisten. Die Objektverfolgungsfunktion basiert auf trainierten Deep-Learning-Modellen, die als .dlpk-Dateien gepackt sind, um die Verfolgung durchzuführen. Sie können diese Modelle direkt auf der Registerkarte Objektverfolgung konfigurieren.

Weitere Informationen zur Funktionsweise der Objektverfolgung in Motion Imagery finden Sie unter Objektverfolgung in bewegten Bilddaten.

Während die Objektverfolgungsfunktion in ArcGIS Pro Deep-Learning-basierte Verfolgung bietet, erfordert die Erstellung eines neuen Modells innerhalb von ArcGIS oft erheblichen Aufwand. Hochwertige Verfolgungsmodelle basieren auf umfangreichen beschrifteten Trainingsdaten, und das Training von Deep-Learning-Modellen kann rechenintensiv sein. In ArcGIS Pro können Sie Deep-Learning-Modelle von Drittanbietern verwenden, um Objekte zu verfolgen. Python-Entwickler können ihre Verfolgungsmodelle vorbereiten, sie als kompatible .dlpk-Dateien packen und sie direkt über die Objektverfolgungsoberfläche für den Einsatz in Motion Imagery-Workflows laden.

Benutzerdefinierte Python-Objektverfolgungsfunktion

Sie können eine benutzerdefinierte Objektverfolgungsfunktion in Python erstellen, um Deep-Learning-Modelle von Drittanbietern in den Motion Imagery-Verfolgungs-Workflow zu integrieren. Diese Funktionen ermöglichen ArcGIS Pro die Verwendung externer Deep-Learning-Modelle zur Initialisierung, Wartung und Verwaltung verfolgter Objekte in Videodaten.

Die Methoden der Objektverfolgungsfunktion sind in der folgenden Tabelle aufgelistet und in den folgenden Unterabschnitten ausführlich beschrieben.

Methode	Beschreibung
`__init__`	Initialisiert Instanzvariablen, wie zum Beispiel Funktionsname, Beschreibung, Modellreferenzen und weitere Attribute, die für die Objektverfolgungsfunktion erforderlich sind.
`initialize`	Lädt das Objektverfolgungsmodell und nimmt erforderliche Einrichtungen vor, bevor die Verfolgung beginnt. Dies geschieht einmal zu Beginn der Funktion.
`getParameterInfo`	Definiert die Parameter, die von der Objektverfolgungsfunktion akzeptiert werden. Dazu gehören die Konfigurationseinstellungen, die zum Laden des Modells oder Verbinden mit dem Modell erforderlich sind, sowie die Parameter, die für verfolgungsbezogene Einstellungen erforderlich sind.
`getConfiguration`	Beschreibt, wie die Funktion Videobilder verarbeitet und Verfolgungsausgaben erzeugt. Dazu gehören Details für die Vorverarbeitungs- oder Nachbearbeitungsschritte, die für die Funktion erforderlich sind.
`init_tracker`	Initialisiert den Tracker mithilfe des initialen Videobildes und des vom Benutzer bereitgestellten umgebenden Rechtecks um das zu verfolgende Objekt. Mit dieser Methode wird der interne Zustand eingerichtet, der für den Beginn der Verfolgung erforderlich ist.
`track`	Führt die Verfolgung für jedes neue Videobild durch. Mit dieser Methode wird die Position des Objekts aktualisiert und das resultierende umgebende Rechteck oder der Schwerpunkt für das verfolgte Objekt zurückgegeben.

Funktionsmethoden

Die Methoden der Objektverfolgungsfunktion werden nachfolgend beschrieben.

Verwenden der init-Methode

Die __init__-Methode ist der Konstruktor der benutzerdefinierten Objektverfolgungsklasse. Sie initialisiert Instanzvariablen, wie zum Beispiel Name, Beschreibung, Deep-Learning-Modellreferenzen und weitere Attribute, die für die die Verfolgung von Objekten in Videodaten erforderlich sind. Mit dieser Methode wird der Anfangszustand der Tracker-Funktion eingerichtet und sichergestellt, dass alle Standardeinstellungen und erforderlichen Eigenschaften vor Beginn der Verfolgung definiert sind.

Beim Erstellen einer Instanz der Objektverfolgungsklasse bereitet der Konstruktor alles Notwendige für die Verfolgung vor, beispielsweise Modellreferenzen, Standardverfolgungsparameter oder andere Konfigurationsoptionen, die von den Methoden init_tracker und track benötigt werden.

class MyObjectTracker:
 def __init__(self, **kwargs):
     """
     Initializes the object tracker by setting up its core properties,  
     including name, description, and any additional configuration parameters.
     """
     self.name = "Object Tracker"
     self.description = (
         "The `MyObjectTracker` class is designed to perform object tracking "
         "in video data using a pre-trained deep learning model."
     )
     self.model = None  # Placeholder for the deep learning model (.dlpk)
     # Additional initialization code here
     ...

Verwenden der initialize-Methode

Die initialize-Methode wird zu Beginn der benutzerdefinierten Objektverfolgungsfunktion aufgerufen. Diese Methode empfängt "kwargs['model']", das heißt den Pfad oder die URL der Esri Deep-Learning-Paketdatei (.dlpk). Verwenden Sie diese Methode zum Laden der Modellgewichtungen und zum Einrichten des NLP-Modells, damit eine Referenz für das geladene Modell für nachfolgende Operationen wie init_tracker und track vorhanden ist.

def initialize(self, **kwargs):
 """
 Initialize object tracking model parameters, including loading the pretrained
 deep learning model from a `.dlpk` file.
 """
 dlpk_path = kwargs['model']  # Path or URL to the `.dlpk` file
  
 # Load the deep learning package
 self.model = load_deep_learning_model(dlpk_path)
  
 # Additional initialization code here, e.g., setting default tracking parameters
 ...

Verwenden der getParameterInfo-Methode

Die getParameterInfo-Methode wird nach der initialize-Methode aufgerufen. In ihr werden die von der Objektverfolgungsfunktion benötigten Parameter definiert. Diese Methode gibt eine Liste der vom benutzerdefinierten Tracker erwarteten Eingabeparameter zurück. Jeder Parameter wird unter Verwendung eines Wörterbuchs, in dem Name, Datentyp, Anzeigename und Beschreibung des Parameters enthalten sind, und Informationen dazu, ob dieser Parameter erforderlich ist, wie nachfolgend dargestellt beschrieben.

def getParameterInfo(self):
 return [
     {
         "name": "confidence_threshold",
         "dataType": "numeric",
         "required": False,
         "displayName": "Confidence Threshold",
         "description": "Minimum confidence score required to maintain a tracked object.",
         "value": 0.1
     },
     # Additional tracking parameters here
     ...
 ]

Zu den Schlüsselattributen jedes Wörterbuchs gehören die folgenden:

name: Ein Zeichenfolgebezeichner für den Parameter
dataType: Der Datentyp, den der Parameter akzeptiert (Zeichenfolge, Ziffernfolge, boolescher Wert usw.)
value: Der Standardwert für den Parameter
required: Ein boolescher Wert, der angibt, ob der Parameter erforderlich ist
displayName: Ein bedienfreundlicher Name, der auf der Bedienoberfläche angezeigt wird
description: Eine detaillierte Beschreibung des Parameters

Die Liste der Parameter wird über die Argumente des benutzerdefinierten Modells in ArcGIS Pro angezeigt. Sie können diese Werte interaktiv auf der Bedienoberfläche eines Werkzeugs festlegen oder sie programmgesteuert als Schlüsselwortargumente an die Verfolgungsfunktion übergeben.

Verwenden der init_tracker-Methode

Die init_tracker-Methode initialisiert den Objekt-Tracker mithilfe des initialen Videobildes und der vom Benutzer bereitgestellten umgebenden Rechtecke um jedes zu verfolgende Objekt. Sie bereitet den internen Zustand vor, der für den Beginn der Verfolgung erforderlich ist, einschließlich der Zuweisung eindeutiger Objekt-IDs, der Konvertierung umgebender Rechtecke in das erforderliche Format und des Aufrufens der Initialisierungsroutine des zugrunde liegenden Trackers.

def init_tracker(self, frame, boxes):
 """
 Prepare the tracker using the initial frame and bounding boxes.
 """
 # Convert user-provided boxes to float arrays
 boxes = ensure_numpy_array_of_floats(boxes)

 for box in boxes:
     # Store unique object ID
     self.obj_id = int(box[0])
     self.labels = np.array([1], dtype=np.int32)

     # Convert from [x_min, y_min, x_max, y_max] to [x, y, w, h]
     bbox = box[1:]
     bbox = [bbox[0], bbox[1], bbox[2] - bbox[0], bbox[3] - box[1]]

     # Initialize the underlying tracker
     self._tracker.initialize(frame, bbox)

Verwenden der track-Methode

Die track-Methode aktualisiert die Position des Objekts für jedes neue Videobild. Nachdem der Tracker mit init_tracker initialisiert wurde, wird diese Methode wiederholt (einmal pro Bild) aufgerufen, um die Trajektorie des Objekts während der Videowiedergabe beizubehalten.

Die Methode verwendet das aktuelle Videobild als Eingabe, wendet den zugrunde liegenden Deep-Learning-basierten Tracker an und gibt das aktualisierte umgebende Rechteck oder den Schwerpunkt für das verfolgte Objekt zurück. Sie kann je nach Modell auch zusätzliche Metadaten wie Verfolgungskonfidenzwerte oder Objektkennungen erzeugen.

Diese Methode ist zentral für den Verfolgungs-Workflow, da sie eine kontinuierliche Objektlokalisierung über Bilder hinweg ermöglicht und gleichzeitig Herausforderungen wie Bewegung, Verdeckung, Maßstabsänderungen und variierendes Aussehen bewältigt.

def track(self, frame):
 """
 Update the tracked object's bounding box using the current frame.
 """
 # Get updated bounding box from the underlying tracker
 tracked_bbox = self._tracker.track(frame)

 # Convert [x, y, w, h] to [x_min, y_min, x_max, y_max]
 x, y, w, h = tracked_bbox
 # Convert center/width/height representation to rectangle coordinates
 location = cxy_wh_2_rect(...)
 # int(x_min), int(y_min), int(x_max), int(y_max)
 x1, y1, x2, y2 = ...

 # Prepare ArcGIS-formatted output
 all_bboxes = [[float(self.obj_id), float(x1), float(y1), float(x2), float(y2)]]
 return all_bboxes

Verwenden einer Esri EMD-Datei für die Objektverfolgung

Nach dem Erstellen einer benutzerdefinierten Python-Objektverfolgungsfunktion müssen Sie diese in der .emd-Datei (Esri Model Definition) referenzieren, indem Sie sie unter dem Parameter InferenceFunction angeben. Dadurch wird die .emd-Datei mit der Python-Verfolgungsfunktion verknüpft, sodass ArcGIS Pro sie während des Objektverfolgungs-Workflow laden und ausführen kann.

Eine typische .emd-Datei sieht in etwa wie folgt aus:

{
 "InferenceFunction": "MyObjectTracker.py",
 "ModelType": "ObjectTracker",
 "ModelFile": "model_weights.pth",
 // additional keys here
 ...
}

Verwenden einer benutzerdefinierten DLPK-Datei

Um ein benutzerdefiniertes Objektverfolgungs-Setup abzuschließen, müssen Sie die Objektverfolgungsfunktion und die Modell-Assets in einer .dlpk-Datei packen. Die .dlpk Datei ermöglicht ArcGIS Pro das Laden des benutzerdefinierten Trackers über die Objektverfolgungsfunktion in Motion Imagery.

Organisieren Sie die Dateien wie folgt:

Erstellen Sie einen Order, der die Python-Datei für die benutzerdefinierte Objektverfolgung (zum Beispiel MyObjectTracker.py) und die Esri .emd-Datei (Modelldefinitionsdatei) (zum Beispiel ObjectTracker.emd) enthält.

Der Ordnername muss mit dem Namen der .emd-Datei (ohne die Erweiterung) übereinstimmen.

Die Struktur kann in etwa wie folgt aussehen:
```
ObjectTracker/
├── MyObjectTracker.py
└── ObjectTracker.emd
```
Fügen Sie alle zusätzlichen für den Tracker erforderlichen Assets hinzu, wie zum Beispiel die folgenden:
- Modellgewichtungsdateien (.pth, .onnx usw.)
- Konfigurationsdateien
- Unterstützende Module oder Dienstprogrammskripte
- Tracker-Abhängigkeiten (falls lokal enthalten)
Komprimieren Sie den Ordner in ein ZIP-Archiv.
Benennen Sie die .zip-Datei so, dass sie dem Namen der .emd-Datei, jedoch mit der Erweiterung .dlpk, entspricht.

Beispiel:
```
ObjectTracker.zip  →  ObjectTracker.dlpk
```

Nach dem Packen kann das Modell auf der Registerkarte "Objektverfolgung" geladen und sofort zur Initialisierung, Verfolgung und Verwaltung von Objekten über Videobilder hinweg verwendet werden. Dadurch werden effiziente und skalierbare Verfolgungs-Workflows unterstützt.