このモデルは2025年11月19日にHugging Face Transformersに貢献されました。

SAM3 Tracker Video

概要

SAM3 (Segment Anything Model 3) は、SAM 3: Segment Anything with Concepts で紹介されました。

Sam3TrackerVideo は動画に対して Promptable Visual Segmentation (PVS) を実行します。PVS は、インタラクティブな視覚プロンプト（点、ボックス、マスク）またはテキスト入力を受け取り、プロンプトごとに 特定のオブジェクトインスタンス を動画フレーム間でトラッキングします。

Sam3TrackerVideo は、SAM2 Video の更新版であり、同じ API を維持しながら、パフォーマンスと機能の向上を提供します。

論文の抄録は以下の通りです。

本稿では、Segment Anything Model (SAM) 3 を紹介します。SAM 3 は、概念プロンプトに基づいて画像および動画内のオブジェクトを検出・セグメンテーション・トラッキングを行う統合モデルです。ここでいう概念プロンプトとは、短い名詞句（例：「yellow school bus」）、画像のサンプル、またはそれらの組み合わせを指します。Promptable Concept Segmentation (PCS) は、こうしたプロンプトを受け取り、一致するすべてのオブジェクトインスタンスに対してセグメンテーションマスクと一意のIDを返します。PCS の発展を目的として、画像と動画にわたって困難なネガティブ例を含む 400 万のユニークな概念ラベルからなる高品質なデータセットを生成するスケーラブルなデータエンジンを構築しました。本モデルは、単一のバックボーンを共有する画像レベルの検出器と、メモリベースの動画トラッカーで構成されています。存在ヘッドによって認識と位置特定を分離することで、検出精度を向上させています。SAM 3 は、画像および動画の PCS において既存システムの精度を 2 倍に向上させ、視覚的セグメンテーションタスクにおける従来の SAM の機能も改善しています。SAM 3 と、プロンプタブル概念セグメンテーションのための新ベンチマーク Segment Anything with Concepts (SA-Co) をオープンソースとして公開します。

このモデルは、yonigozlan 氏と ronghanghu 氏によって提供されました。

使用例

Video Segmentation and Tracking

基本的なビデオトラッキング

from transformers import Sam3TrackerVideoModel, Sam3TrackerVideoProcessor
import torch

model = Sam3TrackerVideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerVideoProcessor.from_pretrained("facebook/sam3")

# 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 (optional, you can also propagate the masks through the video directly)
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, 480, 854])

# Propagate through the entire video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks

print(f"Tracked object through {len(video_segments)} frames")
Tracked object through 180 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 (optional, you can also propagate the masks through the video directly)
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)

# Propagate both objects through video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_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 180 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 sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks

ストリーミング動画推論

リアルタイムアプリケーション向けに、Sam3TrackerVideoは、フレームが到着するたびに処理を行うことをサポートしています:

# 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
    sam3_tracker_video_output = model(inference_session=inference_session, frame=inputs.pixel_values[0])
...
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=inputs.original_sizes, binarize=False
    )[0]
    print(f"Frame {frame_idx}: mask shape {video_res_masks.shape}")

複数のオブジェクト向けのビデオバッチ処理

をすべて一度に追加して、動画内の複数のオブジェクトを同時にトラッキングします:

# 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 sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_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 180 frames

Transformers

SAM3 Tracker Video

概要

使用例

Video Segmentation and Tracking

基本的なビデオトラッキング

マルチオブジェクト・ビデオトラッキング

動画セグメンテーションの洗練

ストリーミング動画推論

複数のオブジェクト向けのビデオバッチ処理

Sam3TrackerVideoConfig

クラス transformers.Sam3TrackerVideoConfig

Sam3TrackerVideoMaskDecoderConfig

クラス transformers.Sam3TrackerVideoMaskDecoderConfig

Sam3TrackerVideoPromptEncoderConfig

class transformers.Sam3TrackerVideoPromptEncoderConfig

Sam3TrackerVideoProcessor

class transformers.Sam3TrackerVideoProcessor

__call__

post_process_masks

init_video_session

add_inputs_to_inference_session

Sam3TrackerVideoInferenceSession

class transformers.Sam3TrackerVideoInferenceSession

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

Sam3TrackerVideoModel

class transformers.Sam3TrackerVideoModel

forward

propagate_in_video_iterator

get_image_features

call