# spatial_transforms

Python API: `luxonis_train.utils.spatial_transforms`

将模型看到的调整大小后的图像中的边界框、关键点和掩码映射回原始图像。

## 函数

### compute_ratio_and_padding

```python
def compute_ratio_and_padding(orig_h: int, orig_w: int, train_size: tuple[int, int], keep_aspect_ratio: bool) -> tuple[float | None, float, float]:
```

计算 letterbox 调整大小的比例和填充。

如果 `keep_aspect_ratio` 为 true，则比例 r = min(ht ⁄ ho, wt ⁄ wo)，其中 (ht, wt) 是 `train_size`，(ho, wo) 是原始大小。填充 px = (wt − r**wo) ⁄
2（左右），py = (ht − r**ho) ⁄ 2（上下）。如果 `keep_aspect_ratio` 为 false，加载器会拉伸图像，因此函数不返回比例和填充。

> **示例**
> ```pycon
>>> from luxonis_train.utils.spatial_transforms import (
...     compute_ratio_and_padding,
... )
>>> compute_ratio_and_padding(100, 200, (200, 200), True)
(1.0, 0.0, 50.0)
>>> compute_ratio_and_padding(100, 200, (200, 200), False)
(None, 0, 0)
```

参数

 * `orig_h` (`int`): 原始图像的高度，以像素为单位。
 * `orig_w` (`int`): 原始图像的宽度，以像素为单位。
 * `train_size` (`tuple[int, int]`): 模型输入的高度和宽度。
 * `keep_aspect_ratio` (`bool`): 加载器是否对图像进行了 letterbox 处理。

返回

 * `tuple[float | None, float, float]`: 比例 r、填充 px 和填充 py。如果 `keep_aspect_ratio` 为 false，结果为 `(None, 0, 0)`。

### transform_boxes

```python
def transform_boxes(raw_boxes: np.ndarray, orig_h: int, orig_w: int, train_size: tuple[int, int], keep_aspect_ratio: bool) ->
np.ndarray:
```

将边界框从模型输入转换为原始图像。

如果 `keep_aspect_ratio` 为 true，函数会减去填充并除以 [compute_ratio_and_padding](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/spatial_transforms.md) 中的比例。然后将坐标除以原始宽度和高度。它不会裁剪结果，因此填充中的边界框会得到 `[0, 1]` 之外的值。

警告： 如果 `keep_aspect_ratio` 为 false，函数不会从 `train_size` 缩放边界框。只有当原始大小等于 `train_size` 时，结果才正确。

> **示例**
> ```pycon
>>> import numpy as np
>>> from luxonis_train.utils import transform_boxes
>>> boxes = np.array([[20.0, 60.0, 120.0, 110.0]])
>>> transform_boxes(boxes, 100, 200, (200, 200), True).tolist()
[[0.1, 0.1, 0.5, 0.5]]
```

参数

 * `raw_boxes` (`np.ndarray`): 模型输入像素中的边界框，形状为 `[N, 4]`，采用 `xyxy` 格式。
 * `orig_h` (`int`): 原始图像的高度，以像素为单位。
 * `orig_w` (`int`): 原始图像的宽度，以像素为单位。
 * `train_size` (`tuple[int, int]`): 模型输入的高度和宽度。
 * `keep_aspect_ratio` (`bool`): 加载器是否对图像进行了 letterbox 处理。

返回

 * `np.ndarray`: 形状为 `[N, 4]` 的边界框，采用归一化的 `xywh` 格式，其中 `x` 和 `y` 表示左上角。空的 `raw_boxes` 会得到形状为 `[0]` 的空数组。

### transform_keypoints

```python
def transform_keypoints(raw_kpts: np.ndarray, orig_h: int, orig_w: int, train_size: tuple[int, int], keep_aspect_ratio: bool) -> np.ndarray:
```

将关键点从模型输入转换为原始图像。

如果 `keep_aspect_ratio` 为 true，函数会减去填充并除以
[compute_ratio_and_padding](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/spatial_transforms.md)
中的比例。然后将 `x` 除以原始宽度，将 `y` 除以原始高度。第三个值不变。函数不会裁剪结果。

警告： 如果 `keep_aspect_ratio` 为 false，函数不会从 `train_size` 缩放关键点。只有当原始大小等于 `train_size` 时，结果才正确。

> **示例**
> ```pycon
>>> import numpy as np
>>> from luxonis_train.utils import transform_keypoints
>>> kpts = np.array([[[100.0, 100.0, 2.0]]])
>>> transform_keypoints(kpts, 100, 200, (200, 200), True).tolist()
[[[0.5, 0.5, 2.0]]]
```

参数

 * `raw_kpts` (`np.ndarray`): 模型输入像素中的关键点，形状为 `[N, K, 3]`。最后一个轴包含 `x`、`y` 和可见性或分数。
 * `orig_h` (`int`): 原始图像的高度，以像素为单位。
 * `orig_w` (`int`): 原始图像的宽度，以像素为单位。
 * `train_size` (`tuple[int, int]`): 模型输入的高度和宽度。
 * `keep_aspect_ratio` (`bool`): 加载器是否对图像进行了 letterbox 处理。

返回

 * `np.ndarray`: 形状为 `[N, K, 3]` 的关键点，为 `float64` 类型，`x` 和 `y` 已归一化。

### transform_masks

```python
def transform_masks(raw_masks: np.ndarray, orig_h: int, orig_w: int, train_size: tuple[int, int], keep_aspect_ratio: bool) ->
np.ndarray:
```

将掩码从模型输入转换为原始图像。

如果 `keep_aspect_ratio` 为 true，函数会从每个掩码中裁剪填充。它会将裁剪边界截断为整数。然后使用最近邻插值将每个掩码调整为原始大小。

> **示例**
> ```pycon
>>> import numpy as np
>>> from luxonis_train.utils import transform_masks
>>> masks = np.zeros((1, 200, 200), dtype=np.float32)
>>> masks[:, 50:150] = 1.0
>>> result = transform_masks(masks, 100, 200, (200, 200), True)
>>> result.shape, float(result.min())
((1, 100, 200), 1.0)
```

参数

 * `raw_masks` (`np.ndarray`): 模型输入大小的掩码，形状为 `[N, H, W]`。`N` 必须至少为 `1`，因为 `np.stack` 拒绝空列表。数据类型必须是 `cv2.resize` 接受的类型，例如
   `float32`。
 * `orig_h` (`int`): 原始图像的高度，以像素为单位。
 * `orig_w` (`int`): 原始图像的宽度，以像素为单位。
 * `train_size` (`tuple[int, int]`): 模型输入的高度和宽度。
 * `keep_aspect_ratio` (`bool`): 加载器是否对图像进行了 letterbox 处理。

返回

 * `np.ndarray`: 形状为 `[N, orig_h, orig_w]` 的掩码。
