Transformers documentation

EdgeTAMVideo

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.2).

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-01-13 tarihinde HF papers'ta yayımlandı ve 2025-09-29 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

EdgeTAMVideo

Genel Bakış

EdgeTAM modeli, EdgeTAM: On-Device Track Anything Model adlı makalede Chong Zhou, Chenchen Zhu, Yunyang Xiong, Saksham Suri, Fanyi Xiao, Lemeng Wu, Raghuraman Krishnamoorthi, Bo Dai, Chen Change Loy, Vikas Chandra ve Bilge Soran tarafından önerilmiştir.

EdgeTAM, mobil cihazlarda gerçek zamanlı video segmentasyonu için bellek dikkat mekanizmalarını optimize etmek amacıyla 2B Uzamsal Perceiver mimarisi tanıtan SAM 2'nin verimli bir uyarlamasıdır.

Makalenin özeti aşağıdaki gibidir:

Segment Anything Model (SAM) üzerine kurulu SAM 2, bir hafıza bankası mekanizması aracılığıyla yetkinliğini görüntüden video girdilerine doğru daha da genişletir ve önceki yöntemlere kıyasla olağanüstü bir performans elde ederek video segmentasyon görevi için bir temel model haline gelir. Bu makalede, SAM 2'yi çok daha verimli hale getirerek, karşılaştırılabilir bir performansı korurken mobil cihazlarda bile çalışmasını sağlamayı hedefliyoruz. SAM'ın verimliliğini artırmak için optimize eden birkaç çalışma olmasına rağmen, bunların SAM 2 için yeterli olmadığını tespit ettik; çünkü tümü görüntü kodlayıcısını sıkıştırmaya odaklanırken, benchmark'ımız yeni tanıtılan hafıza dikkat bloklarının da gecikme darboğazı olduğunu gösteriyor. Bu gözlem ışığında, hesaplama maliyetini azaltmak için yeni bir 2D Mekânsal Perceiver'dan yararlanan EdgeTAM'ı öneriyoruz. Özellikle, önerilen 2D Mekânsal Perceiver, yoğun olarak saklanan kare düzeyindeki hafızaları, sabit bir öğrenilebilir sorgu kümesi içeren hafif bir Transformer ile kodlar. Video segmentasyonunun yoğun bir tahmin görevi olması nedeniyle, sorguların küresel düzeyde ve yama (patch) düzeyinde gruplara ayrılması gerektiğinden, hafızaların mekânsal yapısının korunmasının hayati önem taşıdığını tespit ettik. Ayrıca, çıkarım (inference) maliyeti olmadan performansı daha da artıran bir damıtma (distillation) hattı öneriyoruz. Sonuç olarak EdgeTAM, DAVIS 2017, MOSE, SA-V val ve SA-V test setlerinde sırasıyla 87,7, 70,0, 72,3 ve 71,7 J&F değerlerine ulaşırken, iPhone 15 Pro Max üzerinde 16 FPS hızında çalışmaktadır.

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

Kullanım örneği

Video Segmentasyonu ve Takibi

EdgeTAM Video'nun temel gücü, mobil cihazlarda video kareleri arasında nesneleri verimli bir şekilde izleme yeteneğidir. Video segmentasyonu için nasıl kullanılacağı aşağıda açıklanmıştır:

Temel Video Takibi

from transformers import EdgeTamVideoModel, Sam2VideoProcessor
import torch

model = EdgeTamVideoModel.from_pretrained("yonigozlan/edgetam-video-1", device_map="auto")
processor = Sam2VideoProcessor.from_pretrained("yonigozlan/edgetam-video-1")

# 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, 540, 960])

# 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 200 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 200 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 EdgeTAM Video, 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}")

Frame 0: mask shape torch.Size([1, 1, 540, 960])
...

Ç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 200 frames

Transformers

EdgeTAMVideo

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

EdgeTamVideoMaskDecoderConfig

sınıf transformers.EdgeTamVideoMaskDecoderConfig

EdgeTamVideoPromptEncoderConfig

sınıf transformers.EdgeTamVideoPromptEncoderConfig

EdgeTamVideoConfig

sınıf transformers.EdgeTamVideoConfig

EdgeTamVideoInferenceSession

sınıf transformers.EdgeTamVideoInferenceSession

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

EdgeTamVideoModel

sınıf transformers.EdgeTamVideoModel

forward

get_image_features