# rope_position_encoding

Python API: `luxonis_train.nodes.backbones.dinov3.rope_position_encoding`

DINOv3 的旋转位置编码，已更改为导出到 ONNX。

## 类

### RopePositionEmbedding

DINOv3 的轴向旋转位置编码，没有可学习的权重。

该模块计算 DINOv3 注意力用于旋转查询和键向量的正弦和余弦表。`H x W`
网格的每个补丁都会获得其中心的坐标。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md)
将它们除以 `normalize_coords` 选择并将每个坐标 c 映射到 2c − 1。使用 `"separate"` 或 `"max"`，结果在 `[-1, 1]` 中。使用 `"min"`，较长轴的坐标可以大于
`1`。每个角度仅取决于一个轴，因此轴不会混合。对于坐标 c 和周期 p，角度为 2π**c ⁄ p。

周期来自两种设置之一。D 是头部维度，`embed_dim // num_heads`。

 * `base`: pi = base2i ⁄ (D ⁄ 2) 对于 i = 0, …, D ⁄ 4 − 1。
 * `min_period` 和 `max_period`: 从 `min_period` 到 `max_period` 的几何序列中的 D ⁄ 4 周期。

代码来自
DINOv3。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md)
使用 `repeat` 而不是 `tile`，因为 `tile` 不导出到 ONNX。

> **示例**
> ```pycon
>>> rope = RopePositionEmbedding(64, num_heads=4)
>>> [round(p, 2) for p in rope.periods.tolist()]
[1.0, 3.16, 10.0, 31.62]
>>> sin, cos = rope(H=2, W=3)
>>> sin.shape, cos.shape
(torch.Size([6, 16]), torch.Size([6, 16]))
```

周期的第二种设置：

```pycon
>>> rope = RopePositionEmbedding(
...     64, num_heads=4, base=None, min_period=0.5, max_period=10.0
... )
>>> [round(p, 2) for p in rope.periods.tolist()]
[0.5, 1.36, 3.68, 10.0]
```

#### 方法

##### init

```python
def __init__(embed_dim: int, *, num_heads: int, base: float | None = 100.0, min_period: float | None = None, max_period: float |
None = None, normalize_coords: Literal['min', 'max', 'separate'] = 'separate', shift_coords: float | None = None, jitter_coords:
float | None = None, rescale_coords: float | None = None, dtype: torch.dtype | None = None, device: torch.device | None = None):
```

存储设置并计算周期。

提供 `base`，或 `base=None` 并同时提供 `min_period` 和 `max_period`。当设置 `base` 时，构造函数会忽略单个 `min_period` 或 `max_period`。

参数

 * `embed_dim` (`int`): 变换器的嵌入维度。它必须是 `4 * num_heads` 的倍数。
 * `num_heads` (`int`): 注意力头的数量。
 * `base` (`float | None`): 周期的基数。`None` 选择 `min_period` 和 `max_period` 设置。
 * `min_period` (`float | None`): 最小周期。模块仅在 `base` 为 `None` 时使用它。
 * `max_period` (`float | None`): 最大周期。模块仅在 `base` 为 `None` 时使用它。
 * `normalize_coords` (`Literal['min', 'max', 'separate']`): 补丁坐标的除数。`"separate"` 将行除以 `H`，列除以 `W`。`"max"` 将两者都除以 `max(H, W)`，`"min"` 将两者都除以 `min(H, W)`。
 * `shift_coords` (`float | None`): 在训练模式下，[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md) 会为每个轴添加一个随机偏移。每个轴都会获得自己的偏移，在 `[-shift_coords, shift_coords]` 中均匀分布。`None` 不添加偏移。
 * `jitter_coords` (`float | None`): 在训练模式下，[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md) 会将每个轴乘以其自身的随机因子。该因子在 `[1 / jitter_coords, jitter_coords]` 中呈对数均匀分布。`None` 不应用抖动。
 * `rescale_coords` (`float | None`): 在训练模式下，[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md) 会将两个轴乘以一个随机因子。该因子在 `[1 / rescale_coords, rescale_coords]` 中呈对数均匀分布。`None` 不应用重新缩放。
 * `dtype` (`torch.dtype | None`): 周期和坐标的数据类型。`None` 选择默认数据类型。
 * `device` (`torch.device | None`): 周期缓冲区的设备。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/backbones/dinov3/rope_position_encoding.md) 在该缓冲区的设备上计算。

引发

 * `AssertionError`: 当 `embed_dim` 不是 `4 * num_heads` 的倍数时。
 * `ValueError`: 当 `base` 为 `None` 且其中一个周期为 `None`，或者当 `base` 和两个周期都设置时。

##### forward

```python
def forward(*, H: int, W: int) -> tuple[Tensor, Tensor]:
```

计算 `H x W` 网格的正弦和余弦表。

补丁遵循行主序。对于每个补丁，该方法从行坐标计算 D ⁄ 4 个角度，然后从列坐标计算 D ⁄ 4 个角度。它附加这些 D ⁄ 2 个角度的副本，这给出了 D 个角度。在训练模式下，该方法首先根据构造函数参数启用，对坐标进行平移、抖动和重新缩放。

参数

 * `H` (`int`): 补丁行数。
 * `W` (`int`): 补丁列数。

返回

 * `tuple[Tensor, Tensor]`: 角度的正弦和余弦，每个形状为 `[H * W, D]`，其中 `D` 是头部维度。

引发

 * `ValueError`: 当 `normalize_coords` 不是 `"min"`、`"max"` 或 `"separate"` 时。

#### 属性

##### periods

D ⁄ 4 周期，在持久缓冲区中。
