Bu model, 2025-08-14 tarihinde Hugging Face Transformers'a katkıda bulunulmuştur.

SAM2 Video

Genel Bakış

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 ve Christoph Feichtenhofer tarafından Segment Anything in Images and Videos makalesinde önerilmiştir.

Model, girdi olarak bir görüntü veya video ile girdi noktaları veya sınırlayıcı kutular verildiğinde, ilgi duyulan herhangi bir nesnenin segmentasyon maskelerini tahmin etmek için kullanılabilir.

example image

Makalenin özeti aşağıdaki gibidir:

Segment Anything Model 2 (SAM 2)'yi sunuyoruz; bu, görüntülerde ve videolarda istemlenebilir görsel segmentasyonu çözmeye yönelik bir temel modeldir. Kullanıcı etkileşimi yoluyla model ve veriyi iyileştiren bir veri motoru geliştirerek, bugüne kadar toplanan en büyük video segmentasyon veri setini derledik. Modelimiz, gerçek zamanlı video işleme için akış belleğine sahip basit bir transformer mimarisidir. Verilerimiz üzerinde eğitilen SAM 2, geniş bir görev yelpazesinde güçlü performans sağlar. Video segmentasyonunda, önceki yaklaşımlara kıyasla 3 kat daha az etkileşimle daha yüksek doğruluk gözlemliyoruz. Görüntü segmentasyonunda ise modelimiz, Segment Anything Model (SAM)'den daha doğru ve 6 kat daha hızlıdır. Verilerimizin, modelimizin ve içgörülerimizin, video segmentasyonu ve ilgili algılama görevleri için önemli bir kilometre taşı olacağına inanıyoruz. Modelimizin bir sürümünü, veri setini ve etkileşimli bir demo'yu yayınlıyoruz.

İpuçları:

Batch & Video Desteği: SAM2, yerel olarak batch işleme ve sorunsuz video segmentasyonunu desteklerken, orijinal SAM statik görüntüler ve daha basit, tek seferde tek görüntü işleme akışları için tasarlanmıştır.
Doğruluk ve Genelgeçerlik: SAM2, orijinal SAM'a kıyasla özellikle karma prompt'larla birlikte segmentasyon kalitesinde, sağlamlıkta ve yeni alanlara sıfır atış genelgeçerliğinde iyileşme göstermektedir.

Bu model sangbumchoi ve yonigozlan tarafından katkıda bulunmuştur. Orijinal kod burada bulunabilir.

Kullanım örneği

Video Segmentasyonu ve Takibi

SAM2'nin temel gücü, nesneleri video kareleri boyunca izleme yeteneğidir. Video segmentasyonu için nasıl kullanılacağı aşağıda gösterilmektedir:

Temel Video Takibi

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

Çoklu Nesne Video Takibi

Video kareleri boyunca birden fazla nesneyi eş zamanlı olarak izleyin:

# 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

Video Segmentasyonunu İnce Ayar

Herhangi bir karede ek tıklamalar yaparak takibi iyileştirebilirsiniz:

# 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

Akışkan Video Çıkarımı

Gerçek zamanlı uygulamalar için SAM2, video kareleri geldikçe işlenmesini destekler:

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

Çoklu Nesneler için Video Toplu İşleme

Video'da birden fazla nesneyi aynı anda izlemek için hepsini tek seferde ekleyin:

# 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

Kaynaklar

SAM ile başlamanıza yardımcı olmak için resmi Hugging Face ve topluluk (🌎 ile belirtilen) kaynaklarının listesi.

Modeli kullanmak için Sangbum Choi tarafından katkıda bulunan Demo notebook 🌎.

Transformers

SAM2 Video

Genel Bakış

Kullanım örneği

Video Segmentasyonu ve Takibi

Temel Video Takibi

Çoklu Nesne Video Takibi

Video Segmentasyonunu İnce Ayar

Akışkan Video Çıkarımı

Çoklu Nesneler için Video Toplu İşleme

Kaynaklar

Sam2VideoConfig

sınıf transformers.Sam2VideoConfig

Sam2VideoMaskDecoderConfig

sınıf transformers.Sam2VideoMaskDecoderConfig

Sam2VideoPromptEncoderConfig

sınıf transformers.Sam2VideoPromptEncoderConfig

Sam2VideoProcessor

sınıf transformers.Sam2VideoProcessor

__call__

post_process_masks

init_video_session

add_inputs_to_inference_session

Sam2VideoVideoProcessor

sınıf transformers.Sam2VideoVideoProcessor

post_process_masks

Sam2VideoInferenceSession

sınıf 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

sınıf transformers.Sam2VideoModel

forward

propagate_in_video_iterator

get_image_features

call