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

Ce modèle a été publié dans HF papers le 2025-01-13 et ajouté à Hugging Face Transformers le 2025-09-29.

EdgeTAMVideo

Aperçu

Le modèle EdgeTAM a été proposé dans 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 est une adaptation efficace de SAM 2 qui introduit une architecture 2D Spatial Perceiver afin d'optimiser les mécanismes d'attention mémoire pour la segmentation vidéo en temps réel sur des appareils mobiles.

L'abstract de l'article est le suivant :

Au-delà de Segment Anything Model (SAM), SAM 2 étend davantage sa capacité des images aux entrées vidéo grâce à un mécanisme de mémoire et obtient des performances remarquables par rapport aux méthodes précédentes, ce qui en fait un modèle de base pour la tâche de segmentation vidéo. Dans cet article, nous visons à rendre SAM 2 beaucoup plus efficace afin qu'il puisse même s'exécuter sur des appareils mobiles tout en maintenant des performances comparables. Malgré plusieurs travaux optimisant SAM pour une meilleure efficacité, nous constatons qu'ils ne sont pas suffisants pour SAM 2, car ils se concentrent tous sur la compression de l'encodeur d'image, alors que notre référence montre que les nouveaux blocs d'attention mémoire introduits constituent également le goulot d'étranglement de latence. Compte tenu de cette observation, nous proposons EdgeTAM, qui exploite un nouveau 2D Spatial Perceiver pour réduire le coût de calcul. En particulier, le 2D Spatial Perceiver proposé encode les mémoires de niveau image stockées de manière dense avec un Transformer léger contenant un ensemble fixe de requêtes apprenables. Étant donné que la segmentation vidéo est une tâche de prédiction dense, nous constatons qu'il est essentiel de préserver la structure spatiale des mémoires, de sorte que les requêtes sont divisées en groupes de niveau global et de niveau patch. Nous proposons également un pipeline de distillation qui améliore davantage les performances sans surcharge d'inférence. En conséquence, EdgeTAM atteint 87,7, 70,0, 72,3 et 71,7 J&F sur DAVIS 2017, MOSE, SA-V val et SA-V test, tout en fonctionnant à 16 FPS sur iPhone 15 Pro Max.

Ce modèle a été contribué par yonigozlan. Le code d'origine peut être trouvé ici.

Exemple d'utilisation

Segmentation et suivi vidéo

La principale force d’EdgeTAM Video est sa capacité à suivre efficacement des objets à travers les images d’une vidéo sur des appareils mobiles. Voici comment l’utiliser pour la segmentation vidéo :

Suivi vidéo de base

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

Suivi vidéo multi-objets

Suivre plusieurs objets simultanément à travers les images vidéo :

# 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

Affiner la segmentation vidéo

Vous pouvez ajouter des clics supplémentaires sur n'importe quel plan pour affiner le suivi :

# 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

Inférence vidéo en streaming

Pour les applications en temps réel, EdgeTAM Video prend en charge le traitement des images vidéo à mesure qu’elles arrivent :

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

Traitement par lots de vidéos pour plusieurs objets

Suivre plusieurs objets simultanément dans une vidéo en les ajoutant tous d'un coup :

# 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

Aperçu

Exemple d'utilisation

Segmentation et suivi vidéo

Suivi vidéo de base

Suivi vidéo multi-objets

Affiner la segmentation vidéo

Inférence vidéo en streaming

Traitement par lots de vidéos pour plusieurs objets

EdgeTamVideoMaskDecoderConfig

classe transformers.EdgeTamVideoMaskDecoderConfig

EdgeTamVideoPromptEncoderConfig

classe transformers.EdgeTamVideoPromptEncoderConfig

EdgeTamVideoConfig

classe transformers.EdgeTamVideoConfig

EdgeTamVideoInferenceSession

classe 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

classe transformers.EdgeTamVideoModel

forward

get_image_features