# 掩码生成

掩码生成是指为图像生成具有语义意义的掩码的任务。该任务与[图像分割](semantic_segmentation)非常相似，但两者之间存在许多差异。图像分割模型在带标签的数据集上进行训练，其能力受限于训练期间所见的类别；给定一张图像，它们会返回一组掩码及对应的类别。

掩码生成模型在大量数据上进行训练，并以两种模式运行。

- Prompting 模式：在此模式下，模型接收一张图像和一个提示，其中提示可以是图像中物体内部的二维点位置（XY 坐标），也可以是包围物体的边界框。在提示模式下，模型仅返回覆盖该物体的掩码
提示词所指出
- Segment Everything 模式：在 Segment Everything 中，给定一张图像，模型会生成图像中的所有掩码。为此，会生成一个点网格并叠加到图像上以进行推理。
- 视频推理：模型接受一个视频以及视频帧中的一个点或框提示，并会在整个视频中对其进行跟踪。有关如何进行视频推理的更多信息，请参阅 [SAM 2 文档](../model_doc/sam2)。

掩码生成任务由 [Segment Anything Model (SAM)](../model_doc/sam) 和 [Segment Anything Model 2 (SAM2)](../model_doc/sam2) 提供支持，而视频推理则由 [Segment Anything Model 2 (SAM2)](../model_doc/sam2) 提供支持。SAM 是一个功能强大的模型，由基于 Vision Transformer 的图像编码器、提示编码器和双向 Transformer 掩码解码器组成。图像和提示会被编码，解码器接收这些嵌入并生成有效的掩码。与此同时，SAM 2 通过添加内存模块来跟踪掩码，从而对 SAM 进行了扩展。

     

SAM 凭借其庞大的数据覆盖范围，成为分割任务中强大的基础模型。它在 [SA-1B](https://ai.meta.com/datasets/segment-anything/) 数据集上进行了训练，该数据集包含 100 万张图像和 11 亿个掩码。

在本指南中，您将学习如何：

- 在批量处理下，以分割所有模式进行推理，
- 以点提示模式进行推理，
- 以框提示模式进行推理。

首先，让我们安装 `transformers`：

```bash
pip install -q transformers
```

## 掩码生成流水线

推理掩码生成模型最简单的方法是使用 `mask-generation` 流水线。

```python
>>> from transformers import pipeline

>>> checkpoint = "facebook/sam2-hiera-base-plus"
>>> mask_generator = pipeline(model=checkpoint, task="mask-generation")
```

让我们看看这张图片。

```python
from PIL import Image
import requests

img_url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"
image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
```

     

让我们对一切进行分割。`points-per-batch` 允许在“分割一切”模式下对点进行并行推理。这可以加快推理速度，但会消耗更多内存。此外，SAM 仅支持对点进行批处理，而不支持对图像进行批处理。`pred_iou_thresh` 是 IoU 置信度阈值，只有高于该阈值的掩码才会被返回。

```python
masks = mask_generator(image, points_per_batch=128, pred_iou_thresh=0.88)
```

`masks` 看起来如下：

```bash
{'masks': [tensor([[False, False, False,  ...,  True,  True,  True],
          [False, False, False,  ...,  True,  True,  True],
          [False, False, False,  ...,  True,  True,  True],
          ...,
          [False, False, False,  ..., False, False, False], .. 
 'scores': tensor([0.9874, 0.9793, 0.9780, 0.9776, ... 0.9016])}
```

我们可以这样可视化它们：

```python
import matplotlib.pyplot as plt

plt.imshow(image, cmap='gray')

for i, mask in enumerate(masks["masks"]):
    plt.imshow(mask, cmap='viridis', alpha=0.1, vmin=0, vmax=1)

plt.axis('off')
plt.show()
```

下方是原始灰度图像，上面叠加了彩色映射图。非常令人印象深刻。

     

## 模型推理

### 点提示

你也可以在不使用 pipeline 的情况下使用模型。为此，请初始化模型和处理器。

```python
from transformers import SamModel, SamProcessor
from accelerate import Accelerator
import torch
device = Accelerator().device
model = SamModel.from_pretrained("facebook/sam-vit-base").to(device)
processor = SamProcessor.from_pretrained("facebook/sam-vit-base")
```

要进行点提示，请将输入点传递给处理器，然后获取处理器的输出并将其传递给模型进行推理。要对模型输出进行后处理，请传递输出以及取自处理器初始输出的`original_sizes`。我们需要传递这些值，因为处理器会调整图像大小，而输出需要进行外推。

```python
input_points = [[[2592, 1728]]] # point location of the bee

inputs = processor(image, input_points=input_points, return_tensors="pt").to(device)
with torch.no_grad():
    outputs = model(**inputs)
masks = processor.image_processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"].cpu())
```

我们可以在 `masks` 输出中可视化这三个掩码。

```python
import matplotlib.pyplot as plt
import numpy as np

fig, axes = plt.subplots(1, 4, figsize=(15, 5))

axes[0].imshow(image)
axes[0].set_title('Original Image')
mask_list = [masks[0][0][0].numpy(), masks[0][0][1].numpy(), masks[0][0][2].numpy()]

for i, mask in enumerate(mask_list, start=1):
    overlayed_image = np.array(image).copy()

    overlayed_image[:,:,0] = np.where(mask == 1, 255, overlayed_image[:,:,0])
    overlayed_image[:,:,1] = np.where(mask == 1, 0, overlayed_image[:,:,1])
    overlayed_image[:,:,2] = np.where(mask == 1, 0, overlayed_image[:,:,2])
    
    axes[i].imshow(overlayed_image)
    axes[i].set_title(f'Mask {i}')
for ax in axes:
    ax.axis('off')

plt.show()
```

     

### Box Prompting

你也可以以与点提示类似的方式进行框提示。只需将输入框以 `[x_min, y_min, x_max, y_max]` 列表格式与图像一起传递给 `processor`。获取 processor 的输出并直接传递给模型，然后再次对输出进行后处理。

```python
# bounding box around the bee
box = [2350, 1600, 2850, 2100]

inputs = processor(
        image,
        input_boxes=[[[box]]],
        return_tensors="pt"
    ).to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

mask = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(),
    inputs["original_sizes"].cpu(),
)[0][0][0].numpy()
```

您可以可视化蜜蜂周围的边界框，如下所示。

```python
import matplotlib.patches as patches

fig, ax = plt.subplots()
ax.imshow(image)

rectangle = patches.Rectangle((2350, 1600), 500, 500, linewidth=2, edgecolor='r', facecolor='none')
ax.add_patch(rectangle)
ax.axis("off")
plt.show()
```

     

您可以在下方查看推理输出。

```python
fig, ax = plt.subplots()
ax.imshow(image)
ax.imshow(mask, cmap='viridis', alpha=0.4)

ax.axis("off")
plt.show()
```

     

## 用于掩码生成的微调

我们将使用 MicroMat 数据集的一小部分对 SAM2.1 进行微调，以实现图像抠图。我们需要安装 [monai](https://github.com/Project-MONAI/MONAI) 库以使用 DICE 损失，并安装 [trackio](https://huggingface.co/docs/trackio/index) 用于在训练过程中记录掩码。

```bash
pip install -q datasets monai trackio
``` 
现在我们可以加载数据集并查看它。

```python
from datasets import load_dataset

dataset = load_dataset("merve/MicroMat-mini", split="train")
dataset
# Dataset({
#    features: ['image', 'mask', 'prompt', 'image_id', 'object_id', 'sample_idx', 'granularity', 
# 'image_path', 'mask_path', 'prompt_path'],  num_rows: 94
#})
```

我们需要图像、掩码和提示词列。我们将数据拆分为训练集和测试集。

```python
dataset = dataset.train_test_split(test_size=0.1)
train_ds = dataset["train"]
val_ds = dataset["test"]
```

让我们来看一个示例。

```python
train_ds[0]
```

```json
 {'image': <PIL.PngImagePlugin.PngImageFile image mode=RGB size=2040x1356>,
 'mask': <PIL.PngImagePlugin.PngImageFile image mode=L size=2040x1356>,
 'prompt': '{"point": [[137, 1165, 1], [77, 1273, 0], [58, 1351, 0]], "bbox": [0, 701, 251, 1356]}',
 'image_id': '0034',
 'object_id': '34',
 'sample_idx': 1,
 'granularity': 'fine',
 'image_path': '/content/MicroMat-mini/img/0034.png',
 'mask_path': '/content/MicroMat-mini/mask/0034_34.png',
 'prompt_path': '/content/MicroMat-mini/prompt/0034_34.json'}
```

Prompt 是字典的字符串，因此您可以按以下所示获取边界框。

```python
import json

json.loads(train_ds["prompt"][0])["bbox"]
# [0, 701, 251, 1356]
```

可视化一个示例图像、提示词和掩码。

```python
import matplotlib.pyplot as plt
import numpy as np

def show_mask(mask, ax):
    color = np.array([0.12, 0.56, 1.0, 0.6])
    mask = np.array(mask)
    h, w = mask.shape
    mask_image = mask.reshape(h, w, 1) * color.reshape(1, 1, 4)
    ax.imshow(mask_image)
    x0, y0, x1, y1 = eval(train_ds["prompt"][0])["bbox"]
    ax.add_patch(
        plt.Rectangle((x0, y0), x1 - x0, y1 - y0,
                      fill=False, edgecolor="lime", linewidth=2))

example = train_ds[0]
image = np.array(example["image"])
ground_truth_mask = np.array(example["mask"])

fig, ax = plt.subplots()
ax.imshow(image)
show_mask(ground_truth_mask, ax)
ax.set_title("Ground truth mask")
ax.set_axis_off()

plt.show() 
```

现在我们可以定义用于加载数据的 dataset。SAMDataset 封装了我们的 dataset，并按照 SAM processor 的期望格式对每个样本进行格式化。因此，你得到的不再是原始图像和掩码，而是经过处理的图像、边界框以及可直接用于训练的 ground-truth 掩码。

默认情况下，processor 会对图像进行缩放，因此除了返回图像和掩码外，还会返回原始尺寸。此外，由于掩码的取值范围为 [0, 255]，我们还需要对其进行二值化处理。

```python
from torch.utils.data import Dataset
import torch

class SAMDataset(Dataset):
  def __init__(self, dataset, processor):
    self.dataset = dataset
    self.processor = processor

  def __len__(self):
    return len(self.dataset)

  def __getitem__(self, idx):
    item = self.dataset[idx]
    image = item["image"]
    prompt = eval(item["prompt"])["bbox"]
    inputs = self.processor(image, input_boxes=[[prompt]], return_tensors="pt")
    inputs["ground_truth_mask"] = (np.array(item["mask"]) > 0).astype(np.float32)
    inputs["original_image_size"] = torch.tensor(image.size[::-1])

    return inputs
```

我们可以使用它来初始化处理器和数据集。

```python
from transformers import Sam2Processor

processor = Sam2Processor.from_pretrained("facebook/sam2.1-hiera-small")
train_dataset = SAMDataset(dataset=train_ds, processor=processor)
``` 

我们需要定义一个数据整理器（data collator），用于将不同尺寸的真实值掩码转换为形状统一的批量重塑掩码。我们使用最近邻插值进行重塑。同时，我们还会为批次中的其余元素创建批量张量。如果你的掩码尺寸都相同，可以跳过此步骤。

```python
import torch.nn.functional as F

def collate_fn(batch, target_hw=(256, 256)):

    pixel_values = torch.cat([item["pixel_values"] for item in batch], dim=0)
    original_sizes = torch.stack([item["original_sizes"] for item in batch])
    input_boxes = torch.cat([item["input_boxes"] for item in batch], dim=0)
    ground_truth_masks = torch.cat([
        F.interpolate(
            torch.as_tensor(x["ground_truth_mask"]).unsqueeze(0).unsqueeze(0).float(),
            size=(256, 256),
            mode="nearest"
        )
        for x in batch
    ], dim=0).long()

    return {
        "pixel_values": pixel_values,
        "original_sizes": original_sizes,
        "input_boxes": input_boxes,
        "ground_truth_mask": ground_truth_masks,
        "original_image_size": torch.stack([item["original_image_size"] for item in batch]),
    }

from torch.utils.data import DataLoader
train_dataloader = DataLoader(
    train_dataset,
    batch_size=4,
    shuffle=True,
    collate_fn=collate_fn,
)
```

让我们来看看数据加载器返回了什么。

```python
batch = next(iter(train_dataloader))
for k,v in batch.items():
  print(k,v.shape)

# pixel_values torch.Size([4, 3, 1024, 1024])
# original_sizes torch.Size([4, 1, 2])
# input_boxes torch.Size([4, 1, 4])
# ground_truth_mask torch.Size([4, 1, 256, 256])
#original_image_size torch.Size([4, 2])
```

接下来，我们将加载模型并冻结视觉编码器和提示编码器，仅训练掩码解码器。

```python
from transformers import Sam2Model

model = Sam2Model.from_pretrained("facebook/sam2.1-hiera-small")

for name, param in model.named_parameters():
  if name.startswith("vision_encoder") or name.startswith("prompt_encoder"):
    param.requires_grad_(False)
``` 

我们现在可以定义优化器和损失函数了。
```python 
from torch.optim import Adam
import monai

optimizer = Adam(model.mask_decoder.parameters(), lr=1e-5, weight_decay=0)
seg_loss = monai.losses.DiceCELoss(sigmoid=True, squared_pred=True, reduction='mean')
```

让我们看看模型在训练前的表现。

```python
import matplotlib.pyplot as plt

item = val_ds[1]
img = item["image"]
bbox = json.loads(item["prompt"])["bbox"]
inputs = processor(images=img, input_boxes=[[bbox]], return_tensors="pt").to(model.device)

with torch.no_grad():
  outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
preds = masks.squeeze(0)
mask = (preds[0] > 0).cpu().numpy()

overlay = np.asarray(img, dtype=np.uint8).copy()
overlay[mask] = 0.55 * overlay[mask] + 0.45 * np.array([0, 255, 0], dtype=np.float32)

plt.imshow(overlay)
plt.axis("off")
plt.show()
```

![SAM2 result after training](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/sam2_before_training.png)

我们需要将预测结果记录到 trackio，以便在训练过程中监控模型的改进情况。

```python
from PIL import Image
import trackio
import json

@torch.no_grad()
def predict_fn(img, bbox):

  inputs = processor(images=img, input_boxes=[[bbox]], return_tensors="pt").to(model.device)

  with torch.no_grad():
      outputs = model(**inputs)

  masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
  return masks

def log_eval_masks_trackio(dataset, indices, step, predict_fn,  project=None, sample_cap=8):
    logs = {"eval/step": int(step)}
    for idx in indices[:sample_cap]:
        item = dataset[idx] 
        img = item["image"]
        bbox = json.loads(item["prompt"])["bbox"]
        preds = predict_fn(img, bbox)
        preds = preds.squeeze(0)
        mask = (preds[0] > 0).cpu().numpy()  

        overlay = np.asarray(img, dtype=np.uint8).copy()
        overlay[mask] = 0.55 * overlay[mask] + 0.45 * np.array([0, 255, 0], dtype=np.float32)
        logs[f"{idx}/overlay"] = trackio.Image(overlay, caption="overlay")
        
    trackio.log(logs)
```

现在我们可以编写训练循环并开始训练了！

注意我们如何使用 trackio 记录损失和评估掩码。

```python
from tqdm import tqdm
from statistics import mean
import trackio
import torch

num_epochs = 30

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"
model.to(device)

model.train()
trackio.init(project="mask-eval")
for epoch in range(num_epochs):
    epoch_losses = []
    for batch in tqdm(train_dataloader):
      outputs = model(pixel_values=batch["pixel_values"].to(device),
                      input_boxes=batch["input_boxes"].to(device),
                      multimask_output=False)

      predicted_masks = outputs.pred_masks.squeeze(1)
      ground_truth_masks = batch["ground_truth_mask"].float().to(device)
      loss = seg_loss(predicted_masks, ground_truth_masks)

      optimizer.zero_grad()
      loss.backward()

      optimizer.step()
      epoch_losses.append(loss.item())
      
    log_eval_masks_trackio(dataset=val_ds, indices=[0, 3, 6, 9], step=epoch, predict_fn=predict_fn, project="mask-eval")
    print(f'Epoch: {epoch}')
    print(f'Mean loss: {mean(epoch_losses)}')
    trackio.log({"loss": mean(epoch_losses)})

trackio.finish()
```

让我们对训练好的模型进行测试。

```python
import matplotlib.pyplot as plt

item = val_ds[1]
img = item["image"]
bbox = json.loads(item["prompt"])["bbox"]

inputs = processor(images=img, input_boxes=[[bbox]], return_tensors="pt").to(model.device)

with torch.no_grad():
  outputs = model(**inputs)

preds = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]

preds = preds.squeeze(0)
mask = (preds[0] > 0).cpu().numpy()

overlay = np.asarray(img, dtype=np.uint8).copy()
overlay[mask] = 0.55 * overlay[mask] + 0.45 * np.array([0, 255, 0], dtype=np.float32)

plt.imshow(overlay)
plt.axis("off")
plt.show()
```

仅在小数据集上训练 20 个 epoch，就取得了显著的提升！

![SAM2 result after training](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/sam2_after_training.png)

