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

نُشر هذا النموذج في أوراق HF في 13 يناير 2025، وأُضيف إلى مكتبة Hugging Face Transformers في 29 سبتمبر 2025.

EdgeTAMVideo

نظرة عامة

قُدِّم نموذج EdgeTAM في EdgeTAM: On-Device Track Anything Model Chong Zhou, Chenchen Zhu, Yunyang Xiong, Saksham Suri, Fanyi Xiao, Lemeng Wu, Raghuraman Krishnamoorthi, Bo Dai, Chen Change Loy, Vikas Chandra, Bilge Soran.

EdgeTAM هو تكييف فعّال لـ SAM 2 يُدخل بنية Perceiver مكانية ثنائية الأبعاد لتحسين آليات الانتباه في الذاكرة من أجل تجزئة الفيديو في الوقت الفعلي على الأجهزة المحمولة.

المستخلص من الورقة البحثية هو كالتالي:

بالإضافة إلى نموذج Segment Anything Model (SAM)، يوسّع SAM 2 قدرته من مدخلات الصور إلى مدخلات الفيديو من خلال آلية بنك الذاكرة، ويحقق أداءً ملحوظًا مقارنةً بالطرق السابقة، مما يجعله نموذجًا أساسيًا لمهمة تجزئة الفيديو. في هذه الورقة، نهدف إلى جعل SAM 2 أكثر كفاءة بكثير بحيث يعمل حتى على الأجهزة المحمولة مع الحفاظ على أداء مماثل. على الرغم من وجود عدة أعمال تهدف إلى تحسين كفاءة SAM، نجد أنها غير كافية لـ SAM 2 لأنها تركز جميعها على ضغط مشفّر الصورة، بينما تُظهر معاييرنا المرجعية أن كتل الانتباه الذاكري الجديدة المُدخلة هي أيضًا عنق الزجاجة في زمن الاستجابة. بناءً على هذه الملاحظة، نقترح EdgeTAM، الذي يستفيد من Perceiver مكاني ثنائي الأبعاد جديد لتقليل التكلفة الحسابية. على وجه التحديد، يُشفّر Perceiver المكاني ثنائي الأبعاد المقترح الذاكرات على مستوى الإطار المخزنة بكثافة باستخدام Transformer خفيف يحتوي على مجموعة ثابتة من الاستعلامات القابلة للتعلم. ونظرًا لأن تجزئة الفيديو مهمة تنبؤ كثيف، نجد أن الحفاظ على البنية المكانية للذاكرات أمر جوهري، لذا يتم تقسيم الاستعلامات إلى مجموعات على مستوى عام ومجموعات على مستوى الباتش. كما نقترح خط أنابيب تقطير يحسّن الأداء بشكل أكبر دون أي عبء على الاستدلال. ونتيجةً لذلك، يحقق EdgeTAM قيم J&F تبلغ 87.7 و70.0 و72.3 و71.7 على DAVIS 2017 وMOSE وSA-V val وSA-V test، بينما يعمل بسرعة 16 إطارًا في الثانية على iPhone 15 Pro Max.

تمت مساهمة هذا النموذج من قِبل yonigozlan. يمكن العثور على الكود الأصلي هنا.

مثال على الاستخدام

تجزئة الفيديو وتتبعه

تتمثل القوة الرئيسية لـ EdgeTAM Video في قدرته على تتبع الكائنات عبر إطارات الفيديو بكفاءة على الأجهزة المحمولة. فيما يلي كيفية استخدامه لتجزئة الفيديو:

تتبع الفيديو الأساسي

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

تتبع الفيديو متعدد الأهداف

تتبع عدة كائنات في وقت واحد عبر إطارات الفيديو:

# 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

تحسين تجزئة الفيديو

يمكنك إضافة نقرات إضافية على أي إطار لتحسين التتبع:

# 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

الاستدلال على الفيديو عبر البث

لتطبيقات الوقت الحقيقي، يدعم EdgeTAM Video معالجة إطارات الفيديو عند وصولها:

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

معالجة الدُفعات من الفيديو لعدة كائنات

تتبّع عدة كائنات في نفس الوقت داخل الفيديو عن طريق إضافتها جميعًا دفعة واحدة:

# 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

نظرة عامة

مثال على الاستخدام

تجزئة الفيديو وتتبعه

تتبع الفيديو الأساسي

تتبع الفيديو متعدد الأهداف

تحسين تجزئة الفيديو

الاستدلال على الفيديو عبر البث

معالجة الدُفعات من الفيديو لعدة كائنات

EdgeTamVideoMaskDecoderConfig

فئة transformers.EdgeTamVideoMaskDecoderConfig

EdgeTamVideoPromptEncoderConfig

فئة transformers.EdgeTamVideoPromptEncoderConfig

EdgeTamVideoConfig

فئة transformers.EdgeTamVideoConfig

EdgeTamVideoInferenceSession

فئة 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

فئة transformers.EdgeTamVideoModel

forward

get_image_features