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

Este modelo foi publicado no HF papers em 13/01/2025 e contribuído para o Hugging Face Transformers em 29/09/2025.

EdgeTAMVideo

Visão geral

O modelo EdgeTAM foi proposto em 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 é uma adaptação eficiente do SAM 2 que introduz uma arquitetura 2D Spatial Perceiver para otimizar os mecanismos de atenção de memória para segmentação de vídeo em tempo real em dispositivos móveis.

O resumo do artigo é o seguinte:

Além do Segment Anything Model (SAM), o SAM 2 estende ainda mais sua capacidade de imagens para entradas de vídeo por meio de um mecanismo de banco de memória e obtém um desempenho notável em comparação com métodos anteriores, tornando-o um modelo de base para a tarefa de segmentação de vídeo. Neste artigo, nosso objetivo é tornar o SAM 2 muito mais eficiente, de modo que ele possa ser executado em dispositivos móveis mantendo um desempenho comparável. Apesar de vários trabalhos que otimizam o SAM para uma melhor eficiência, constatamos que eles não são suficientes para o SAM 2, pois todos se concentram na compressão do codificador de imagem, enquanto nosso benchmark mostra que os novos blocos de atenção de memória introduzidos também são o gargalo de latência. Dada essa observação, propomos o EdgeTAM, que utiliza um novo 2D Spatial Perceiver para reduzir o custo computacional. Em particular, o 2D Spatial Perceiver proposto codifica as memórias de nível de quadro armazenadas de forma densa com um Transformer leve que contém um conjunto fixo de consultas aprendíveis. Dado que a segmentação de vídeo é uma tarefa de predição densa, constatamos que preservar a estrutura espacial das memórias é essencial, de modo que as consultas são divididas em grupos de nível global e de nível de patch. Também propomos um pipeline de destilação que melhora ainda mais o desempenho sem sobrecarga de inferência. Como resultado, o EdgeTAM alcança 87,7, 70,0, 72,3 e 71,7 J&F em DAVIS 2017, MOSE, SA-V val e SA-V test, enquanto é executado a 16 FPS no iPhone 15 Pro Max.

Este modelo foi contribuído por yonigozlan. O código original pode ser encontrado aqui.

Exemplo de uso

Segmentação e Rastreamento de Vídeo

A principal vantagem do EdgeTAM Video é a capacidade de rastrear objetos entre os quadros de um vídeo de forma eficiente em dispositivos móveis. Veja como usá-lo para segmentação de vídeo:

Rastreamento básico de vídeo

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

Rastreamento de Vídeo Multi-Objeto

Rastreie vários objetos simultaneamente entre os quadros de um vídeo:

# 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

Refinamento da segmentação de vídeo

Você pode adicionar cliques adicionais em qualquer quadro para refinar o rastreamento:

# 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

Inferência de Vídeo em Streaming

Para aplicações em tempo real, o EdgeTAM Video suporta o processamento de quadros de vídeo à medida que chegam:

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

Processamento em Lote de Vídeos para Múltiplos Objetos

Rastreie vários objetos simultaneamente em um vídeo adicionando todos de uma vez:

# 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

Visão geral

Exemplo de uso

Segmentação e Rastreamento de Vídeo

Rastreamento básico de vídeo

Rastreamento de Vídeo Multi-Objeto

Refinamento da segmentação de vídeo

Inferência de Vídeo em Streaming

Processamento em Lote de Vídeos para Múltiplos Objetos

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