# perlin

Python API: `luxonis_train.loaders.perlin`

Perlin 噪声掩码，以及将纹理转换为异常的混合。

[LuxonisLoaderPerlinNoise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_perlin_loader_torch.md)
调用
[apply_anomaly_to_img](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)，它使用
[generate_perlin_noise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
绘制其掩码。其他函数是噪声的步骤。

## 函数

### apply_anomaly_to_img

```python
def apply_anomaly_to_img(img: Tensor, anomaly_img: Tensor, beta: float | None = None) -> tuple[Tensor, Tensor]:
```

在随机 Perlin 噪声掩码内将纹理混合到图像中。

该函数使用
[generate_perlin_noise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
绘制掩码 M。然后它混合图像 I 和纹理 A：

I’ = (1 − M)⊙I + (1 − β)M⊙A + β**M⊙I

图像在掩码外部不发生变化。在掩码内部，`beta` 是图像的权重，`1 - beta` 是纹理的权重。`H` 和 `W` 必须是 `32` 的倍数，请参阅
[generate_perlin_noise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)。

> **示例**
> 当 `beta=0.0` 时，纹理在掩码内部替换图像：

```pycon
>>> import torch
>>> _ = torch.manual_seed(0)
>>> img = torch.zeros(3, 64, 64)
>>> texture = torch.ones(3, 64, 64)
>>> augmented, mask = apply_anomaly_to_img(img, texture, beta=0.0)
>>> augmented.shape, mask.shape
(torch.Size([3, 64, 64]), torch.Size([64, 64]))
>>> torch.equal(augmented, mask.expand(3, -1, -1))
True
```

参数

 * `img` (`Tensor`): 形状为 `[C, H, W]` 的干净图像。
 * `anomaly_img` (`Tensor`): 形状为 `[C, H, W]` 的纹理图像。
 * `beta` (`float | None`): 掩码内部图像的权重。`None` 从 `[0, 0.8)` 中抽取一个值。

返回

 * `tuple[Tensor, Tensor]`: 带有异常的图像，形状为 `[C, H, W]`，以及形状为 `[H, W]` 的掩码。掩码在异常内部为 `1.0`，在异常外部为 `0.0`。

### compute_gradients

```python
def compute_gradients(res: tuple[int, int]) -> Tensor:
```

在晶格的每个点绘制一个随机单位梯度。

角度在 [0, 2π) 中均匀分布。它们使用全局 `torch` 随机状态。

> **示例**
> ```pycon
>>> import torch
>>> gradients = compute_gradients((2, 3))
>>> gradients.shape
torch.Size([3, 4, 2])
>>> torch.allclose(gradients.norm(dim=-1), torch.ones(3, 4))
True
```

参数

 * `res` (`tuple[int, int]`): 沿每个维度晶格单元的数量。

返回

 * `Tensor`: 形状为 `[res[0] + 1, res[1] + 1, 2]` 的梯度 `(cos, sin)`。

### dot

```python
def dot(grad: Tensor, shift: tuple[int, int], grid: Tensor, shape: tuple[int, int]) -> Tensor:
```

计算每个像素偏移量与其角梯度的点积。

从单元格角到像素的偏移量是 `grid + shift`。该函数在乘积之前将 `grid` 和 `grad` 裁剪为 `shape`。

> **示例**
> 一个像素在其单元格中的位置为 `(0.25, 0.75)`，角为 `(1, 0)`，梯度为 `(1, 0)`：

```pycon
>>> import torch
>>> grad = torch.tensor([[[1.0, 0.0]]])
>>> grid = torch.tensor([[[0.25, 0.75]]])
>>> dot(grad, (-1, 0), grid, (1, 1)).tolist()
[[-0.75]]
```

参数

 * `grad` (`Tensor`): 每个像素的角梯度，形状为 `[H', W', 2]`，其中 `H' >= H` 且 `W' >= W`。
 * `shift` (`tuple[int, int]`): 角在单元格中的负位置：`(0, 0)`、`(-1, 0)`、`(0, -1)` 或 `(-1, -1)`。
 * `grid` (`Tensor`): 每个像素在其单元格中的位置，在 `[0, 1)` 中，形状为 `[H'', W'', 2]`，其中 `H'' >= H` 且 `W'' >= W`。
 * `shape` (`tuple[int, int]`): 输出形状 `(H, W)`。

返回

 * `Tensor`: 形状为 `[H, W]` 的点积。

### fade_function

```python
def fade_function(t: Tensor) -> Tensor:
```

应用 Perlin 噪声的五次衰减曲线。

f(t) = 6t5 − 15t4 + 10t3

该曲线将 `0` 映射到 `0`，将 `1` 映射到 `1`。其一阶和二阶导数在两端均为零。因此，噪声的一阶和二阶导数在晶格单元边界处是连续的。

> **示例**
> ```pycon
>>> import torch
>>> fade_function(torch.tensor([0.0, 0.25, 0.5, 1.0])).tolist()
[0.0, 0.103515625, 0.5, 1.0]
```

参数

 * `t` (`Tensor`): 单元格内的位置，在 `[0, 1]` 中。

返回

 * `Tensor`: 衰减后的位置，形状与 `t` 相同。

### generate_perlin_noise

```python
def generate_perlin_noise(shape: tuple[int, int], min_perlin_scale: int = 0, perlin_scale: int = 6, threshold: float = 0.5) -> Tensor:
```

从阈值化的 Perlin 噪声生成随机二进制掩码。

该函数为每个维度绘制一个指数 `k`，在 `[min_perlin_scale, perlin_scale)` 中的整数上均匀分布。来自
[rand_perlin_2d](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
的噪声沿该维度具有 `2 ** k` 个单元格。噪声高于 `threshold` 的像素得到 `1.0`，其他像素得到 `0.0`。然后
[rotate_noise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
将掩码旋转一个随机角度。

`shape` 中的每个大小都必须是 `2 ** (perlin_scale - 1)` 的倍数，对于默认值，它是 `32`。否则，某些绘制会失败，请参阅
[rand_perlin_2d](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)。

> **示例**
> ```pycon
>>> import torch
>>> _ = torch.manual_seed(0)
>>> mask = generate_perlin_noise((64, 64))
>>> mask.shape, mask.dtype
(torch.Size([64, 64]), torch.float32)
>>> set(mask.unique().tolist()) <= {0.0, 1.0}
True
```

参数

 * `shape` (`tuple[int, int]`): 掩码形状 `(H, W)`。
 * `min_perlin_scale` (`int`): 最小指数。
 * `perlin_scale` (`int`): 指数的上限，不包括。较大的指数会产生较小的噪声斑点。不大于 `min_perlin_scale` 的值会使 `torch.randint` 引发 `RuntimeError`。
 * `threshold` (`float`): 像素必须超过的噪声值才能得到 `1.0`。噪声在 `[-1, 1]` 中，因此较高的阈值会产生较小的掩码区域。

返回

 * `Tensor`: 形状为 `[H, W]` 的 `torch.float32` 掩码，值为 `0.0` 和 `1.0`。

### lerp_torch

```python
def lerp_torch(x: Tensor, y: Tensor, w: Tensor) -> Tensor:
```

使用权重 `w` 从 `x` 到 `y` 进行线性插值。

lerp(x, y, w) = x + w(y − x)

TorchScript 编译该函数。

参数

 * `x` (`Tensor`): `w = 0` 时的值。
 * `y` (`Tensor`): `w = 1` 时的值。
 * `w` (`Tensor`): 权重。它们与 `x` 和 `y` 进行广播。

返回

 * `Tensor`: 插值后的值，形状与 `x`、`y` 和 `w` 广播后的形状相同。

### rand_perlin_2d

```python
def rand_perlin_2d(shape: tuple[int, int], res: tuple[int, int], fade: Callable[[Tensor], Tensor] = fade_function) -> Tensor:
```

生成具有随机梯度的 2D Perlin 噪声。

该函数将输出分成 `res[0]` 乘以 `res[1]` 个晶格单元。它使用 [compute_gradients](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md) 在每个晶格点绘制一个随机梯度。像素的值混合了其四个单元格角的点积，权重来自 `fade`。因子 √(2) 将值缩放到 `[-1, 1]`。噪声在每个晶格点处为 `0`。

`shape` 中的每个大小都必须是 `res` 中相同维度值的倍数。否则，张量操作会引发 `RuntimeError`。如果大小为 `1` 且单元格多于一个，则会得到一个空张量。

> **示例**
> ```pycon
>>> import torch
>>> _ = torch.manual_seed(0)
>>> noise = rand_perlin_2d((8, 8), (2, 2))
>>> noise.shape
torch.Size([8, 8])
>>> bool(noise.abs().max() <= 1)
True
>>> bool((noise[::4, ::4] == 0).all())
True
```

参数

 * `shape` (`tuple[int, int]`): 输出形状 `(H, W)`。
 * `res` (`tuple[int, int]`): 沿每个维度晶格单元的数量。更多的单元格会产生更小的噪声特征。
 * `fade` (`Callable[[Tensor], Tensor]`): 插值曲线。它获取每个像素在其单元格内的位置。

返回

 * `Tensor`: 形状为 `[H, W]` 的噪声，值在 `[-1, 1]` 中。

### rotate_noise

```python
def rotate_noise(noise: Tensor) -> Tensor:
```

将 2D 张量绕其中心旋转一个随机角度。

角度在 [0, 2π) 中均匀分布，并使用全局 `torch` 随机状态。中心是 `(H // 2, W // 2)`。每个输出像素取输入像素在旋转位置的值，坐标向下取整。输入外部的位置移动到最近的边界。TorchScript 编译该函数。

参数

 * `noise` (`Tensor`): 形状为 `[H, W]` 的张量。

返回

 * `Tensor`: 形状为 `[H, W]` 的旋转张量。它只包含 `noise` 中的值。

### tile_grads

```python
def tile_grads(slice1: tuple[int, int | None], slice2: tuple[int, int | None], gradients: Tensor, d: tuple[int, int]) -> Tensor:
```

在每个单元格的像素上重复梯度晶格的一个角。

该函数获取切片 `gradients[slice1[0]:slice1[1], slice2[0]:slice2[1]]`。然后它将每行重复 `d[0]` 次，每列重复 `d[1]`
次。[rand_perlin_2d](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
为四个单元格角中的每一个调用它一次。切片 `(0, -1)` 沿一个维度选择第一个角，`(1, None)` 选择第二个角。

> **示例**
> 2D 张量显示索引的模式：

```pycon
>>> import torch
>>> gradients = torch.arange(9).reshape(3, 3)
>>> tile_grads((0, -1), (1, None), gradients, (2, 1)).tolist()
[[1, 2], [1, 2], [4, 5], [4, 5]]
```

参数

 * `slice1` (`tuple[int, int | None]`): 沿维度 `0` 的切片的开始和停止。
 * `slice2` (`tuple[int, int | None]`): 沿维度 `1` 的切片的开始和停止。
 * `gradients` (`Tensor`):
   晶格梯度。[rand_perlin_2d](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
   给出形状 `[res[0] + 1, res[1] + 1, 2]`。
 * `d` (`tuple[int, int]`): 沿每个维度单元格中的像素数。

返回

 * `Tensor`: 重复的梯度。对于
   [rand_perlin_2d](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/perlin.md)
   的切片，形状为 `[res[0] * d[0], res[1] * d[1], 2]`。
