Transformers documentation

SAM3 Video

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

SAM3 Video

Genel Bakış

SAM3 (Segment Anything Model 3), SAM 3: Segment Anything with Concepts makalesinde tanıtılmıştır.

SAM3 Video, videolarda Promptable Concept Segmentation (PCS) gerçekleştirir. PCS, metin girdisi alır (ör. “yellow school bus”) ve kavramla eşleşen her bir nesne için örnekleme ve anlamsal maskeleri tahmin ederken, nesne kimliklerini video kareleri boyunca korur.

Model, metin istemleri kullanılarak video kareleri arasında sağlam nesne takibi yapılmasını sağlamak için bir algılama modülü (SAM3) ile bir takip modülünü (SAM2 tarzı takipçi) birleştirir.

Makalenin özeti aşağıdaki gibidir:

Segment Anything Model (SAM) 3'ü sunuyoruz. Bu, kısa isim tamlamaları (ör. “yellow school bus”), görsel örnekler veya her ikisinin birleşimi olarak tanımladığımız kavram istemlerine (concept prompts) dayanarak görüntülerde ve videolarda nesneleri algılayan, segmente eden ve izleyen birleşik bir modeldir. Promptable Concept Segmentation (PCS), bu tür istemleri alır ve eşleşen tüm nesne örnekleri için segmentasyon maskeleri ve benzersiz kimlikler döndürür. PCS'yi ilerletmek için, görüntüler ve videolar arasında zor negatifleri (hard negatives) içeren, 4M benzersiz kavram etiketine sahip yüksek kaliteli bir veri seti üreten ölçeklenebilir bir veri motoru geliştiriyoruz. Modelimiz, tek bir omurga (backbone) paylaşan görüntü düzeyinde bir algılayıcı ve bellek tabanlı bir video izleyiciden oluşur. Tanıma ve konumlandırma, algılama doğruluğunu artıran bir varlık başlığı (presence head) ile ayrıştırılır. SAM 3, hem görüntü hem de video PCS'de mevcut sistemlerin doğruluğunu ikiye katlar ve önceki SAM yeteneklerini görsel segmentasyon görevlerinde iyileştirir. Promptable concept segmentation için yeni Segment Anything with Concepts (SA-Co) benchmark'ımızla birlikte SAM 3'ü açık kaynak olarak yayımlıyoruz.

Bu model yonigozlan ve ronghanghu tarafından katkıda bulunmuştur.

Kullanım örneği

Video Segmentasyonu ve Takibi

Önceden Yüklenmiş Video Çıkarımı

Metin istemleri kullanarak tüm kareleri zaten mevcut olan bir videoyu işleyin:

from transformers import Sam3VideoModel, Sam3VideoProcessor
import torch

model = Sam3VideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3")

# Load video frames
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,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt to detect and track objects
text = "person"
inference_session = processor.add_text_prompt(
    inference_session=inference_session,
    text=text,
)

# Process all frames in the video
outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=inference_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(inference_session, model_outputs)
    outputs_per_frame[model_outputs.frame_idx] = processed_outputs

print(f"Processed {len(outputs_per_frame)} frames")
Processed 51 frames

# Access results for a specific frame
frame_0_outputs = outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects")
print(f"Object IDs: {frame_0_outputs['object_ids'].tolist()}")
print(f"Scores: {frame_0_outputs['scores'].tolist()}")
print(f"Boxes shape (XYXY format, absolute coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks shape: {frame_0_outputs['masks'].shape}")

Birden fazla istem sağlayarak aynı anda birden fazla nesne kategorisini de izleyebilirsiniz. Model, tüm istemler arasında görme özelliklerini verimli bir şekilde yeniden kullanır:

# Add multiple text prompts (or use a list in add_text_prompt)
multi_prompt_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)
>>>
prompts = ["person", "bed", "lamp"]
processor.add_text_prompt(multi_prompt_session, prompts)
>>>
# Process video - detects objects from ALL prompts in a single pass
multi_outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=multi_prompt_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(multi_prompt_session, model_outputs)
    multi_outputs_per_frame[model_outputs.frame_idx] = processed_outputs
>>>
# Check which objects were detected by each prompt
frame_0_outputs = multi_outputs_per_frame[0]
prompt_to_obj_ids = frame_0_outputs["prompt_to_obj_ids"]
for prompt, obj_ids in prompt_to_obj_ids.items():
    print(f"{prompt}: {len(obj_ids)} objects")
person: 2 objects
bed: 1 objects
lamp: 1 objects

Akışkan Video Çıkarımı

⚠️ **Akış Çıkarımı Kalitesi Hakkında Not**: Akış çıkarımı, eşleşmeyen ve yinelenen nesneleri kaldıran hotstart sezgisel yöntemlerini devre dışı bırakır; çünkü bu yöntemler bilinçli kararlar verebilmek için gelecek karelere erişim gerektirir. Bu durum, önceden yüklenmiş video çıkarımına kıyasla daha fazla yanlış pozitif algılama ve yinelenen nesne izlerine yol açabilir. En iyi sonuçlar için, tüm kareler mevcut olduğunda önceden yüklenmiş video çıkarımını kullanın.

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

# Initialize session for streaming
streaming_inference_session = processor.init_video_session(
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt
text = "person"
streaming_inference_session = processor.add_text_prompt(
    inference_session=streaming_inference_session,
    text=text,
)

# Process frames one by one (streaming mode)
streaming_outputs_per_frame = {}
for frame_idx, frame in enumerate(video_frames[:50]):  # Process first 50 frames
    # First, process the frame using the processor
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    # Process frame using streaming inference - pass the processed pixel_values
    model_outputs = model(
        inference_session=streaming_inference_session,
        frame=inputs.pixel_values[0],  # Provide processed frame - this enables streaming mode
        reverse=False,
    )
...
    # Post-process outputs with original_sizes for proper resolution handling
    processed_outputs = processor.postprocess_outputs(
        streaming_inference_session,
        model_outputs,
        original_sizes=inputs.original_sizes,  # Required for streaming inference
    )
    streaming_outputs_per_frame[frame_idx] = processed_outputs
...
    if (frame_idx + 1) % 10 == 0:
        print(f"Processed {frame_idx + 1} frames...")

print(f"✓ Streaming inference complete! Processed {len(streaming_outputs_per_frame)} frames")
✓ Streaming inference complete! Processed 50 frames

# Access results
frame_0_outputs = streaming_outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects in first frame")
print(f"Boxes are in XYXY format (absolute pixel coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks are at original video resolution: {frame_0_outputs['masks'].shape}")

Özel Çözünürlükte Çıkarım

⚠️ **Performans Notu**: Özel çözünürlükler doğruluğu düşürebilir. Model, 1008px çözünürlükte kullanılacak şekilde tasarlanmıştır.

Daha hızlı çıkarım veya daha düşük bellek kullanımı için:

config = Sam3VideoConfig.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3VideoModel.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})

Transformers

SAM3 Video

Genel Bakış

Kullanım örneği

Video Segmentasyonu ve Takibi

Önceden Yüklenmiş Video Çıkarımı

Akışkan Video Çıkarımı

Özel Çözünürlükte Çıkarım

Sam3VideoConfig

sınıf transformers.Sam3VideoConfig

Sam3VideoProcessor

sınıf transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

sınıf transformers.Sam3VideoInferenceSession

add_mask_inputs

add_new_frame

add_prompt

get_frame

get_obj_num

get_output

obj_id_to_idx

obj_idx_to_id

remove_mask_inputs

remove_object

reset_inference_session

reset_state

reset_tracking_data

store_output

Sam3VideoSegmentationOutput

sınıf transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

sınıf transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call