# xfeat

Python API: `depthai_nodes.node.parsers.xfeat`

## 类

### XFeatBaseParser

用于解析 XFeat 模型输出的基础解析器类。它是 XFeatMonoParser 和 XFeatStereoParser 类的父类。

抛出

 * `ValueError`: 如果输出层数量不是 3。
 * `ValueError`: 如果未指定原始图像大小。
 * `ValueError`: 如果未指定输入图像大小。
 * `ValueError`: 如果未指定最大关键点数量。
 * `ValueError`: 如果未指定包含特征的输出层。
 * `ValueError`: 如果未指定包含关键点的输出层。
 * `ValueError`: 如果未指定包含热图的输出层。

#### 方法

##### init

```python
def __init__(output_layer_feats: str = '', output_layer_keypoints: str = '', output_layer_heatmaps: str = '', original_size: tuple[float, float] = None, input_size: tuple[float, float] = (640, 352), max_keypoints: int = 4096):
```

存储张量名称和图像几何体以进行 XFeat 解码。

参数

 * `output_layer_feats` (`str`): 特征描述符层名称。
 * `output_layer_keypoints` (`str`): 关键点对数层名称。
 * `output_layer_heatmaps` (`str`): 可靠性热图层名称。
 * `original_size` (`tuple[float, float]`): 源图像大小，格式为 `(宽度, 高度)`。
 * `input_size` (`tuple[float, float]`): 模型输入大小，格式为 `(宽度, 高度)`。
 * `max_keypoints` (`int`): 要保留的最大特征点数量。

##### build

```python
def build(head_config: dict[str, Any]) -> XFeatBaseParser:
```

配置解析器。

参数

 * `head_config` (`dict[str, Any]`): 解析器的头部配置。

返回

 * `XFeatBaseParser`: 设置了头部配置的解析器对象。

##### extractTensors

```python
def extractTensors(output: dai.NNData) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
```

从输出中提取张量。它返回特征、关键点和热图。它还通过请求 NCHW 存储顺序来处理张量的重塑。

参数

 * `output` (`dai.NNData`): 神经网络节点的输出。

返回

 * `tuple[np.ndarray, np.ndarray, np.ndarray]`: 特征、关键点和热图的元组。

##### reference_input.setter

```python
def reference_input.setter(reference_input: dai.Node.Input | None):
```

替换存储的 XFeat 输入端口。

参数

 * `reference_input` (`dai.Node.Input | None`): 相应神经网络流的输入端口。

##### setInputSize

```python
def setInputSize(input_size: tuple[int, int]):
```

设置输入图像大小。

参数

 * `input_size` (`tuple[int, int]`): 输入图像大小。

##### setMaxKeypoints

```python
def setMaxKeypoints(max_keypoints: int):
```

设置要保留的最大关键点数量。

参数

 * `max_keypoints` (`int`): 最大关键点数量。

##### setOriginalSize

```python
def setOriginalSize(original_size: tuple[int, int]):
```

设置原始图像大小。

参数

 * `original_size` (`tuple[int, int]`): 原始图像大小。

##### setOutputLayerFeats

```python
def setOutputLayerFeats(output_layer_feats: str):
```

设置包含特征的输出层。

参数

 * `output_layer_feats` (`str`): 包含特征的输出层名称。

##### setOutputLayerHeatmaps

```python
def setOutputLayerHeatmaps(output_layer_heatmaps: str):
```

设置包含热图的输出层。

参数

 * `output_layer_heatmaps` (`str`): 包含热图的输出层名称。

##### setOutputLayerKeypoints

```python
def setOutputLayerKeypoints(output_layer_keypoints: str):
```

设置包含关键点的输出层。

参数

 * `output_layer_keypoints` (`str`): 包含关键点的输出层名称。

##### target_input.setter

```python
def target_input.setter(target_input: dai.Node.Input | None):
```

替换存储的 XFeat 输入端口。

参数

 * `target_input` (`dai.Node.Input | None`): 相应神经网络流的输入端口。

##### validateParams

```python
def validateParams(self):
```

验证参数。

#### 属性

##### input

##### input_size

输入图像大小。

##### max_keypoints

要保留的最大关键点数量。

##### original_size

原始图像大小。

##### output_layer_feats

包含特征的输出层名称。

##### output_layer_heatmaps

包含热图的输出层名称。

##### output_layer_keypoints

包含关键点的输出层名称。

##### reference_input

返回参考输入。

##### target_input

返回目标输入。

### XFeatMonoParser

用于解析 XFeat 模型输出的解析器类。它可用于解析来自一个源（例如一个摄像头）的输出。参考帧可以通过触发方法设置。

> **Note**
> 发出 `dai.TrackedFeatures` 消息。TrackedFeatures 消息包含具有相同 ID 的匹配关键点。

抛出

 * `ValueError`: 如果未指定原始图像大小。
 * `ValueError`: 如果未指定输入图像大小。
 * `ValueError`: 如果未指定最大关键点数量。
 * `ValueError`: 如果未指定包含特征的输出层。
 * `ValueError`: 如果未指定包含关键点的输出层。
 * `ValueError`: 如果未指定包含热图的输出层。

#### 方法

##### init

```python
def __init__(output_layer_feats: str = 'feats', output_layer_keypoints: str = 'keypoints', output_layer_heatmaps: str = 'heatmaps', original_size: tuple[float, float] = None, input_size: tuple[float, float] = (640, 352), max_keypoints: int = 4096):
```

初始化 XFeatParser 节点。

参数

 * `output_layer_feats` (`str`): 包含特征的输出层名称。
 * `output_layer_keypoints` (`str`): 包含关键点的输出层名称。
 * `output_layer_heatmaps` (`str`): 包含热图的输出层名称。
 * `original_size` (`tuple[float, float]`): 原始图像大小。
 * `input_size` (`tuple[float, float]`): 输入图像大小。
 * `max_keypoints` (`int`): 要保留的最大关键点数量。

##### compute

```python
def compute(feats: np.ndarray, keypoints: np.ndarray, heatmaps: np.ndarray, *, resize_rate_w: float, resize_rate_h: float) -> dict[str, Any] | None:
```

计算第一个批次项的特征。

参数

 * `feats` (`np.ndarray`): 批处理的密集特征描述符张量。
 * `keypoints` (`np.ndarray`): 模型关键点张量。
 * `heatmaps` (`np.ndarray`): 模型热图张量。
 * `resize_rate_w` (`float`): 将模型坐标映射到源图像的水平比例因子。
 * `resize_rate_h` (`float`): 将模型坐标映射到源图像的垂直比例因子。

返回

 * `dict[str, Any] | None`: 包含第一个图像的关键点、分数和描述符的字典，如果没有找到候选者则为 `None`。

##### emit

```python
def emit(output: dai.NNData, result: dict[str, Any] | None):
```

将特征与存储的参考进行匹配并发出跟踪点。

> **Note**
> 如果没有当前特征或没有参考，则发出空消息。复制当前时间戳和序列号。待处理的触发器在匹配后用非 None 结果替换存储的参考。

参数

 * `output` (`dai.NNData`): 携带张量和源时间戳、序列号以及可选图像变换的神经网络输出。
 * `result` (`dict[str, Any] | None`): 当前计算的关键点、分数和描述符，或 `None`。

##### extract

```python
def extract(output: dai.NNData) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
```

从一个网络结果中提取特征、关键点和热图张量。

参数

 * `output` (`dai.NNData`): 携带张量和源时间戳、序列号以及可选图像变换的神经网络输出。

返回

 * `tuple[np.ndarray, np.ndarray, np.ndarray]`: 特征描述符、关键点对数和热图的元组，由 `extractTensors()` 生成。

##### run

```python
def run(self):
```

读取排队的网络输出，解析它们，并在运行时发出结果。

管道调用此处理循环。当输入队列关闭或节点停止时，它会退出。

##### setTrigger

```python
def setTrigger(self):
```

设置触发器以设置参考帧。

#### 属性

##### input_size

输入图像大小。

##### max_keypoints

要保留的最大关键点数量。

##### original_size

原始图像大小。

##### output_layer_feats

包含特征的输出层名称。

##### output_layer_heatmaps

包含热图的输出层名称。

##### output_layer_keypoints

包含关键点的输出层名称。

##### previous_results

模型之前的结果。之前的结果用于匹配两个帧之间的关键点。

##### trigger

设置参考帧的触发器。

### XFeatStereoParser

用于解析 XFeat 模型输出的解析器类。它可用于解析来自两个源（例如两个摄像头 - 左和右）的输出。

> **Note**
> 发出 `dai.TrackedFeatures` 消息。TrackedFeatures 消息包含具有相同 ID 的匹配关键点。

抛出

 * `ValueError`: 如果未指定原始图像大小。
 * `ValueError`: 如果未指定输入图像大小。
 * `ValueError`: 如果未指定最大关键点数量。
 * `ValueError`: 如果未指定包含特征的输出层。
 * `ValueError`: 如果未指定包含关键点的输出层。
 * `ValueError`: 如果未指定包含热图的输出层。

#### 方法

##### init

```python
def __init__(output_layer_feats: str = 'feats', output_layer_keypoints: str = 'keypoints', output_layer_heatmaps: str = 'heatmaps', original_size: tuple[float, float] = None, input_size: tuple[float, float] = (640, 352), max_keypoints: int = 4096):
```

初始化 XFeatParser 节点。

参数

 * `output_layer_feats` (`str`): 包含特征的输出层名称。
 * `output_layer_keypoints` (`str`): 包含关键点的输出层名称。
 * `output_layer_heatmaps` (`str`): 包含热图的输出层名称。
 * `original_size` (`tuple[float, float]`): 原始图像大小。
 * `input_size` (`tuple[float, float]`): 输入图像大小。
 * `max_keypoints` (`int`): 要保留的最大关键点数量。

##### compute

```python
def compute(reference_tensors: tuple[np.ndarray, np.ndarray, np.ndarray], target_tensors: tuple[np.ndarray, np.ndarray, np.ndarray], *, resize_rate_w: float, resize_rate_h: float) -> dict[str, tuple[np.ndarray, np.ndarray] | str | None]:
```

计算并匹配参考张量和目标张量之间的特征。

参数

 * `reference_tensors` (`tuple[np.ndarray, np.ndarray, np.ndarray]`): 参考特征、关键点和热图张量。
 * `target_tensors` (`tuple[np.ndarray, np.ndarray, np.ndarray]`): 目标特征、关键点和热图张量。
 * `resize_rate_w` (`float`): 应用于关键点坐标的水平比例因子。
 * `resize_rate_h` (`float`): 应用于关键点坐标的垂直比例因子。

返回

 * `dict[str, tuple[np.ndarray, np.ndarray] | str | None]`: 包含 `status`（`matched`、`reference_missing` 或 `target_missing`）和
   `match_result`（配对点数组，或 `None`）的字典。

##### emit

```python
def emit(reference_output: dai.NNData, target_output: dai.NNData, result: dict[str, tuple[np.ndarray, np.ndarray] | str | None]):
```

发出匹配的参考点和目标点，或空特征消息。

参数

 * `reference_output` (`dai.NNData`): 提供序列号，如果参考特征缺失，则提供时间戳。
 * `target_output` (`dai.NNData`): 提供匹配和缺失目标特征的时间戳。
 * `result` (`dict[str, tuple[np.ndarray, np.ndarray] | str | None]`): `compute()` 返回的状态和配对点。

##### extract

```python
def extract(reference_output: dai.NNData, target_output: dai.NNData) -> tuple[tuple[np.ndarray, np.ndarray, np.ndarray], tuple[np.ndarray, np.ndarray, np.ndarray]]:
```

从两个网络结果中提取匹配的张量。

参数

 * `reference_output` (`dai.NNData`): 参考图像网络输出。
 * `target_output` (`dai.NNData`): 目标图像网络输出。

返回

 * `tuple[tuple[np.ndarray, np.ndarray, np.ndarray], tuple[np.ndarray, np.ndarray, np.ndarray]]`: 参考和目标元组，每个元组包含特征、关键点对数和热图。

##### run

```python
def run(self):
```

读取排队的网络输出，解析它们，并在运行时发出结果。

管道调用此处理循环。当输入队列关闭或节点停止时，它会退出。

#### 属性

##### input_size

输入图像大小。

##### max_keypoints

要保留的最大关键点数量。

##### original_size

原始图像大小。

##### out

解析器将处理后的网络结果以 DepthAI 消息的形式发送到此输出。它是检索处理后的网络结果的链接点。

##### output_layer_feats

从中提取特征的输出层名称。

##### output_layer_heatmaps

从中提取热图的输出层名称。

##### output_layer_keypoints

从中提取关键点的输出层名称。

##### reference_input

节点的输入。它是神经网络输出的链接点。它接受神经网络节点的输出。

##### target_input

节点的输入。它是神经网络输出的链接点。它接受神经网络节点的输出。
