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

SAM2 Video

概要

SAM2 (Segment Anything Model 2) は、Nikhila Ravi、Valentin Gabeur、Yuan-Ting Hu、Ronghang Hu、Chaitanya Ryali、Tengyu Ma、Haitham Khedr、Roman Rädle、Chloe Rolland、Laura Gustafson、Eric Mintun、Junting Pan、Kalyan Vasudev Alwala、Nicolas Carion、Chao-Yuan Wu、Ross Girshick、Piotr Dollár、Christoph Feichtenhofer によって、Segment Anything in Images and Videos で提案されました。

モデルは、入力画像または動画、および入力されたポイントまたはバウンディングボックスを指定することで、対象とする任意のオブジェクトのセグメンテーションマスクを予測するために使用できます。

example image

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

画像および動画におけるプロンプト可能な視覚セグメンテーションの解決に向けた基盤モデルであるSegment Anything Model 2 (SAM 2) を紹介します。ユーザーとのインタラクションを通じてモデルとデータを改善するデータエンジンを構築し、これまでに収集された最大規模の動画セグメンテーションデータセットを収集しました。当社のモデルは、リアルタイムの動画処理に対応するストリーミングメモリを備えたシンプルなtransformerアーキテクチャです。当社のデータで訓練されたSAM 2は、幅広いタスクで優れたパフォーマンスを発揮します。動画セグメンテーションでは、従来の手法よりも3分の1のインタラクション数で、より高い精度を実現しています。画像セグメンテーションでは、Segment Anything Model (SAM) よりも精度が高く、6倍速く動作します。当社のデータ、モデル、および知見は、動画セグメンテーションおよび関連する知覚タスクにとって重要なマイルストーンとなるものと確信しています。モデルのバージョン、データセット、およびインタラクティブなデモを公開します。

ヒント:

Batch & Video Support: SAM2 はバッチ処理とシームレスな動画セグメンテーションをネイティブでサポートする一方、オリジナルの SAM は静的な画像と、1枚ずつ処理するシンプルなワークフロー向けに設計されています。
Accuracy & Generalization: SAM2は、元のSAMと比較して、特に混合プロンプトを使用した場合に、セグメンテーションの品質、ロバストネス、および新しいドメインへのゼロショット汎化性能が向上しています。

このモデルは、sangbumchoi と yonigozlan によって提供されました。元のコードはこちらで確認できます。

使用例

Video Segmentation and Tracking

SAM2の最大の強みは、動画フレーム間でオブジェクトを追跡できる点です。動画セグメンテーションにSAM2を使用する方法は以下の通りです。

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

from transformers import Sam2VideoModel, Sam2VideoProcessor
import torch

model = Sam2VideoModel.from_pretrained("facebook/sam2.1-hiera-tiny", device_map="auto")
processor = Sam2VideoProcessor.from_pretrained("facebook/sam2.1-hiera-tiny")

# 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, 480, 854])

# 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 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
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 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 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

ストリーミング動画推論

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

# 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}")

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

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

# 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 180 frames

リソース

SAMの入門を支援するための、Hugging Face公式およびコミュニティ（🌎で示す）のリソースのリストです。

Demo notebook 🌎は、Sangbum Choi 氏によって提供された、このモデルの使用方法を示すノートブックです。

Transformers

SAM2 Video

概要

使用例

Video Segmentation and Tracking

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

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

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

ストリーミング動画推論

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

リソース

Sam2VideoConfig

class transformers.Sam2VideoConfig

Sam2VideoMaskDecoderConfig

クラス transformers.Sam2VideoMaskDecoderConfig

Sam2VideoPromptEncoderConfig

class transformers.Sam2VideoPromptEncoderConfig

Sam2VideoProcessor

class transformers.Sam2VideoProcessor

__call__

post_process_masks

init_video_session

add_inputs_to_inference_session

Sam2VideoVideoProcessor

class transformers.Sam2VideoVideoProcessor

post_process_masks

Sam2VideoInferenceSession

class transformers.Sam2VideoInferenceSession

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

Sam2VideoModel

class transformers.Sam2VideoModel

forward

propagate_in_video_iterator

get_image_features

call