Utiliser des modèles tiers de suivi d’objet avec ArcGIS

Disponible avec une licence Image Analyst.

La fonctionnalité de suivi d’objet dans l’imagerie animée vous permet de localiser un objet d’intérêt, de suivre son mouvement pendant la lecture de la vidéo et de gérer les objets suivis tout au long du processus. Cette fonctionnalité utilise des modèles de Deep Learning entraînés à suivre des objets en mouvement ou immobiles et à les réidentifier après des périodes de masquage à travers les images vidéo afin de maintenir un suivi cohérent pendant la lecture vidéo. La fonctionnalité de suivi d’objet repose sur des modèles de Deep Learning entraînés empaquetés sous forme de fichiers .dlpk pour effectuer le suivi, et vous pouvez configurer ces modèles directement dans l’onglet Object Tracking (Suivi d’objet).

Pour plus de détails sur le fonctionnement du suivi d’objet dans les images en mouvement, voir Suivi d’objet dans l’imagerie animée.

Bien que la fonctionnalité de suivi d’objet dans ArcGIS Pro offre un suivi basé sur le Deep Learning, la création d’un nouveau modèle dans ArcGIS demande souvent un effort considérable. Les modèles de suivi de haute qualité reposent sur de nombreuses données d’entraînement étiquetées, et l’entraînement de modèles de Deep Learning peut être exigeant en calcul. Dans ArcGIS Pro, vous pouvez utiliser des modèles de Deep Learning tiers pour suivre des objets. Les développeurs Python peuvent préparer leurs modèles de suivi, les empaqueter en tant que fichiers .dlpk compatibles, puis les charger directement via l’interface de suivi d’objet pour les utiliser dans les processus d’imagerie animée.

Fonctionnalité de suivi d’objet Python personnalisée

Vous pouvez créer une fonction de suivi d’objet personnalisée dans Python pour intégrer des modèles de Deep Learning tiers dans le processus de suivi d’imagerie animée. Ces fonctions permettent à ArcGIS Pro d’utiliser des modèles de Deep Learning externes pour initialiser, maintenir et gérer les objets suivis dans les données vidéo.

Les méthodes de fonctionnalité de suivi d’objet sont répertoriées dans le tableau suivant et sont décrites en détail dans les sous-sections ci-dessous.

Méthode	Description
`__init__`	Initialise des variables d’instance telles que le nom de la fonction, la description, les références de modèle et d’autres attributs nécessaires à la fonctionnalité de suivi d’objet.
`initialize`	Charge le modèle de suivi d’objet et effectue la configuration nécessaire avant le début du suivi. Cette opération est effectuée une fois au début de la fonction.
`getParameterInfo`	Définit les paramètres que la fonctionnalité de suivi d’objet accepte. Cela inclut les paramètres de configuration requis pour charger ou se connecter au modèle, ainsi que les valeurs nécessaires aux paramètres de suivi.
`getConfiguration`	Décrit comment la fonction traitera les images vidéo et produira des sorties de suivi. Cela inclut les détails des étapes de prétraitement ou de post-traitement nécessaires à la fonction.
`init_tracker`	Initialise le suiveur d’objet en utilisant l’image vidéo initiale et l’emprise fournie par l’utilisateur autour de l’objet à suivre. Cette méthode configure l’état interne nécessaire pour commencer le suivi.
`track`	Effectue le suivi sur chaque nouvelle image vidéo. Cette méthode met à jour la position de l'objet et retourne l’emprise ou le centroïde résultant pour l'objet suivi.

Méthodes des fonctions

Les méthodes des fonctions de suivi sont décrites ci-dessous.

Utilisez la méthode init

La méthode __init__ est le constructeur de la classe de suivi d’objets personnalisée. Elle initialise des variables d’instance telles que le nom, la description, les références aux modèles de Deep Learning et d’autres attributs nécessaires au suivi des objets dans les données vidéo. Cette méthode configure l’état initial de la fonction de suivi et garantit que tous les paramètres par défaut et les propriétés requises sont définis avant le début du suivi.

Lors de la création d’une instance de la classe de suivi d’objet, le constructeur prépare tout ce qui est nécessaire au suivi, comme les références de modèle, les paramètres de suivi par défaut ou d’autres options de configuration nécessaires aux méthodes init_tracker et track.

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

Utiliser la méthode d’initialisation

La méthode initialize est appelée au début de la fonction de suivi d’objet personnalisée. Cette méthode reçoit kwargs['model'], qui est le chemin ou l’URL du fichier de paquetage de Deep Learning Esri (.dlpk). Utilisez cette méthode pour charger les pondérations du modèle et configurer le suiveur, et garantir ainsi qu’une référence au modèle chargé est disponible pour les opérations suivantes telles que init_tracker et track.

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

Utiliser la méthode getParameterInfo

La méthode getParameterInfo est nommée d’après la méthode initialize, et c’est dans cette méthode que les paramètres nécessaires à la fonction de suivi d’objet sont définis. Cette méthode renvoie une liste des paramètres en entrée attendus par le suiveur personnalisé. Chaque paramètre est décrit à l’aide d’un dictionnaire contenant le nom, le type de données, le nom d’affichage et la description et indique si le paramètre est obligatoire, comme illustré ci-dessous.

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

Les attributs clés de chaque dictionnaire incluent les éléments suivants :

name : identifiant de chaîne du paramètre
dataType : type de données accepté par le paramètre (chaîne, numérique, booléen, etc.)
value : valeur par défaut du paramètre
required : valeur booléenne indiquant si le paramètre est obligatoire
displayName : nom convivial affiché dans l’interface utilisateur
description : description détaillée du paramètre

La liste des paramètres est affichée par l’intermédiaire des arguments du modèle personnalisé dans ArcGIS Pro. Vous pouvez définir ces valeurs de façon interactive à l’aide de l’interface de suivi d’objet ou les transmettre par programmation à la fonction de suivi en tant qu’arguments de mots-clés.

Utiliser la méthode init_tracker

La méthode init_tracker initialise le suiveur d’objet en utilisant l’image vidéo initiale et les emprises fournies par l’utilisateur autour de chaque objet à suivre. Elle prépare l’état interne nécessaire pour commencer le suivi, y compris l’attribution d’ID d’objets uniques, la conversion des emprises au format requis et l’appel de la routine d’initialisation du suiveur sous-jacent.

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)

Utiliser la méthode de suivi

La méthode track met à jour la position de l’objet pour chaque nouvelle image vidéo. Une fois le traceur initialisé avec init_tracker, cette méthode est appelée à plusieurs reprises — une fois par image — pour maintenir la trajectoire de l’objet pendant la lecture vidéo.

La méthode prend l’image vidéo actuelle en entrée, applique le suiveur sous-jacent basé sur le Deep Learning, et renvoie l’emprise ou le centroïde mis à jour pour l’objet suivi. Elle peut également produire des métadonnées supplémentaires telles que le suivi des scores de confiance ou des identifiants d’objets, selon le modèle.

Cette méthode est centrale au processus de suivi, car elle permet la localisation continue des objets à travers les images tout en gérant des défis tels que le mouvement, l’occlusion, les changements d’échelle et les variations d’apparence.

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

Utiliser un fichier .emd Esri pour le suivi d’objet

Après avoir créé une fonction de suivi d’objet Python personnalisée, vous devez la référencer dans le fichier .emd (Esri Model Definition) en la spécifiant sous le paramètre InferenceFunction. Cela relie le fichier .emd à votre fonction de suivi Python afin qu’ArcGIS Pro puisse le charger et l’exécuter pendant le processus de suivi d’objet.

Un fichier .emd standard ressemble à ce qui suit :

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

Utiliser un fichier .dlpk personnalisé

Pour réaliser une configuration personnalisée de suivi d’objet, vous devez empaqueter votre fonction de suivi et modéliser les actifs dans un fichier .dlpk. Le fichier .dlpk permet à ArcGIS Pro de charger votre suiveur personnalisé via la fonctionnalité de suivi d’objet dans l’imagerie animée.

Organisez les fichiers comme suit :

Créez un dossier contenant le fichier Python de suivi d’objet personnalisé (par exemple, MyObjectTracker.py) et le fichier de définition du modèle .emd Esri (par exemple, ObjectTracker.emd).

Le nom du dossier doit correspondre au nom du fichier .emd (à l’exclusion de l’extension).

Par exemple, la structure peut ressembler à ce qui suit :
```
ObjectTracker/
├── MyObjectTracker.py
└── ObjectTracker.emd
```
Incluez tous les actifs supplémentaires requis par votre suiveur, tels que les éléments suivants :
- Des fichiers de pondération de modèle (.pth, .onnx, etc.)
- Des fichiers de configuration
- Des modules de support ou des scripts utilitaires
- Dépendances du suiveur (si elles sont incluses localement)
Compressez le dossier en archive ZIP.
Renommez le fichier .zip pour qu’il corresponde au nom du fichier .emd mais utilise l’extension .dlpk.

Consultez l’exemple ci-dessous :
```
ObjectTracker.zip  →  ObjectTracker.dlpk
```

Une fois empaqueté, le modèle peut être chargé dans l’onglet Object Tracking (Suivi d’objet) et utilisé immédiatement pour initialiser, suivre et gérer des objets à travers les images vidéo, pour des processus de suivi efficaces et évolutifs.