# medipipe

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

mediapipe.py。

描述：此脚本包含用于解码 MediaPipe 手部跟踪模型输出的实用函数。

此脚本包含基于或直接取自公共 GitHub 存储库的代码：[https://github.com/geaxgx/depthai_hand_tracker](https://github.com/geaxgx/depthai_hand_tracker)

原始代码作者：geaxgx

许可证：MIT 许可证

版权所有 (c) [2021] [geax]

## 类

### HandRegion

存储检测到的手掌及其派生的旋转区域。

#### 方法

##### init

```python
def __init__(pd_score=None, pd_box=None, pd_kps=None):
```

在派生旋转区域之前存储手掌检测值。

参数

 * `pd_score`：可选的检测置信度。
 * `pd_box`：可选的归一化 `[x, y, width, height]` 框。
 * `pd_kps`：可选的归一化手掌关键点。

#### 属性

##### pd_box

正方形图像中的归一化 `[x, y, width, height]` 框。

##### pd_kps

正方形图像中的归一化 `[x, y]` 手掌关键点。

##### pd_score

手掌检测置信度。

##### rect_h

归一化矩形高度，可能超过 1。

##### rect_h_a

正方形图像像素中的矩形高度。

##### rect_points

像素中的四个矩形角点。坐标在处理期间指正方形图像，返回时指源图像。

##### rect_w

归一化矩形宽度，可能超过 1。

##### rect_w_a

正方形图像像素中的矩形宽度。

##### rect_x_center

归一化旋转矩形中心 X 坐标。

##### rect_x_center_a

正方形图像像素中的矩形中心 X 坐标。

##### rect_y_center

归一化旋转矩形中心 Y 坐标。

##### rect_y_center_a

正方形图像像素中的矩形中心 Y 坐标。

##### rotation

矩形相对于 Y 轴的旋转，以弧度表示。

## 函数

### calculate_scale

```python
def calculate_scale(min_scale, max_scale, stride_index, num_strides):
```

在特征步幅上插值锚点比例。

参数

 * `min_scale`：第一个步幅处的比例。
 * `max_scale`：最后一个步幅处的比例。
 * `stride_index`：从零开始的步幅索引。
 * `num_strides`：步幅数量；当为 1 时，使用中点比例。

返回

 * 插值的锚点比例。

### compute_mediapipe_palm_detections

```python
def compute_mediapipe_palm_detections(bboxes: np.ndarray, scores: np.ndarray, *, anchors: np.ndarray, conf_threshold: float, iou_threshold: float, max_det: int, scale: int, label_names: list[str] | None = None) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, list[str] | None]:
```

将 MediaPipe 手掌解码为旋转检测并应用抑制。

参数

 * `bboxes` (`np.ndarray`)：每个锚点的手掌框和地标预测。
 * `scores` (`np.ndarray`)：每个锚点的手掌分数 logits。
 * `anchors` (`np.ndarray`)：用于解码模型预测的预计算锚点坐标。
 * `conf_threshold` (`float`)：用于过滤候选的最小检测置信度。
 * `iou_threshold` (`float`)：用于非极大值抑制的交并比阈值。
 * `max_det` (`int`)：在抑制期间保留或考虑的最大检测候选数量。
 * `scale` (`int`)：正方形模型输入的边长（像素）。
 * `label_names` (`list[str] | None`)：按预测类别 ID 索引的可选类别名称查找。

返回

 * `tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, list[str] | None]`：归一化的中心 XY/宽度/高度框、置信度分数、角度（度）、零值类别 ID 和可选类别名称。

### decode

```python
def decode(bboxes, scores, anchors, threshold=0.5, scale=192):
```

解码手掌预测并附加旋转的像素矩形。

参数

 * `bboxes`：形状为 `(N, 18)` 的每个锚点的框和地标偏移。
 * `scores`：每个锚点的一个分数 logit。
 * `anchors`：与模型输入维度匹配的预计算锚点。
 * `threshold`：保留检测的最小 sigmoid 分数。
 * `scale`：正方形模型输入的边长（像素）。

返回

 * `HandRegion` 对象列表，包含归一化的手掌几何形状和像素空间旋转矩形。

### decode_bboxes

```python
def decode_bboxes(score_thresh, scores, bboxes, anchors, scale=128, best_only=False):
```

使用 SSD 锚点解码手掌框和七个地标。

参数

 * `score_thresh`：保留手掌的最小 sigmoid 置信度。
 * `scores`：每个锚点的一个分数 logit。
 * `bboxes`：形状为 `(N, 18)` 的每个锚点的框和地标偏移。
 * `anchors`：与预测计数匹配的归一化中心 XY/宽度/高度锚点。
 * `scale`：用于归一化预测偏移的模型输入边长。
 * `best_only`：用于最高分数选择的兼容性标志；标准解码路径使用 false。

返回

 * 包含归一化手掌框和关键点的 `HandRegion` 对象列表。宽度或高度为负的框将被丢弃。

引发

 * `IndexError`：如果预测和锚点无法一起选择。当前最高分数路径在候选满足阈值时也会引发。

### detections_to_rect

```python
def detections_to_rect(regions):
```

将归一化旋转矩形几何形状添加到每个手掌中。

参数

 * `regions`：具有手掌框和地标的手部区域。手腕到中指的方向决定旋转。

### generate_anchors

```python
def generate_anchors(options):
```

使用 MediaPipe 的锚点布局生成 SSD 锚点。

基于 MediaPipe `ssd_anchors_calculator.cc` 实现。

参数

 * `options` (`SSDAnchorOptions`)：层大小、步幅、比例和纵横比。

返回

 * `[x_center, y_center, width, height]` 格式的锚点数组。

### generate_handtracker_anchors

```python
def generate_handtracker_anchors(input_size_width, input_size_height):
```

为 MediaPipe 手掌检测布局生成锚点。

参数

 * `input_size_width`：模型输入宽度（像素）。
 * `input_size_height`：模型输入高度（像素）。

返回

 * 步幅为 8、16、16 和 16 的归一化中心 XY/宽度/高度锚点数组。

### normalize_radians

```python
def normalize_radians(angle):
```

将角度包装到区间 [-pi, pi)。

参数

 * `angle`：输入角度（弧度）。

返回

 * 等效角度，介于 -pi（包含）和 pi（不包含）之间。

### rect_transformation

```python
def rect_transformation(regions, w, h, no_shift=False):
```

将旋转区域转换为像素矩形。

参数

 * `regions`：已由 `detections_to_rect()` 填充的区域。
 * `w`：源图像宽度（像素）。
 * `h`：源图像高度（像素）。
 * `no_shift`：如果为 false，则向手指方向移动并将正方形扩展 2.9 倍；如果为 true，则保持中心并使用原始较长边。

### rotated_rect_to_points

```python
def rotated_rect_to_points(cx, cy, w, h, rotation):
```

将旋转矩形转换为整数像素角点。

参数

 * `cx`：矩形中心 X 坐标。
 * `cy`：矩形中心 Y 坐标。
 * `w`：矩形宽度（像素）。
 * `h`：矩形高度（像素）。
 * `rotation`：旋转角度（弧度）。

返回

 * 周长顺序的四个整数 XY 坐标列表。

## 属性

### SSDAnchorOptions
