Transformers documentation
SAM3 Tracker
このモデルは2025年11月19日にHugging Face Transformersに貢献されました。
SAM3 Tracker
概要
SAM3 (Segment Anything Model 3) は、SAM 3: Segment Anything with Concepts で紹介されました。
Sam3Trackerは画像に対してPromptable Visual Segmentation (PVS)を実行します。PVSでは、インタラクティブなビジュアルプロンプト（点、ボックス、マスク）またはテキスト入力を指定することで、プロンプトごとに特定のオブジェクトインスタンスをセグメンテーションします。これはSAM 1とSAM 2が焦点を当てていたタスクであり、SAM 3ではその点において改善が加えられています。
Sam3Trackerは、SAM2（Segment Anything Model 2）の更新版であり、同じ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 氏によって提供されました。
使用例
Pipelineによる自動マスク生成
Sam3Trackerは、mask-generationパイプラインを使用して画像内のすべてのオブジェクトをセグメントするための自動マスク生成に使用できます。
from transformers import pipeline
generator = pipeline("mask-generation", model="facebook/sam3", device=0)
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
outputs = generator(image_url, points_per_batch=64)
len(outputs["masks"]) # Number of masks generated
39基本的な画像セグメンテーション
単一ポイントクリック
オブジェクトをセグメントするには、セグメントしたいオブジェクトに1回クリックするだけで分割できます:
from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests
model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
raw_image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")
input_points = [[[[500, 375]]]] # Single point click, 4 dimensions (image_dim, object_dim, point_per_object_dim, coordinates)
input_labels = [[[1]]] # 1 for positive click, 0 for negative click, 3 dimensions (image_dim, object_dim, point_label)
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
# The model outputs multiple mask predictions ranked by quality score
print(f"Generated {masks.shape[1]} masks with shape {masks.shape}")
Generated 3 masks with shape torch.Size([1, 3, 1500, 2250])改善のための複数のポイント
セグメンテーションを微調整するために、複数の点を指定できます。
# Add both positive and negative points to refine the mask
input_points = [[[[500, 375], [1125, 625]]]] # Multiple points for refinement
input_labels = [[[1, 1]]] # Both positive clicks
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]バウンディングボックス入力
Sam3Tracker は、セグメンテーション用のバウンディングボックス入力もサポートしています:
# Define bounding box as [x_min, y_min, x_max, y_max]
input_boxes = [[[75, 275, 1725, 850]]]
inputs = processor(images=raw_image, input_boxes=input_boxes, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]複数オブジェクトのセグメンテーション
複数のオブジェクトを同時にセグメンテーションできます:
# Define points for two different objects
input_points = [[[[500, 375]], [[650, 750]]]] # Points for two objects in same image
input_labels = [[[1], [1]]] # Positive clicks for both objects
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
# Each object gets its own mask
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
print(f"Generated masks for {masks.shape[0]} objects")
Generated masks for 2 objectsバッチ推論
バッチ化された画像
効率を向上させるために、複数の画像を同時に処理します:
from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests
model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")
# Load multiple images
image_urls = [
"https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
"https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dog_sam.png"
]
raw_images = [Image.open(requests.get(url, stream=True).raw).convert("RGB") for url in image_urls]
# Single point per image
input_points = [[[[500, 375]]], [[[770, 200]]]] # One point for each image
input_labels = [[[1]], [[1]]] # Positive clicks for both images
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
# Post-process masks for each image
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(all_masks)} images, each with {all_masks[0].shape[0]} objects")
Processed 2 images, each with 1 objects画像ごとのバッチ化されたオブジェクト
バッチ推論を使用して、各画像内の複数のオブジェクトをセグメントします:
# Multiple objects per image - different numbers of objects per image
input_points = [
[[[500, 375]], [[650, 750]]], # Truck image: 2 objects
[[[770, 200]]] # Dog image: 1 object
]
input_labels = [
[[1], [1]], # Truck image: positive clicks for both objects
[[1]] # Dog image: positive click for the object
]
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])バッチ化された画像とバッチ化されたオブジェクト、および複数のポイント
1つのオブジェクトに複数の点を含む複雑なバッチシナリオを処理します:
# Add groceries image for more complex example
groceries_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/groceries.jpg"
groceries_image = Image.open(requests.get(groceries_url, stream=True).raw).convert("RGB")
raw_images = [raw_images[0], groceries_image] # Use truck and groceries images
# Complex batching: multiple images, multiple objects, multiple points per object
input_points = [
[[[500, 375]], [[650, 750]]], # Truck image: 2 objects with 1 point each
[[[400, 300]], [[630, 300], [550, 300]]] # Groceries image: obj1 has 1 point, obj2 has 2 points
]
input_labels = [
[[1], [1]], # Truck image: positive clicks
[[1], [1, 1]] # Groceries image: positive clicks for refinement
]
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])バッチ化されたバウンディングボックス
バウンディングボックス入力で複数の画像を処理します:
# Multiple bounding boxes per image (using truck and groceries images)
input_boxes = [
[[75, 275, 1725, 850], [425, 600, 700, 875], [1375, 550, 1650, 800], [1240, 675, 1400, 750]], # Truck image: 4 boxes
[[450, 170, 520, 350], [350, 190, 450, 350], [500, 170, 580, 350], [580, 170, 640, 350]] # Groceries image: 4 boxes
]
# Update images for this example
raw_images = [raw_images[0], groceries_image] # truck and groceries
inputs = processor(images=raw_images, input_boxes=input_boxes, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(input_boxes)} images with {len(input_boxes[0])} and {len(input_boxes[1])} boxes respectively")
Processed 2 images with 4 and 4 boxes respectively以前のマスクを入力として使用
Sam3Tracker は、前回の予測から得られたマスクを入力として使用して、セグメンテーションを精緻化できます:
# Get initial segmentation
input_points = [[[[500, 375]]]]
input_labels = [[[1]]]
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
# Use the best mask as input for refinement
mask_input = outputs.pred_masks[:, :, torch.argmax(outputs.iou_scores.squeeze())]
# Add additional points with the mask input
new_input_points = [[[[500, 375], [450, 300]]]]
new_input_labels = [[[1, 1]]]
inputs = processor(
input_points=new_input_points,
input_labels=new_input_labels,
original_sizes=inputs["original_sizes"],
return_tensors="pt",
).to(model.device)
with torch.no_grad():
refined_outputs = model(
**inputs,
input_masks=mask_input,
image_embeddings=outputs.image_embeddings,
multimask_output=False,
)Sam3TrackerConfig
クラス transformers.Sam3TrackerConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02 )
パラメータ
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig]、任意) — ビジョンバックボーンの config オブジェクトまたは辞書です。 - prompt_encoder_config (Union[
dict,Sam3TrackerPromptEncoderConfig], 省略可) — Sam3TrackerPromptEncoderConfig を初期化するために使用される設定オプションの辞書。 - mask_decoder_config (Union[
dict,Sam3TrackerMaskDecoderConfig], 省略可) — Sam3TrackerMaskDecoderConfigを初期化するために使用される設定オプションの辞書。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。
これは Sam3TrackerModel の設定を保存するための設定クラスです。指定された引数に基づいて Sam3 Tracker モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、facebook/sam3 と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import (
... Sam3TrackerVisionConfig,
... Sam3TrackerPromptEncoderConfig,
... Sam3TrackerMaskDecoderConfig,
... Sam3TrackerModel,
... )
>>> # Initializing a Sam3TrackerConfig with `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> configuration = Sam3TrackerConfig()
>>> # Initializing a Sam3TrackerModel (with random weights) from the `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> model = Sam3TrackerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config
>>> # We can also initialize a Sam3TrackerConfig from a Sam3TrackerVisionConfig, Sam3TrackerPromptEncoderConfig, and Sam3TrackerMaskDecoderConfig
>>> # Initializing SAM3_TRACKER vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVisionConfig()
>>> prompt_encoder_config = Sam3TrackerPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerMaskDecoderConfig()
>>> config = Sam3TrackerConfig(vision_config, prompt_encoder_config, mask_decoder_config)Sam3TrackerPromptEncoderConfig
class transformers.Sam3TrackerPromptEncoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256image_size: int | list[int] | tuple[int, int] = 1008patch_size: int | list[int] | tuple[int, int] = 14mask_input_channels: int = 16num_point_embeddings: int = 4hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06scale: int = 1 )
パラメータ
- hidden_size (
int、任意、デフォルトは256) — 隠れ表現の次元数。 - image_size (
Union[int, list[int], tuple[int, int]]、任意、デフォルトは1008) — 各画像のサイズ（解像度）。 - patch_size (
Union[int, list[int], tuple[int, int]]、任意、デフォルトは14) — 各パッチのサイズ（解像度）です。 - mask_input_channels (
int、任意、デフォルトは 16)—MaskDecoderモジュールに渡すチャネル数です。 - num_point_embeddings (
int、任意、デフォルトは 4) — 使用する point embeddings の数です。 - hidden_act (
str、任意、デフォルトはgelu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、"relu"、"silu"など。 - layer_norm_eps (
float、任意、デフォルトは1e-06) — レイヤーノーマル層で使用する epsilon です。 - scale (
float、任意、デフォルトは 1) — プロンプトエンコーダーのスケール係数です。
This is the configuration class to store the configuration of a Sam3TrackerModel. It is used to instantiate a Sam3 Tracker model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the facebook/sam3
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
Sam3TrackerMaskDecoderConfig
class transformers.Sam3TrackerMaskDecoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256hidden_act: str = 'gelu'mlp_dim: int = 2048num_hidden_layers: int = 2num_attention_heads: int = 8attention_downsample_rate: int = 2num_multimask_outputs: int = 3iou_head_depth: int = 3iou_head_hidden_dim: int = 256dynamic_multimask_via_stability: bool = Truedynamic_multimask_stability_delta: float = 0.05dynamic_multimask_stability_thresh: float = 0.98 )
パラメータ
- hidden_size (
int、任意、デフォルトは256) — 隠れ表現の次元数。 - hidden_act (
str、任意、デフォルトはgelu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、"relu"、"silu"など。 - mlp_dim (
int、任意、デフォルトは 2048) — 2 方向 Transformer における MLP の次元数です。 - num_hidden_layers (
int、任意、デフォルトは2) — Transformerデコーダーの隠れ層の数。 - num_attention_heads (
int、任意、デフォルトは8) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 - attention_downsample_rate (
int、任意、デフォルトは 2) — アテンション層のダウンサンプル率です。 - num_multimask_outputs (
int、任意、デフォルトは 3) — マルチマスク出力の数です。 - iou_head_depth (
int、任意、デフォルト値は 3) — IoU ヘッドの深さです。 - iou_head_hidden_dim (
int、任意、デフォルトは 256) — IoU ヘッドの隠れ層の次元数です。 - dynamic_multimask_via_stability (
bool、省略可、デフォルトはTrue) — stability を用いた動的マルチマスクを使用するかどうかを指定します。 - dynamic_multimask_stability_delta (
float、任意、デフォルト値は 0.05) — 動的マルチマスクの安定性デルタです。 - dynamic_multimask_stability_thresh (
float、任意、デフォルト値は 0.98) — 動的マルチマスクの安定性しきい値です。
これは Sam3TrackerModel の設定を保存するための設定クラスです。指定された引数に基づいて Sam3 Tracker モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、facebook/sam3 と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
Sam3TrackerProcessor
class transformers.Sam3TrackerProcessor
< source >( image_processortarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )
パラメータ
- image_processor (
Sam3ImageProcessor) — 画像プロセッサは必須の入力です。 - target_size (
int, 任意) — 入力ポイントとバウンディングボックスを正規化するためのターゲットサイズ（ピクセル単位）です。指定されない場合、デフォルトでは画像プロセッサのサイズ設定が使用されます。すべての入力座標（ポイントとボックス）は、モデルに渡される前にこのサイズに正規化されます。これにより、元の画像の寸法に関係なく、座標の表現が常に一貫したものになります。 - point_pad_value (
int、任意、デフォルトは -10) — 長さの異なるシーケンスをバッチ処理する際に、入力ポイントのパディングに使用される値です。この値はパディングされた位置をマークするために使用され、座標正規化の間も保持されます。
画像プロセッサーを単一のプロセッサーにラップするSam3TrackerProcessorを構築します。
Sam3TrackerProcessor は Sam3ImageProcessor のすべての機能を提供します。詳細については、~Sam3ImageProcessor を参照してください。
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonesegmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Noneinput_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = Noneinput_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = Noneinput_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = Noneoriginal_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs ) → A BatchEncoding with the following fields
パラメータ
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 任意) — 前処理対象の画像です。ピクセル値が 0 から 255 の範囲にある単一の画像またはバッチを想定しています。ピクセル値が 0 から 1 の範囲にある画像を渡す場合は、do_rescale=Falseを設定してください。 - segmentation_maps (
ImageInput、任意) — 処理対象のセグメンテーションマップです。 - input_points (
list[list[list[list[float]]]]、torch.Tensor、省略可) — フレームに追加する点です。 - input_labels (
list[list[list[int]]]、torch.Tensor、省略可) — ポイントのラベルです。 - input_boxes (
list[list[list[float]]]、torch.Tensor、省略可) — フレームに追加するバウンディングボックスです。 - original_sizes (
list[list[float]]、torch.Tensor、省略可) — 画像の元のサイズです。 - return_tensors (
Union[str, ~utils.generic.TensorType], 省略可能) — 設定すると、特定のフレームワークのテンソルを返します。受け入れられる値は以下の通りです:'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': NumPyのnp.ndarrayオブジェクトを返します。
戻り値
以下のフィールドを持つBatchEncoding
pixel_values(torch.Tensor): 処理された画像。original_sizes(list[list[float]]): 画像の元のサイズ。labels(torch.Tensor): 処理済みのセグメンテーションマップ（指定されている場合）。input_points(torch.Tensor): 処理済みのポイント。input_labels(torch.Tensor): 処理済みのラベル。input_boxes(torch.Tensor): 処理済みのバウンディングボックス。
post_process_masks
< source >( masksoriginal_sizesmask_threshold = 0.0binarize = Truemax_hole_area = 0.0max_sprinkle_area = 0.0apply_non_overlapping_constraints = False**kwargs ) → (torch.Tensor)
パラメータ
- masks (
Union[List[torch.Tensor], List[np.ndarray]]) — mask_decoder からのバッチ化されたマスク。形式は (batch_size, num_channels, height, width) です。 - original_sizes (
Union[torch.Tensor, List[Tuple[int,int]]]) — モデルが期待する入力形状にリサイズされる前の、各画像の元のサイズです。形式は (高さ, 幅) です。 - mask_threshold (
float、任意、デフォルト値は 0.0) — 二値化および後処理操作の閾値。 - binarize (
bool、省略可能、デフォルトはTrue) — マスクをバイナリ化するかどうかを指定します。 - max_hole_area (
float、任意、デフォルト値は 0.0)— 埋める穴の最大面積です。 - max_sprinkle_area (
float、任意、デフォルト値は 0.0) — 塗りつぶす sprinkle の最大面積です。 - apply_non_overlapping_constraints (
bool、省略可能、デフォルトはFalse) — マスクに非重複制約を適用するかどうか。
戻り値
(torch.Tensor)
batch_size, num_channels, height, width形式のバッチ化されたマスク。ここで、(height, width)はoriginal_sizeによって指定されます。
パディングを除去し、マスクを元の画像サイズにアップスケールします。
Sam3TrackerModel
class transformers.Sam3TrackerModel
< source >( config: Sam3TrackerConfig )
パラメータ
- config (Sam3TrackerConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
入力画像と、入力ポイントおよびラベル、ボックス、またはマスクを指定してセグメンテーションマスクを生成するためのSegment Anything Model 2 (SAM 2)。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( pixel_values: typing.Optional[torch.FloatTensor] = Noneinput_points: typing.Optional[torch.FloatTensor] = Noneinput_labels: typing.Optional[torch.LongTensor] = Noneinput_boxes: typing.Optional[torch.FloatTensor] = Noneinput_masks: typing.Optional[torch.LongTensor] = Noneimage_embeddings: typing.Optional[torch.FloatTensor] = Nonemultimask_output: bool = Trueattention_similarity: typing.Optional[torch.FloatTensor] = Nonetarget_embedding: typing.Optional[torch.FloatTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerImageSegmentationOutput or tuple(torch.FloatTensor)
パラメータ
- pixel_values (
torch.FloatTensor、形状(batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値は Sam3ImageProcessor を使用して取得できます。詳細は Sam3ImageProcessor.call() を参照してください（Sam3TrackerProcessor は画像の処理に Sam3ImageProcessor を使用します）。 - input_points (
torch.FloatTensor、shape(batch_size, num_points, 2)) — 入力となる 2 次元空間上の点です。プロンプトエンコーダがプロンプトをエンコードするために使用されます。一般的に、これによりはるかに良い結果が得られます。点は、リストのリストのリストをプロセッサに渡すことで取得でき、これにより次元 4 の対応するtorchテンソルが作成されます。最初の次元は画像のバッチサイズ、2 番目の次元は点のバッチサイズ（つまり、入力点ごとにモデルに予測させたいセグメンテーションマスクの数）、3 番目の次元はセグメンテーションマスクごとの点の数（1 つのマスクに対して複数の点を渡すことも可能です）、最後の次元は点の x（縦）および y（横）座標です。画像ごと、またはマスクごとに異なる数の点が渡された場合、プロセッサは (0, 0) 座標に対応する「PAD」点を作成し、これらの点についてはラベルを使用して埋め込みの計算をスキップします。 - input_labels (
torch.LongTensorの形状(batch_size, point_batch_size, num_points)) — ポイントの入力ラベルです。プロンプトエンコーダーによってプロンプトをエンコードするために使用されます。公式実装によると、ラベルには 3 種類あります1: 対象オブジェクトを含む点0: 対象オブジェクトを含まない点-1: 背景に対応する点
ラベルを追加しました:
-10: その点はパディングポイントであるため、プロンプトエンコーダーによって無視されるべきです
パディングラベルは、プロセッサによって自動的に処理されるべきです。
- input_boxes (
torch.FloatTensorの形状(batch_size, num_boxes, 4)) — ポイント用の入力ボックスです。プロンプトエンコーダーによってプロンプトをエンコードするために使用されます。一般的に、より優れた生成マスクが得られます。ボックスは、リストのリストのリストをプロセッサーに渡すことで取得でき、torchテンソルが生成されます。各次元は、それぞれ画像のバッチサイズ、画像ごとのボックス数、およびボックスの左上と右下の点の座標に対応します。順序は (x1,y1,x2,y2):x1: 入力ボックスの左上の点のx座標y1: 入力ボックスの左上の点のy座標x2: 入力ボックスの右下の点のx座標y2: 入力ボックスの右下隅の y 座標
- input_masks (
torch.FloatTensor、shape(batch_size, image_size, image_size)) — SAM モデルは、セグメンテーションマスクも入力として受け入れます。マスクはプロンプトエンコーダーによって埋め込まれ、対応する埋め込みが生成されます。この埋め込みは、後でマスクデコーダーに渡されます。これらのマスクはユーザーが手動で渡す必要があり、shape は (batch_size,image_size,image_size) である必要があります。 - image_embeddings (
torch.FloatTensor、shape(batch_size, output_channels, window_size, window_size)) — 画像の埋め込みです。マスクデコーダーがマスクと IoU スコアを生成するために使用されます。よりメモリ効率の高い計算を行うには、まずget_image_embeddingsメソッドで画像の埋め込みを取得し、pixel_valuesを渡す代わりに、それをforwardメソッドに渡すことができます。 - multimask_output (
bool, 任意) — 元の実装および論文では、モデルは常に1枚の画像ごとに3つのマスクを出力します（関連する場合は、ポイントごとまたはバウンディングボックスごと）。ただし、multimask_output=Falseを指定することで、「最良」のマスクに相当する単一のマスクのみを出力することも可能です。 - attention_similarity (
torch.FloatTensor, 任意) — ターゲットガイドドアテンションのためにマスクデコーダーに渡すアテンション類似度テンソル。モデルがPerSAMで導入されたパーソナライゼーションに使用される場合に指定します。 - target_embedding (
torch.FloatTensor, 任意) — ターゲット概念の埋め込み。モデルがPerSAMで導入されたパーソナライゼーションに使用される場合、ターゲット意味プロンプティングのためにマスクデコーダーに提供されます。
戻り値
Sam3TrackerImageSegmentationOutput または tuple(torch.FloatTensor)
Sam3TrackerImageSegmentationOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Sam3TrackerConfig）や入力に応じて、さまざまな要素で構成されます。
Sam3TrackerModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- iou_scores (
torch.FloatTensor、shape(batch_size, point_batch_size, num_masks)) — 予測されたマスクの Intersection over Union (IoU) スコア。 - pred_masks (
torch.FloatTensor、shape(batch_size, point_batch_size, num_masks, height, width)) — 予測された低解像度マスクです。これはlow_res_masksの別名です。これらのマスクは、プロセッサによって後処理を行うことで、元の画像サイズに拡大する必要があります。 - object_score_logits (
torch.FloatTensor、shape(batch_size, point_batch_size, 1)) — オブジェクトが存在するかどうかを示す、オブジェクトスコアの logits。 - image_embeddings (
tuple(torch.FloatTensor)) — FPN からの特徴量であり、マスクデコーダーで使用されます。これはtorch.FloatTensorのタプルで、各テンソルの形状は(batch_size, channels, height, width)です。 - vision_hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueの場合のみ返却) — 各ステージの出力に対応するtorch.FloatTensorのタプルで、形状は(batch_size, height, width, hidden_size)です。 各ステージの出力におけるビジョンモデルの隠れ状態です。 - vision_attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueの場合のみ返却) —torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。 ビジョンモデルのアテンション重み。 - mask_decoder_attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueの場合のみ返却) —torch.FloatTensorのタプル（各レイヤーごとに1つ）。形状は(batch_size, num_heads, sequence_length, sequence_length)です。 マスクデコーダーの注意重みです。
例:
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor
>>> model = AutoModel.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")
>>> processor = AutoProcessor.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")
>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
... raw_image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]] # 2D location of a window on the car
>>> inputs = processor(images=raw_image, input_points=input_points, return_tensors="pt")
>>> # Get segmentation mask
>>> outputs = model(**inputs)
>>> # Postprocess masks
>>> masks = processor.post_process_masks(
... outputs.pred_masks, inputs["original_sizes"]
... )get_image_features
< source >( pixel_values: FloatTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerVisionEncoderOutput or tuple(torch.FloatTensor)
パラメータ
戻り値
Sam3TrackerVisionEncoderOutput または tuple(torch.FloatTensor)
Sam3TrackerVisionEncoderOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（Sam3TrackerConfig）や入力に応じて、さまざまな要素で構成されます。
last_hidden_state (
torch.FloatTensor、shape(batch_size, height, width, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。pooler_output (
torch.FloatTensor、shape(batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測（分類）目的から学習されます。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
fpn_hidden_states (
tuple(torch.FloatTensor)) — 各特徴レベル（高解像度から低解像度へ）に対応するtorch.FloatTensorのタプルで、形状は(batch_size, hidden_size, height, width)です。Feature Pyramid Network のネック部からの特徴マップです。fpn_position_encoding (
tuple(torch.FloatTensor)) —torch.FloatTensorのタプル（解像度が高い順に各フィーチャーレベル分）。形状は(batch_size, hidden_size, height, width)。fpn_hidden_statesに対応する位置エンコーディングです。
Sam3TrackerPreTrainedModel
class transformers.Sam3TrackerPreTrainedModel
< source >( config: PreTrainedConfig*inputs**kwargs )
パラメータ
- config (PreTrainedConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
入力画像と、入力となる点とラベル、ボックス、またはマスクを指定してセグメンテーションマスクを生成するためのSegment Anything Model 3 (SAM 3)。