将第三方对象追踪模型与 ArcGIS 结合使用

需具有 Image Analyst 许可才能使用。

动态视频影像中的对象追踪功能用于定位感兴趣对象，追踪其在视频播放过程中的移动，并在整个工作流中管理被追踪对象。该功能使用经过训练的深度学习模型，能够追踪移动或静止的对象，并在视频帧间出现一段时间的模糊后重新识别对象，以保持视频播放期间的追踪一致性。对象追踪功能依赖于以 .dlpk 文件形式打包的已训练深度学习模型来执行追踪，您可以直接在对象追踪选项卡上配置这些模型。

有关动态视频影像中对象追踪的工作原理的详细信息，请参阅动态视频影像中的对象追踪

虽然 ArcGIS Pro 中的对象追踪功能提供基于深度学习的追踪，但在 ArcGIS 中创建新模型通常需要大量工作。高质量追踪模型依赖于大量带标注的训练数据，而训练深度学习模型计算量大。在 ArcGIS Pro 中，可使用第三方深度学习模型追踪对象。 Python 开发人员可以准备追踪模型，将其打包成兼容的 .dlpk 文件，并直接通过对象追踪界面进行加载，以用于动态视频影像工作流。

自定义 Python 对象追踪函数

可在 Python 中创建自定义对象追踪函数，以将第三方深度学习模型集成到动态视频影像追踪工作流中。这些函数允许 ArcGIS Pro 使用外部深度学习模型初始化、维护和管理视频数据中的追踪对象。

下表列出了对象追踪函数方法，有关详细说明，请参阅以下小节。

方法	描述
`__init__`	初始化实例变量，如函数名称、说明、模型引用及对象追踪函数所需的其他属性。
`initialize`	加载对象追踪模型，并在开始追踪前完成所需的所有设置。这在函数开始时执行一次。
`getParameterInfo`	定义对象追踪函数接受的参数。这包括加载或连接模型所需的所有配置设置以及追踪相关设置所需的参数。
`getConfiguration`	描述函数如何处理视频帧并生成追踪输出。包括该函数所需的任何预处理或后处理步骤的详细信息。
`init_tracker`	利用初始视频帧和用户在要追踪对象周围提供的边界框初始化追踪器。该方法用于设置开始追踪所需的内部状态。
`track`	对每个新的视频帧执行追踪。该方法会更新对象位置，并返回追踪对象的边界框或质心。

函数方法

下面介绍了对象追踪函数方法。

使用 init 方法

__init__ 方法是自定义对象追踪类的构造函数。它会初始化实例变量，如名称、描述、对深度学习模型的引用以及追踪视频数据中对象所需的其他属性。该方法会设置追踪器函数的初始状态，并确保在追踪开始前定义所有默认设置和所需属性。

在创建对象追踪类实例时，构造函数会准备追踪所需的所有内容，如模型引用、默认追踪参数或 init_tracker 和 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
     ...

使用初始化方法

initialize 方法在自定义对象追踪函数的开头被调用。该方法会接收 kwargs['model']，即 Esri 深度学习包文件 (.dlpk) 的路径或 URL。使用此方法可加载模型权重并设置追踪器，确保对已加载模型的引用适用于后续操作，例如 init_tracker 和 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
 ...

使用 getParameterInfo 方法

getParameterInfo 方法在initialize 方法之后调用，可在其中定义对象追踪函数所需参数。此方法将返回自定义追踪器所需的输入参数列表。每个参数通过包含名称、数据类型、显示名称、描述以及参数是否为必需项的字典进行描述，如下所示。

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

每个字典的关键属性包括如下所示：

name - 参数的字符串标识符
dataType - 参数接受的数据类型（字符串、数值、布尔等）
value - 参数的默认值
required - 指示参数是否为必需项的布尔值
displayName - 用户界面中显示的用户友好名称
description - 参数的详细描述

参数列表通过 ArcGIS Pro 中的自定义模型参数进行显示。可使用对象追踪界面以交互方式设置这些值，或者以编程方式将其作为关键字参数传递到追踪函数中。

使用 init_tracker 方法

init_tracker 方法利用初始视频帧和用户在要追踪的每个对象周围提供的边界框初始化对象追踪器。它准备开始追踪所需的内部状态，包括分配唯一对象 ID、将边界框转换为所需格式，以及调用基础追踪器的初始化例程。

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)

使用追踪方法

track 方法会更新每个新视频帧的对象位置。在使用 init_tracker 初始化追踪器后，会重复调用该方法（每帧一次），以在视频播放时保持对象轨迹。

该方法以当前视频帧为输入，应用基于深度学习的基础追踪器，并返回追踪对象已更新边界框或质心。根据不同的模型，它还可能生成其他元数据，如追踪置信度得分或对象标识符。

该方法对于追踪工作流至关重要，因为它能够实现跨帧的连续对象定位，同时应对运动、遮挡、比例变化和外观变化等挑战。

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

使用 Esri .emd 文件进行对象追踪

在创建自定义 Python 对象追踪函数后，必须在 .emd（Esri 模型定义）文件中通过在 InferenceFunction 参数下指定该函数对其进行引用。这会将 .emd 文件链接到 Python 追踪函数，以便 ArcGIS Pro 可在对象追踪工作流中加载和运行该文件。

典型的 .emd 文件类似于以下内容：

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

使用自定义 .dlpk 文件

要完成自定义对象追踪设置，必须将追踪函数和模型资产打包成 .dlpk 文件。 .dlpk 文件允许 ArcGIS Pro 通过动态视频影像中的对象追踪功能加载自定义追踪器。

按如下方式组织文件：

创建一个包含自定义对象追踪 Python 文件（例如 MyObjectTracker.py）和 Esri .emd 模型定义文件（例如 ObjectTracker.emd）的文件夹。

文件夹名称必须与 .emd 文件名（不包括扩展名）一致。

例如，结构可能类似于以下内容：
```
ObjectTracker/
├── MyObjectTracker.py
└── ObjectTracker.emd
```
包含追踪器需要的任何其他资产，如下所示：
- 模型权重文件（.pth、.onnx 等）
- 配置文件
- 支持模块或实用程序脚本
- 追踪器依赖关系（如果本地包含）
将该文件夹压缩为 ZIP 归档。
重命名 .zip 文件，使其与 .emd 文件名一致，但使用 .dlpk 扩展名。

请参阅以下示例：
```
ObjectTracker.zip  →  ObjectTracker.dlpk
```

打包后，模型可加载到对象追踪选项卡上，并立即用于初始化、追踪和管理跨视频帧的对象，从而支持高效且可扩展的追踪工作流。