# xfeat

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

## Functions

### bilinear

```python
def bilinear(im, pos, H, W):
```

Given an input and a flow-field grid, computes the output using input values and pixel locations from grid. Supported only
bilinear interpolation method to sample the input pixels.

Parameters

 * `im` (`np.ndarray`): Input feature map, shape (N, C, H, W)
 * `pos` (`np.ndarray`): Point coordinates, shape (N, Hg, Wg, 2)
 * `H` (`int`): Height of the output feature map
 * `W` (`int`): Width of the output feature map

Returns

 * `np.ndarray`: A tensor with sampled points, shape (N, C, Hg, Wg)

### compute_xfeat_matches

```python
def compute_xfeat_matches(result1: dict[str, Any], result2: dict[str, Any], min_cossim: float = -1) -> tuple[np.ndarray, np.ndarray]:
```

Match XFeat descriptors by mutual nearest-neighbor similarity.

Parameters

 * `result1` (`dict[str, Any]`): Reference result containing `keypoints` and `descriptors`.
 * `result2` (`dict[str, Any]`): Target result containing `keypoints` and `descriptors`.
 * `min_cossim` (`float`): Minimum descriptor cosine similarity; a non-positive value disables this threshold.

Returns

 * `tuple[np.ndarray, np.ndarray]`: Reference and target keypoint arrays of shape `(N, 2)` in corresponding order.

### compute_xfeat_result

```python
def compute_xfeat_result(feats: np.ndarray, keypoints: np.ndarray, heatmaps: np.ndarray, *, resize_rate_w: float, resize_rate_h: float, input_size: tuple[int, int], max_keypoints: int) -> list[dict[str, Any]] | None:
```

Compute ranked XFeat keypoints and descriptors.

Parameters

 * `feats` (`np.ndarray`): Batched dense feature-descriptor tensor.
 * `keypoints` (`np.ndarray`): Model keypoint tensor.
 * `heatmaps` (`np.ndarray`): Model heatmap tensor.
 * `resize_rate_w` (`float`): Horizontal scale factor mapping model coordinates to the source image.
 * `resize_rate_h` (`float`): Vertical scale factor mapping model coordinates to the source image.
 * `input_size` (`tuple[int, int]`): Model input size as `(width, height)`.
 * `max_keypoints` (`int`): Maximum number of highest-scoring keypoints retained per image.

Returns

 * `list[dict[str, Any]] | None`: One result dictionary per batch item, with `keypoints`, `scores`, and `descriptors`. Returns
   `None` when no candidate keypoints are found.

### detect_and_compute

```python
def detect_and_compute(feats: np.ndarray, kpts: np.ndarray, heatmaps: np.ndarray, resize_rate_w: float, resize_rate_h: float, input_size: tuple[int, int], top_k: int = 4096) -> list[dict[str, Any]]:
```

Detect and compute keypoints.

Parameters

 * `feats` (`np.ndarray`): Features.
 * `kpts` (`np.ndarray`): Keypoints.
 * `heatmaps` (`np.ndarray`): Heatmaps.
 * `resize_rate_w` (`float`): Resize rate for width.
 * `resize_rate_h` (`float`): Resize rate for height.
 * `input_size` (`tuple[int, int]`): Input size.
 * `top_k` (`int`): Maximum number of keypoints to keep.

Returns

 * `list[dict[str, Any]]`: List of dictionaries containing keypoints, scores, and descriptors.

### local_maximum_filter

```python
def local_maximum_filter(x: np.ndarray, kernel_size: int) -> np.ndarray:
```

Apply a local maximum filter to the input array.

Parameters

 * `x` (`np.ndarray`): Input array.
 * `kernel_size` (`int`): Size of the local maximum filter.

Returns

 * `np.ndarray`: Output array after applying the local maximum filter.

### match

```python
def match(result1: dict[str, Any], result2: dict[str, Any], min_cossim: float = -1) -> tuple[np.ndarray, np.ndarray]:
```

Match keypoints.

Parameters

 * `result1` (`dict[str, Any]`): Result 1.
 * `result2` (`dict[str, Any]`): Result 2.
 * `min_cossim` (`float`): Minimum cosine similarity.

Returns

 * `tuple[np.ndarray, np.ndarray]`: Matched keypoints.

### normgrid

```python
def normgrid(x, H, W):
```

Normalize coords to [-1,1].

Parameters

 * `x` (`np.ndarray`): Input coordinates, shape (N, Hg, Wg, 2)
 * `H` (`int`): Height of the output feature map
 * `W` (`int`): Width of the output feature map

Returns

 * `np.ndarray`: Normalized coordinates, shape (N, Hg, Wg, 2)