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

Эта модель была опубликована в HF papers 13.01.2025 и добавлена в Hugging Face Transformers 29.09.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, в которой представлена архитектура 2D Spatial Perceiver для оптимизации механизмов внимания в памяти при сегментации видео в реальном времени на мобильных устройствах.

Аннотация из статьи следующая:

В дополнение к Segment Anything Model (SAM), SAM 2 расширяет его возможности с изображений на видеовход с помощью механизма банка памяти и демонстрирует выдающуюся производительность по сравнению с предыдущими методами, что делает его фундаментальной моделью для задачи сегментации видео. В данной статье мы ставим целью сделать SAM 2 значительно более эффективным, чтобы он мог работать на мобильных устройствах, сохраняя сопоставимую производительность. Несмотря на ряд работ, оптимизирующих SAM для повышения эффективности, мы обнаруживаем, что их недостаточно для SAM 2, поскольку все они сосредоточены на сжатии кодировщика изображений, тогда как наш бенчмарк показывает, что вновь введенные блоки внимания памяти также являются узким местом задержки. Исходя из этого наблюдения, мы предлагаем EdgeTAM, который использует новый 2D Spatial Perceiver для снижения вычислительных затрат. В частности, предложенный 2D Spatial Perceiver кодирует плотно хранимую память на уровне кадров с помощью легковесного Transformer, содержащего фиксированный набор обучаемых запросов. Поскольку сегментация видео является задачей плотного предсказания, мы обнаруживаем, что сохранение пространственной структуры памяти имеет решающее значение, поэтому запросы разделяются на группы глобального и патч-уровня. Мы также предлагаем конвейер дистилляции, который дополнительно улучшает производительность без накладных расходов на инференс. В результате EdgeTAM достигает 87,7, 70,0, 72,3 и 71,7 J&F на DAVIS 2017, MOSE, SA-V val и SA-V test, при этом работая со скоростью 16 FPS на 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