Transformers documentation

마스크 생성

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

마스크 생성

Mask generation은 이미지에서 의미론적으로 의미 있는 마스크를 생성하는 작업입니다. 이 작업은 image segmentation과 매우 유사하지만, 여러 차이점이 존재합니다. Image segmentation 모델은 라벨이 붙은 데이터셋으로 학습되며, 학습 중에 본 클래스로 제한됩니다. 즉, 이미지를 입력하면 마스크의 집합과 해당 클래스를 반환합니다.

Mask generation models은 대량의 데이터로 학습되며 두 가지 모드로 작동합니다.

  • Prompting 모드: 이 모드에서 모델은 이미지와 프롬프트를 입력으로 받습니다. 여기서 프롬프트는 이미지 내 대상 객체 안의 2D 점 위치(XY 좌표) 또는 대상 객체를 둘러싼 bounding box일 수 있습니다. Prompting 모드에서 모델은 프롬프트가 가리키는 대상 객체에 대한 mask만 반환합니다.
  • Segment Everything 모드: Segment everything에서는 이미지가 주어지면 모델이 이미지 내의 모든 마스크를 생성합니다. 이를 위해 추론을 위해 점 그리드가 생성되어 이미지에 겹쳐집니다.
  • Video Inference: 모델은 비디오와 비디오 프레임 내의 점 또는 박스 프롬프트를 입력으로 받아, 해당 대상이 비디오 전체에 걸쳐 추적되도록 합니다. 비디오 추론 수행 방법에 대한 자세한 내용은 SAM 2 문서를 참고하세요.

마스크 생성 작업은 Segment Anything Model (SAM)과 Segment Anything Model 2 (SAM2)에서 지원되며, 비디오 추론은 Segment Anything Model 2 (SAM2)에서 지원됩니다. SAM은 Vision Transformer 기반 이미지 인코더, 프롬프트 인코더, 양방향 트랜스포머 마스크 디코더로 구성된 강력한 모델입니다. 이미지와 프롬프트가 인코딩된 후, 디코더는 이러한 임베딩을 받아 유효한 마스크를 생성합니다. 한편, SAM 2는 마스크를 추적하기 위해 메모리 모듈을 추가하여 SAM을 확장했습니다.

SAM Architecture

SAM은 대규모 데이터 커버리지를 갖추고 있어 분할을 위한 강력한 파운데이션 모델로 기능합니다. 100만 개의 이미지와 11억 개의 마스크로 구성된 SA-1B 데이터셋으로 학습되었습니다.

이 가이드에서는 다음 내용을 배웁니다:

  • 세그먼트 에브리싱 모드에서 배치 처리를 사용하여 추론을 수행합니다.
  • 포인트 프롬프팅 모드에서 추론을 수행합니다.
  • 박스 프롬프팅 모드에서 추론을 수행합니다.

먼저 transformers를 설치해 보겠습니다:

pip install -q transformers

마스크 생성 파이프라인

마스크 생성 모델을 추론하는 가장 쉬운 방법은 mask-generation 파이프라인을 사용하는 것입니다.

>>> from transformers import pipeline

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

이미지를 확인해 보겠습니다.

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")
Example Image

모든 것을 세그먼트해 보겠습니다. points-per-batch는 segment everything 모드에서 포인트의 병렬 추론을 활성화합니다. 이를 통해 추론 속도가 빨라지지만, 메모리 사용량이 증가합니다. 또한 SAM은 이미지보다는 포인트에 대해서만 배치 처리를 지원합니다. pred_iou_thresh는 IoU 신뢰도 임계값으로, 해당 임계값을 초과하는 마스크만 반환됩니다.

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

masks는 다음과 같은 형태입니다:

{'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])}

다음과 같이 시각화할 수 있습니다:

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()

아래는 흑백 원본 이미지 위에 컬러 맵이 겹쳐진 모습입니다. 매우 인상적입니다.

Visualized

모델 추론

포인트 프롬프팅

pipeline 없이 모델을 사용할 수도 있습니다. 이를 위해 모델과 프로세서를 초기화합니다.

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를 프로세서의 초기 출력에서 가져와 전달해야 합니다. 프로세서가 이미지를 리사이즈하기 때문에, 출력을 외삽해야 하므로 이 값들을 전달해야 합니다.

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 출력에서 세 개의 마스크를 시각화할 수 있습니다.

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()
Visualized

Box Prompting

점 프롬프팅과 유사한 방식으로 박스 프롬프팅도 수행할 수 있습니다. [x_min, y_min, x_max, y_max] 형식의 입력 박스를 이미지와 함께 processor에 전달하기만 하면 됩니다. 프로세서의 출력을 받아 모델에 직접 전달한 뒤, 출력을 다시 후처리합니다.

# 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()

아래와 같이 벌 주위의 bounding box를 시각화할 수 있습니다.

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()
Visualized Bbox

아래에서 추론 출력을 확인할 수 있습니다.

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

ax.axis("off")
plt.show()
Visualized Inference

마스크 생성을 위한 Fine-tuning

MicroMat 데이터셋의 일부로 이미지 매팅을 위해 SAM2.1을 fine-tune합니다. DICE loss를 사용하려면 monai 라이브러리를 설치해야 하며, 학습 중 마스크를 기록하려면 trackio가 필요합니다.

pip install -q datasets monai trackio
``` 
We can now load our dataset and take a look.

```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
#})

image, mask, prompt 컬럼이 필요합니다. 학습용과 테스트용으로 분할합니다.

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

샘플을 살펴보겠습니다.

train_ds[0]
 {'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'}

Prompts는 사전의 문자열이므로, 아래에 표시된 바와 같이 bounding box를 가져올 수 있습니다.

import json

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

예시 이미지, 프롬프트 및 마스크를 시각화합니다.

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() 

이제 데이터를 로드하기 위한 데이터셋을 정의할 수 있습니다. SAMDataset는 데이터셋을 래핑하여 각 샘플을 SAM 프로세서가 기대하는 형식으로 포맷팅합니다. 따라서 원본 이미지와 마스크 대신, 학습에 바로 사용할 수 있는 처리된 이미지, 바운딩 박스, ground-truth 마스크를 얻을 수 있습니다.

기본적으로 processor는 이미지를 리사이즈하므로, 이미지와 마스크 외에도 원래 크기를 반환합니다. 또한 마스크의 값이 [0, 255] 범위를 가지므로 이진화(binarize) 처리도 필요합니다.

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

이를 사용하여 프로세서와 데이터셋을 초기화할 수 있습니다.

from transformers import Sam2Processor

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

We need to define a data collator that will turn varying size of ground truth masks to batches of reshaped masks in same shape. We reshape them using nearest neighbor interpolation. We also make batched tensors for rest of the elements in the batch. If your masks are all of same size, feel free to skip this step.

```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,
)

데이터 로더가 생성하는 내용을 살펴봅시다.

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])

이제 모델을 로드하고, mask decoder만 학습하도록 vision과 prompt encoder를 동결합니다.

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)
``` 

We can now define the optimizer and the loss function.
```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')

학습 전에 모델의 성능을 확인해 보겠습니다.

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

모델 개선 사항을 학습 중간에 모니터링할 수 있도록 trackio에 예측 결과를 기록해야 합니다.

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)

이제 학습 루프를 작성하고 학습을 시작할 수 있습니다!

로 loss와 evaluation masks를 로깅하는 방식을 주목해 보세요.

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()

학습된 모델을 테스트해 보겠습니다.

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

Update on GitHub