# embeddings_visualizer

Python API: `luxonis_train.attached_modules.visualizers.embeddings_visualizer`

使用 PCA 将一批嵌入投影到二维，并根据身份标签着色绘制它们。

## 类

### EmbeddingsVisualizer

将嵌入空间可视化为二维图。

左侧的 KDE 图和右侧的散点图显示了嵌入的 2D PCA。每种颜色代表一个身份标签。

 * `输入:`: * `prediction_canvas`, `target_canvas` (`Tensor`): [B, 3, H, W]
    * `predictions` (`Tensor`): [B, D] 嵌入
    * `target` (`Tensor`): [B] 身份标签
 * `输出:`: * `tuple[Tensor, Tensor]`: [1, 3, 512, 512] 2D PCA 的 KDE 和散点图

> **参考**
> * 来源：本项目。
 * 许可证：Apache-2.0（本项目）

> **注意**
> 使用 PCA 投影嵌入，过滤 z-score 异常值，并将 Seaborn 图渲染为张量。

> **示例**
> 附加到 `model.nodes` 中的 `GhostFaceNetHead`：

```yaml
- name: GhostFaceNetHead
  inputs: [GhostFaceNet]
  visualizers:
    - name: EmbeddingsVisualizer
```

 * `兼容:`: *
   使用者：[EmbeddingsModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/embeddings/v1/model.md)
    * 节点：[GhostFaceNetHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/ghostfacenet_head.md)

#### 方法

##### init

```python
def __init__(z_score_threshold: float = 3, **kwargs):
```

初始化可视化器并存储异常值阈值。

参数

 * `z_score_threshold` (`float`): 投影点的绝对 z-score
   限制。[forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
   仅当其两个坐标的绝对 z-score 都低于此限制时才保留该点。z-score 使用批次在每个轴上的均值和标准差。默认为 `3`。
 * `**kwargs`: 转发给
   [BaseVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
   的关键字参数，例如 `scale` 和 `node`。

##### forward

```python
def forward(prediction_canvas: Tensor, target_canvas: Tensor, predictions: Tensor, target: Tensor) -> tuple[Tensor, Tensor]:
```

将嵌入投影到二维并绘制它们。

该方法将 `NaN` 和无限值替换为 `0`。当 `predictions` 是 CPU 张量时，此替换会写入其中。然后它使用 `random_state=42` 拟合一个双分量 PCA。当第二个分量的解释方差低于 `1e-12`
时，嵌入实际上是一维的。该方法然后固定第一个投影坐标的符号。它计算它们与嵌入行和的点积，并在点积为负时翻转坐标。接下来，[_filter_outliers](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
丢弃在任一轴上其绝对 z-score 达到 `z_score_threshold` 的点。最后，它使用
[kde_plot](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
和
[scatter_plot](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)
渲染 KDE 图和散点图。该方法忽略两个画布。

以 `INFO` 级别记录丢弃的异常值数量。

参数

 * `prediction_canvas` (`Tensor`): 忽略。
 * `target_canvas` (`Tensor`): 忽略。
 * `predictions` (`Tensor`): 形状为 `[B, D]` 的嵌入。
 * `target` (`Tensor`): 每个嵌入的 `id` 元数据标签，形状为 `[B]`。该方法将其转换为 `int`。

返回

 * `tuple[Tensor, Tensor]`: KDE 图和散点图，每个都是形状为 `[1, 3, 512, 512]` 的 `uint8` 图像。

##### kde_plot

```python
def kde_plot(ax: plt.Axes, emb: np.ndarray, labels: np.ndarray):
```

在轴上为每个标签绘制一个填充的 KDE。

每个标签的颜色来自
[BaseVisualizer.colormap](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)。KDE
使用 `bw_adjust=1.5` 和 `alpha=0.9`。`warn_singular=False` 抑制了 Seaborn 对无法形成密度的标签点的警告。

参数

 * `ax` (`plt.Axes`): 绘制的轴。
 * `emb` (`np.ndarray`): 形状为 `[N, 2]` 的投影点。
 * `labels` (`np.ndarray`): 每个点的标签，形状为 `[N]`。

##### plot_to_tensor

```python
def plot_to_tensor(embeddings_2d: np.ndarray, ids_np: np.ndarray, plot_func: Callable[[plt.Axes, np.ndarray, np.ndarray], None]) -> Tensor:
```

将投影嵌入的图渲染为图像张量。

创建一个 `10 x 10` 英寸的图，并将两个轴限制在点的范围内。然后它在轴上调用 `plot_func`，隐藏轴，并使用
[figure_to_torch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
转换图。

> **示例**
> ```pycon
>>> import numpy as np
>>> def no_op(ax, points, labels):
...     pass
>>> EmbeddingsVisualizer.plot_to_tensor(
...     np.zeros((0, 2)), np.zeros(0, dtype=int), no_op
... ).shape
torch.Size([1, 3, 512, 512])
```

参数

 * `embeddings_2d` (`np.ndarray`): 形状为 `[N, 2]` 的投影点。可能为空；此时轴限制保持默认值。
 * `ids_np` (`np.ndarray`): 形状为 `[N]` 的标签。
 * `plot_func` (`Callable[[plt.Axes, np.ndarray, np.ndarray], None]`): 在接收到的轴上绘制，例如 [kde_plot](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md) 或 [scatter_plot](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/embeddings_visualizer.md)。

返回

 * `Tensor`: 形状为 `[1, 3, 512, 512]` 的 `uint8` 图像。

##### scatter_plot

```python
def scatter_plot(ax: plt.Axes, emb: np.ndarray, labels: np.ndarray):
```

在轴上绘制所有点，按标签着色。

使用 `s=300`、`alpha=0.9`，无图例。调色板将每个标签映射到 [BaseVisualizer.colormap](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md) 中的颜色。

参数

 * `ax` (`plt.Axes`): 绘制的轴。
 * `emb` (`np.ndarray`): 形状为 `[N, 2]` 的投影点。
 * `labels` (`np.ndarray`): 每个点的标签，形状为 `[N]`。

#### 属性

##### supported_tasks
