이 모델은 2025-08-14에 Hugging Face Transformers에 기여되었습니다.

SAM2 Video

개요

SAM2(Segment Anything Model 2)는 Nikhila Ravi, Valentin Gabeur, Yuan-Ting Hu, Ronghang Hu, Chaitanya Ryali, Tengyu Ma, Haitham Khedr, Roman Rädle, Chloe Rolland, Laura Gustafson, Eric Mintun, Junting Pan, Kalyan Vasudev Alwala, Nicolas Carion, Chao-Yuan Wu, Ross Girshick, Piotr Dollár, Christoph Feichtenhofer가 Segment Anything in Images and Videos에서 제안했습니다.

모델은 입력 이미지 또는 비디오와 입력 점 또는 바운딩 박스를 제공하면 관심 대상인 모든 객체의 분할 마스크를 예측하는 데 사용할 수 있습니다.

example image

해당 논문의 초록은 다음과 같습니다:

Segment Anything Model 2(SAM 2)를 소개합니다. SAM 2는 이미지와 비디오에서 프롬프트 기반 시각 분할을 해결하기 위한 파운데이션 모델입니다. 사용자 상호작용을 통해 모델과 데이터를 개선하는 데이터 엔진을 구축하여, 지금까지 수집된 최대 규모의 비디오 분할 데이터셋을 확보했습니다. 본 모델은 실시간 비디오 처리를 위한 스트리밍 메모리를 갖춘 단순한 트랜스포머 아키텍처입니다. 해당 데이터로 학습된 SAM 2는 다양한 작업에서 강력한 성능을 제공합니다. 비디오 분할에서는 기존 접근법보다 3배 적은 상호작용으로 더 높은 정확도를 달성했습니다. 이미지 분할에서는 Segment Anything Model(SAM)보다 정확도가 높고 6배 빠릅니다. 본 데이터, 모델 및 인사이트가 비디오 분할 및 관련 인식 작업의 중요한 이정표가 될 것이라고 믿습니다. 모델 버전, 데이터셋 및 인터랙티브 데모를 공개합니다.

팁:

Batch & Video Support: SAM2는 배치 처리와 시ーム리스 비디오 분할을 네이티브로 지원하며, 원본 SAM은 정적 이미지와 한 번에 하나의 이미지를 처리하는 단순한 워크플로우를 위해 설계되었습니다.
Accuracy & Generalization: SAM2는 원래 SAM과 비교하여, 특히 혼합 프롬프트를 사용할 때 분할 품질, 견고성, 새로운 도메인에 대한 제로샷 일반화 성능이 향상되었습니다.

이 모델은 sangbumchoi와 yonigozlan이 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.

사용 예시

비디오 분할 및 추적

SAM2의 핵심 강점은 비디오 프레임 간에 객체를 추적하는 능력입니다. 비디오 분할에 활용하는 방법은 다음과 같습니다:

기본 비디오 추적

from transformers import Sam2VideoModel, Sam2VideoProcessor
import torch

model = Sam2VideoModel.from_pretrained("facebook/sam2.1-hiera-tiny", device_map="auto")
processor = Sam2VideoProcessor.from_pretrained("facebook/sam2.1-hiera-tiny")

# Load video frames (example assumes you have a list of PIL Images)
# video_frames = [Image.open(f"frame_{i:05d}.jpg") for i in range(num_frames)]

# For this example, we'll use the video loading utility
from transformers.video_utils import load_video
video_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/bedroom.mp4"
video_frames, _ = load_video(video_url)

# Initialize video inference session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
)

# Add click on first frame to select object
ann_frame_idx = 0
ann_obj_id = 1
points = [[[[210, 350]]]]
labels = [[[1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Segment the object on the first frame
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Segmentation shape: {video_res_masks.shape}")
Segmentation shape: torch.Size([1, 1, 480, 854])

# Propagate through the entire video
video_segments = {}
for sam2_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam2_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam2_video_output.frame_idx] = video_res_masks

print(f"Tracked object through {len(video_segments)} frames")
Tracked object through 180 frames

다중 객체 비디오 추적

다중 객체를 비디오 프레임에 걸쳐 동시에 추적합니다:

# Reset for new tracking session
inference_session.reset_inference_session()

# Add multiple objects on the first frame
ann_frame_idx = 0
obj_ids = [2, 3]
input_points = [[[[200, 300]], [[400, 150]]]]  # Points for two objects (batched)
input_labels = [[[1], [1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for both objects on first frame
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)

# Propagate both objects through video
video_segments = {}
for sam2_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam2_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam2_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames

비디오 분할 개선

프레임에서 추가 클릭을 수행하여 추적을 정밀하게 조정할 수 있습니다:

# Add refinement click on a later frame
refine_frame_idx = 50
ann_obj_id = 2  # Refining first object
points = [[[[220, 280]]]]  # Additional point
labels = [[[1]]]  # Positive click

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=refine_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Re-propagate with the additional information
video_segments = {}
for sam2_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam2_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam2_video_output.frame_idx] = video_res_masks

스트리밍 비디오 추론

실시간 애플리케이션을 위해 SAM2는 비디오 프레임이 도착하는 대로 처리하는 것을 지원합니다:

# Initialize session for streaming
inference_session = processor.init_video_session(
    inference_device=device,
)

# Process frames one by one
for frame_idx, frame in enumerate(video_frames[:10]):  # Process first 10 frames
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    if frame_idx == 0:
        # Add point input on first frame
        processor.add_inputs_to_inference_session(
            inference_session=inference_session,
            frame_idx=0,
            obj_ids=1,
            input_points=[[[[210, 350], [250, 220]]]],
            input_labels=[[[1, 1]]],
            original_size=inputs.original_sizes[0], # need to be provided when using streaming video inference
        )
...
    # Process current frame
    sam2_video_output = model(inference_session=inference_session, frame=inputs.pixel_values[0])
...
    video_res_masks = processor.post_process_masks(
        [sam2_video_output.pred_masks], original_sizes=inputs.original_sizes, binarize=False
    )[0]
    print(f"Frame {frame_idx}: mask shape {video_res_masks.shape}")

여러 개체를 위한 비디오 배치 처리

동시에 여러 개체를 추적하려면, 모든 개체를 한 번에 추가하여 비디오에서 동시에 추적할 수 있습니다:

# Initialize video session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
)

# Add multiple objects on the first frame using batch processing
ann_frame_idx = 0
obj_ids = [2, 3]  # Track two different objects
input_points = [
    [[[200, 300], [230, 250], [275, 175]], [[400, 150]]]
]  # Object 2: 3 points (2 positive, 1 negative); Object 3: 1 point
input_labels = [
    [[1, 1, 0], [1]]
]  # Object 2: positive, positive, negative; Object 3: positive

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for all objects on the first frame
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Generated masks for {video_res_masks.shape[0]} objects")
Generated masks for 2 objects

# Propagate all objects through the video
video_segments = {}
for sam2_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam2_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam2_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames

리소스

SAM을 시작하는 데 도움이 되는 공식 Hugging Face 및 커뮤니티(🌎로 표시) 리소스 목록입니다.

Sangbum Choi님이 기여한 모델을 사용하는 Demo notebook 🌎.

Transformers

SAM2 Video

개요

사용 예시

비디오 분할 및 추적

기본 비디오 추적

다중 객체 비디오 추적

비디오 분할 개선

스트리밍 비디오 추론

여러 개체를 위한 비디오 배치 처리

리소스

Sam2VideoConfig

클래스 transformers.Sam2VideoConfig

Sam2VideoMaskDecoderConfig

class transformers.Sam2VideoMaskDecoderConfig

Sam2VideoPromptEncoderConfig

class transformers.Sam2VideoPromptEncoderConfig

Sam2VideoProcessor

클래스 transformers.Sam2VideoProcessor

__call__

post_process_masks

init_video_session

add_inputs_to_inference_session

Sam2VideoVideoProcessor

class transformers.Sam2VideoVideoProcessor

post_process_masks

Sam2VideoInferenceSession

class transformers.Sam2VideoInferenceSession

add_mask_inputs

add_new_frame

add_point_inputs

get_frame

get_obj_num

get_output

obj_id_to_idx

obj_idx_to_id

remove_mask_inputs

remove_point_inputs

reset_inference_session

reset_tracking_data

store_output

Sam2VideoModel

클래스 transformers.Sam2VideoModel

forward

propagate_in_video_iterator

get_image_features

call