Uso de modelos de seguimiento de objetos de terceros con ArcGIS

Disponible con licencia de Image Analyst.

La capacidad de seguimiento de objetos en imágenes en movimiento le permite localizar un objeto de interés, seguir su movimiento mientras se reproduce el vídeo y gestionar los objetos bajo seguimiento a lo largo del flujo de trabajo. Esta capacidad utiliza modelos de aprendizaje profundo entrenados para realizar el seguimiento de objetos en movimiento o estacionarios y reidentificar objetos tras periodos de oscurecimiento a través de los fotogramas de vídeo para mantener un seguimiento uniforme durante su reproducción. La capacidad de seguimiento de objetos depende de modelos de aprendizaje profundo entrenados empaquetados en forma de archivos .dlpk para realizar el seguimiento. Estos modelos pueden configurarse directamente en la pestaña Seguimiento de Objetos.

Para obtener información sobre el funcionamiento del seguimiento de objetos en imágenes en movimiento, véase Seguimiento de objetos en imágenes en movimiento

Aunque la capacidad de seguimiento de objetos en ArcGIS Pro proporciona un seguimiento basado en aprendizaje profundo, crear un nuevo modelo en ArcGIS a menudo requiere un esfuerzo considerable. Los modelos de seguimiento de alta calidad dependen de una extensa cantidad de datos de entrenamiento etiquetados, y entrenar modelos de aprendizaje profundo puede requerir una potencia de cálculo alta. ArcGIS Pro le permite usar modelos de aprendizaje profundo de terceros para realizar el seguimiento de objetos. Los desarrolladores de Python pueden preparar sus modelos de seguimiento, empaquetarlos en forma de archivos .dlpk compatibles y cargarlos directamente a través de la interfaz de seguimiento de objetos para usarlos en flujos de trabajo de imágenes en movimiento.

Función personalizada de seguimiento de objetos en Python

Puede crear una función personalizada de seguimiento de objetos en Python para integrar modelos de deep learning de terceros en el flujo de trabajo de seguimiento de imágenes en movimiento. Estas funciones permiten a ArcGIS Pro utilizar modelos externos de aprendizaje profundo para inicializar, gestionar y realizar el mantenimiento de objetos bajo seguimiento en datos de vídeo.

Los métodos de la función de seguimiento de objetos se enumeran en la siguiente tabla y se describen en detalle en las subsecciones a continuación.

Método	Descripción
`__init__`	Inicializa variables de instancia como el nombre de la función, la descripción, las referencias al modelo y otros atributos necesarios para la función de seguimiento de objetos.
`initialize`	Carga el modelo de seguimiento de objetos y lleva a cabo cualquier configuración necesaria antes de que comience el seguimiento. Esto se hace una vez al inicio de la función.
`getParameterInfo`	Define los parámetros que acepta la función de seguimiento de objetos. Esto incluye cualquier ajuste de configuración necesario para cargar o conectarse al modelo, así como los parámetros necesarios para los ajustes relacionados con el seguimiento.
`getConfiguration`	Describe cómo la función procesará los fotogramas de vídeo y producirá salidas de seguimiento. Incluye detalles para cualquier paso de preprocesamiento o posprocesamiento necesario para la función.
`init_tracker`	Inicializa el rastreador usando el fotograma inicial de vídeo y la caja delimitadora proporcionada por el usuario alrededor del objeto bajo seguimiento. Este método establece el estado interno necesario para comenzar el seguimiento.
`track`	Realiza seguimiento en cada nuevo fotograma de vídeo. Este método actualiza la posición del objeto y devuelve la caja delimitadora o centroide resultante para el objeto bajo seguimiento.

Métodos de la función

A continuación, se describen los métodos de la función de seguimiento de objetos.

Uso del método init

El método __init__ es el constructor de la clase personalizada de seguimiento de objetos. Inicializa variables de instancia como el nombre, la descripción, referencias a modelos de aprendizaje profundo y otros atributos necesarios para realizar el seguimiento de objetos en datos de vídeo. Este método establece el estado inicial de la función de seguimiento y garantiza que todos los ajustes por defecto y las propiedades requeridas estén definidos antes de que comience el seguimiento.

Al crear una instancia de la clase de seguimiento de objetos, el constructor prepara todo lo necesario para el seguimiento, como referencias de modelos, parámetros de seguimiento por defecto u otras opciones de configuración requeridas por los métodos init_tracker y 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
     ...

Uso del método de inicialización

El método initialize se llama al inicio de la función de seguimiento de objetos personalizada. Este método recibe el argumento de palabra clave ['model'], que es la ruta o URL del archivo de paquete de aprendizaje profundo de Esri (.dlpk). Utilice este método para cargar los pesos del modelo y configurar el rastreador, asegurándose que haya una referencia al modelo cargado disponible para operaciones posteriores como init_tracker y 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
 ...

Uso del método getParameterInfo

El método getParameterInfo se llama así por el método initialize y es donde se definen los parámetros que la función de seguimiento de objetos requiere. Este método devuelve una lista de los parámetros de entrada esperados por el reastreador personalizado. Cada parámetro se describe mediante un diccionario que contiene el nombre, el tipo de datos, el nombre de visualización, la descripción y si es obligatorio o no, como se muestra a continuación.

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

Entre los atributos clave de cada diccionario tenemos los siguientes:

name: un identificador de cadena de caracteres para el parámetro
dataType: el tipo de datos que acepta el parámetro (cadena, numérico, booleano, etc.)
value: el valor predeterminado del parámetro
required: un booleano que indica si el parámetro es obligatorio
displayName: un nombre fácil de usar mostrado en la interfaz
description: una descripción detallada del parámetro

La lista de parámetros se muestra a través de los argumentos del modelo personalizado en ArcGIS Pro. Los usuarios pueden establecer estos valores de forma interactiva mediante la interfaz de usuario de la herramienta o pasarlos mediante programación al método como argumentos de palabra clave.

Uso del método init_tracker

El método init_tracker inicializa el rastreador de objetos usando el fotograma de vídeo inicial y las cajas delimitadoras proporcionadas por el usuario alrededor de cada objeto para rastrear. Prepara el estado interno necesario para comenzar el seguimiento, incluidas la asignación de ID únicos de objetos, la conversión de cajas delimitadoras al formato requerido y la llamada a la rutina de inicialización del rastreador subyacente.

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)

Uso del método de seguimiento

El método track actualiza la posición del objeto para cada nuevo fotograma de vídeo. Después de que el rastreador se haya inicializado usando init_tracker, este método se llama repetidamente —una vez por fotograma— para mantener la trayectoria del objeto mientras se reproduce el vídeo.

El método toma el fotograma de vídeo actual como entrada, aplica el rastreador subyacente basado en aprendizaje profundo y devuelve la caja delimitadora o centroide actualizado para el objeto bajo seguimiento. También puede generar metadatos adicionales como puntuaciones de seguimiento de confianza o identificadores de objetos, dependiendo del modelo.

Este método es fundamental para el flujo de trabajo de seguimiento, ya que permite la localización continua de objetos a lo largo de fotogramas mientras gestiona dificultades como el movimiento, la oclusión, los cambios de escala y las variaciones en la apariencia.

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

Uso de un archivo .emd de Esri para el seguimiento de objetos

Después de crear una función personalizada de seguimiento de objetos en Python, debe referenciarla en el archivo .emd (definición de modelo de Esri) especificándola bajo el parámetro InferenceFunction. Esto vincula el archivo .emd a su función de seguimiento en Python para que ArcGIS Pro pueda cargarlo y ejecutarlo durante el flujo de trabajo de seguimiento de objetos.

Un archivo típico .emd se parece a lo siguiente:

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

Uso de un archivo .dlpk personalizado

Para completar una configuración personalizada de seguimiento de objetos, debe empaquetar su función de seguimiento y los activos del modelo en un archivo .dlpk. El archivo .dlpk permite a ArcGIS Pro cargar su rastreador personalizado a través de la capacidad de seguimiento de objetos en Imágenes en movimiento.

Organice los archivos de la siguiente manera:

Crea una carpeta que contenga el archivo Python personalizado para seguimiento de objetos (por ejemplo, MyObjectTracker.py) y el archivo de definición del modelo Esri .emd (por ejemplo, ObjectTracker.emd).

El nombre de la carpeta debe coincidir con el nombre del archivo .emd (excluyendo la extensión).

Por ejemplo, la estructura puede parecerse a la siguiente:
```
ObjectTracker/
├── MyObjectTracker.py
└── ObjectTracker.emd
```
Incluya cualquier recurso adicional que requiera su rastreador, como los siguientes:
- Archivos de peso de modelos (.pth, .onnx, etc.)
- Archivos de configuración
- Módulos complementarios o scripts auxiliares
- Dependencias del rastreador (si se incluyen en local)
Comprima la carpeta en un archivo ZIP.
Cambie el nombre del archivo .zip para que coincida con el nombre de archivo .emd pero con la extensión .dlpk.

Vea el siguiente ejemplo:
```
ObjectTracker.zip  →  ObjectTracker.dlpk
```

Una vez empaquetado, el modelo puede cargarse en la pestaña Seguimiento de Objetos y usarse inmediatamente para inicializar, seguir y gestionar objetos a lo largo de fotogramas de vídeo y disfrutar de flujos de trabajo de seguimiento eficientes y escalables.