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

Model ini dipublikasikan di HF papers pada 2025-01-13 dan disumbangkan ke Hugging Face Transformers pada 2025-09-29.

EdgeTAMVideo

Ikhtisar

Model EdgeTAM diusulkan dalam 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 adalah adaptasi efisien dari SAM 2 yang memperkenalkan arsitektur 2D Spatial Perceiver untuk mengoptimalkan mekanisme perhatian memori bagi segmentasi video real-time pada perangkat mobile.

Abstrak dari makalah tersebut adalah sebagai berikut:

Di atas Segment Anything Model (SAM), SAM 2 lebih lanjut memperluas kemampuannya dari input gambar ke input video melalui mekanisme memory bank dan memperoleh kinerja yang luar biasa dibandingkan dengan metode sebelumnya, menjadikannya model fondasi untuk tugas segmentasi video. Dalam makalah ini, kami bertujuan untuk membuat SAM 2 jauh lebih efisien sehingga bahkan dapat berjalan pada perangkat seluler sambil mempertahankan kinerja yang sebanding. Meskipun ada beberapa karya yang mengoptimalkan SAM untuk efisiensi yang lebih baik, kami menemukan bahwa mereka tidak cukup untuk SAM 2 karena semuanya berfokus pada kompresi image encoder, sementara benchmark kami menunjukkan bahwa blok memory attention yang baru diperkenalkan juga merupakan bottleneck latensi. Mengingat observasi ini, kami mengusulkan EdgeTAM, yang memanfaatkan 2D Spatial Perceiver baru untuk mengurangi biaya komputasi. Secara khusus, 2D Spatial Perceiver yang diusulkan mengkodekan memori tingkat frame yang disimpan secara padat dengan Transformer ringan yang berisi himpunan tetap dari query yang dapat dipelajari. Mengingat segmentasi video adalah tugas prediksi padat, kami menemukan bahwa mempertahankan struktur spasial dari memori sangat penting sehingga query dipecah menjadi kelompok tingkat global dan tingkat patch. Kami juga mengusulkan pipeline distilasi yang lebih lanjut meningkatkan kinerja tanpa overhead inferensi. Akibatnya, EdgeTAM mencapai 87,7, 70,0, 72,3, dan 71,7 J&F pada DAVIS 2017, MOSE, SA-V val, dan SA-V test, sambil berjalan pada 16 FPS di iPhone 15 Pro Max.

Model ini disumbangkan oleh yonigozlan. Kode aslinya dapat ditemukan di sini.

Contoh penggunaan

Segmentasi dan Pelacakan Video

Kekuatan utama EdgeTAM Video adalah kemampuannya untuk melacak objek di antara bingkai video secara efisien pada perangkat mobile. Berikut cara menggunakannya untuk segmentasi video:

Pelacakan Video Dasar

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

Pelacakan Video Multi-Objek

Lacak beberapa objek secara bersamaan di antara bingkai video:

# 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

Menyempurnakan Segmentasi Video

Anda dapat menambahkan klik tambahan pada frame mana pun untuk menyempurnakan pelacakan:

# 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

Inferensi Video Streaming

Untuk aplikasi real-time, EdgeTAM Video mendukung pemrosesan bingkai video saat mereka tiba:

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

Pemrosesan Batch Video untuk Beberapa Objek

Lacak beberapa objek secara bersamaan dalam video dengan menambahkan semuanya sekaligus:

# 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

Ikhtisar

Contoh penggunaan

Segmentasi dan Pelacakan Video

Pelacakan Video Dasar

Pelacakan Video Multi-Objek

Menyempurnakan Segmentasi Video

Inferensi Video Streaming

Pemrosesan Batch Video untuk Beberapa Objek

EdgeTamVideoMaskDecoderConfig

kelas transformers.EdgeTamVideoMaskDecoderConfig

EdgeTamVideoPromptEncoderConfig

kelas transformers.EdgeTamVideoPromptEncoderConfig

EdgeTamVideoConfig

kelas transformers.EdgeTamVideoConfig

EdgeTamVideoInferenceSession

kelas 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

kelas transformers.EdgeTamVideoModel

forward

get_image_features