# gradcam_visualizer

Python API: `luxonis_train.callbacks.gradcam_visualizer`

记录验证图像的 Grad-CAM 热力图。

热力图显示了对一个类别的分数有贡献的图像区域。

## 类

### GradCamCallback

记录验证图像的 Grad-CAM 热力图的回调。

该回调是实验性的。它在每个验证周期的前 `log_n_batches` 批次上运行 `pytorch_grad_cam` 的 `HiResCAM`。它将每个热力图叠加到其图像上，并使用模型的跟踪器记录结果。它在验证之外不记录任何内容。

Grad-CAM 需要梯度。fit 的验证循环在没有推理模式的情况下运行，因此回调在那里工作。`trainer.validate` 默认在推理模式下运行。在那里，Grad-CAM 的反向传播会引发 `RuntimeError`。

回调在 `CALLBACKS` 注册表中，因此配置可以添加它：

```yaml
trainer:
  callbacks:
    - name: GradCamCallback
      params:
        target_layer: 10
        task: segmentation
```

#### 方法

##### init

```python
def __init__(target_layer: int, class_idx: int = 0, log_n_batches: int = 1, task: str = 'classification'):
```

初始化回调。

参数

 * `target_layer` (`int`): Grad-CAM 读取的层的索引，按照
   [PLModuleWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
   的 `named_modules()` 的顺序。索引 `0` 是包装器，索引 `1` 是被包装的模型。回调选择切片 `[target_layer : target_layer + 1]` 中的层。当切片为空时，例如 `-1`
   或超出范围的索引，Grad-CAM 会引发 `ValueError`。
 * `class_idx` (`int`): 热力图解释的类别的索引。
 * `log_n_batches` (`int`): 每个验证周期要记录的批次数量，从第一个批次开始。
 * `task` (`str`): 要解释的输出类型。可以是 `"segmentation"`、`"detection"`、`"classification"` 或 `"keypoints"`。请参阅
   [PLModuleWrapper.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)。

##### on_validation_batch_end

```python
def on_validation_batch_end(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule, outputs: STEP_OUTPUT, batch: tuple[dict[str, Tensor], Packet[Tensor]], batch_idx: int):
```

记录前 `log_n_batches` 批次的热力图。

Lightning 在每个验证批次之后调用此钩子。当 `batch_idx` 小于 `log_n_batches` 时，钩子获取批次的输入。从输入字典中，它获取 `pl_module.image_source` 条目。然后它调用
[GradCamCallback.visualize_gradients](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)。对于后续批次，钩子不执行任何操作。

参数

 * `trainer` (`pl.Trainer`): 训练器。它提供记录图像的步骤。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。它提供 `image_source`、配置和跟踪器。
 * `outputs` (`STEP_OUTPUT`): 验证步骤的输出。未使用。
 * `batch` (`tuple[dict[str, Tensor], Packet[Tensor]]`): 批次的输入和标签。
 * `batch_idx` (`int`): 批次在验证周期中的索引。

##### setup

```python
def setup(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule, stage: str):
```

为 Grad-CAM 包装模型。

Lightning 在每个阶段开始时调用此钩子。钩子为
[visualize_gradients](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
创建一个新的 `pl_module` 和 `task` 的
[PLModuleWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)。

参数

 * `trainer` (`pl.Trainer`): 训练器。未使用。
 * `pl_module` (`lxt.LuxonisLightningModule`): 要包装的模型。
 * `stage` (`str`): 开始的阶段。未使用。

##### visualize_gradients

```python
def visualize_gradients(trainer: pl.Trainer, pl_module: lxt.LuxonisLightningModule, images: Tensor, batch_idx: int):
```

计算批次的 Grad-CAM 热力图并记录它们。

该方法在
[PLModuleWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
的 `named_modules()` 中索引为 `target_layer` 的层上创建一个 `HiResCAM`。`HiResCAM` 将包装器和模型设置为评估模式。该方法保留
`HiResCAM`，因此其钩子保留在该层上，直到后续调用替换它。在此之前，钩子会保留每次前向传播的层输出的 CPU 副本，以及每次反向传播的梯度的 CPU 副本。

每张图像的 Grad-CAM 目标取决于 `task`：

 * `"segmentation"`: 该方法首先在图像上运行模型并对类别应用 softmax。图像的掩码包含 `class_idx` 具有最高概率的像素。目标是该掩码上 `class_idx` 分数图的总和。
 * 任何其他任务: 目标是
   [PLModuleWrapper.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
   中分数的 `class_idx` 条目。

该方法在启用梯度的情况下计算热力图。Grad-CAM 清除模型的梯度并运行反向传播，因此模型的参数保留新的 `grad` 值。该方法使用 `pl_module.cfg` 的 `trainer.preprocessing.normalize`
对图像进行反归一化。每个热力图以半透明的 JET 颜色图叠加在其图像上。`pl_module` 的跟踪器在 `trainer.global_step` 处将每个结果记录为 `gradcam/gradcam_<batch_idx>_<i>`。`<i>`
是图像在批次中的索引。

参数

 * `trainer` (`pl.Trainer`): 训练器。它提供记录图像的步骤。
 * `pl_module` (`lxt.LuxonisLightningModule`): 模型。它提供用于反归一化的配置和跟踪器。
 * `images` (`Tensor`): 归一化图像，形状为 `[B, C, H, W]`。
 * `batch_idx` (`int`): 批次的索引。它是图像名称的一部分。

### PLModuleWrapper

Lightning 模块，为 Grad-CAM 提供每个批次一个分数张量。

Grad-CAM
需要一个模型，该模型接受图像张量并返回分数张量。[LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
返回一个
[LuxonisOutput](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_output.md)，其中包含输出节点的包。包装器获取图像并从这些包中返回一个张量。[GradCamCallback](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
创建包装器。

#### 方法

##### init

```python
def __init__(pl_module: lxt.LuxonisLightningModule, task: str):
```

初始化包装器。

参数

 * `pl_module` (`lxt.LuxonisLightningModule`): 要包装的模型。
 * `task` (`str`): 选择
   [PLModuleWrapper.forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
   返回的输出。可以是 `"segmentation"`、`"detection"`、`"classification"` 或 `"keypoints"`。构造函数不检查该值。

##### forward

```python
def forward(inputs: Tensor, *args, **kwargs) -> Tensor:
```

在图像上运行模型并返回 `task` 的分数。

该方法调用
[LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)，其中
`{"image": inputs}` 和额外的参数。当模型有多个输出节点时，该方法会记录警告。它读取第一个输出节点的包。返回的张量取决于 `task`：

 * `"segmentation"`: `"segmentation"` 输出，未更改。
 * `"classification"`: `"classification"` 输出，未更改。
 * `"detection"` 和 `"keypoints"`: `"class_scores"` 输出，在维度 1 上求和。对于
   [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
   的分数，形状为 `[B, N, n_classes]`（`N` 个锚点），结果形状为 `[B, n_classes]`。

参数

 * `inputs` (`Tensor`): 图像，形状为 `[B, C, H, W]`。该方法将它们作为名为 `"image"` 的输入传递。该名称不遵循配置的 `loader.image_source`。
 * `*args`:
   [LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   的额外位置参数。
 * `**kwargs`:
   [LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
   的额外关键字参数。

返回

 * `Tensor`: `task` 的分数。

引发

 * `ValueError`: 当 `task` 不是四个支持值之一时。
