# EdgeTAM

## 概要

EdgeTAMモデルは、[EdgeTAM: On-Device Track Anything Model](https://huggingface.co/papers/2501.07256) Chong Zhou, Chenchen Zhu, Yunyang Xiong, Saksham Suri, Fanyi Xiao, Lemeng Wu, Raghuraman Krishnamoorthi, Bo Dai, Chen Change Loy, Vikas Chandra, Bilge Soran. で提案されました。

EdgeTAMは、モバイルデバイスでのリアルタイム動画セグメンテーションにおいてメモリ注意機構を最適化するために2D Spatial Perceiverアーキテクチャを導入した、SAM 2の効率的な適応版です。

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

*Segment Anything Model (SAM)を基盤とするSAM 2は、メモリバンク機構を通じてその能力を画像入力から動画入力へとさらに拡張し、従来の手法と比較して顕著な性能を達成したことで、動画セグメンテーションタスクの基盤モデルとなっています。本論文では、SAM 2を大幅に効率化し、同等の性能を維持しながらもモバイルデバイス上で動作させることを目指しています。SAMの効率化を最適化した複数の先行研究が存在しますが、これらはすべて画像エンコーダーの圧縮に焦点を当てているため、SAM 2には不十分であることが判明しました。私たちのベンチマークでは、新たに導入されたメモリアテンションブロックもまたレイテンシのボトルネックであることが示されています。この観察に基づき、計算コストを削減するために新しい2D Spatial Perceiverを活用するEdgeTAMを提案します。具体的には、提案する2D Spatial Perceiverは、固定された学習可能なクエリのセットを含む軽量なTransformerを用いて、高密度に保存されたフレームレベルのメモリをエンコードします。動画セグメンテーションは高密度予測タスクであるため、クエリをグローバルレベルとパッチレベルのグループに分割することで、メモリの空間構造を保持することが不可欠であると判明しました。さらに、推論時のオーバーヘッドなしで性能をさらに向上させる蒸留パイプラインも提案します。その結果、EdgeTAMはDAVIS 2017、MOSE、SA-V val、SA-V testでそれぞれ87.7、70.0、72.3、71.7のJ&Fを達成し、iPhone 15 Pro Max上で16 FPSで動作します。*

このモデルは [yonigozlan](https://huggingface.co/yonigozlan) によって提供されました。元のコードは [こちら](https://github.com/facebookresearch/EdgeTAM) で確認できます。

## 使用例

### Pipelineによる自動マスク生成

EdgeTAMは、`mask-generation`パイプラインを使用して画像内のすべてのオブジェクトをセグメントするための自動マスク生成に使用できます:

```python
from transformers import pipeline

generator = pipeline("mask-generation", model="yonigozlan/edgetam-1", 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回クリックするだけで分割できます:

```python
from transformers import Sam2Processor, EdgeTamModel
import torch
from PIL import Image
import requests

model = EdgeTamModel.from_pretrained("yonigozlan/edgetam-1", device_map="auto")
processor = Sam2Processor.from_pretrained("yonigozlan/edgetam-1")

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, 1200, 1800])
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.0463, 0.4859, 0.7616], device='cuda:0')
```

#### 改善のための複数のポイント

セグメンテーションを微調整するために、複数の点を指定できます。

```python
# 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]
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.8362, 0.6900, 0.2120], device='cuda:0')
```

#### バウンディングボックス入力

EdgeTAMは、セグメンテーション用のバウンディングボックス入力もサポートしています:

```python
# 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]
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.9301, 0.9348, 0.6605], device='cuda:0')
```

#### 複数オブジェクトのセグメンテーション

複数のオブジェクトを同時にセグメンテーションできます:

```python
# 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
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.7616, 0.9465], device='cuda:0')
```

### バッチ推論

#### バッチ化された画像

効率を向上させるために、複数の画像を同時に処理します:

```python
from transformers import Sam2Processor, EdgeTamModel
import torch
from PIL import Image
import requests

model = EdgeTamModel.from_pretrained("yonigozlan/edgetam-1", device_map="auto")
processor = Sam2Processor.from_pretrained("yonigozlan/edgetam-1")

# 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
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.7618, 0.7999], device='cuda:0')
```

#### 画像ごとのバッチ化されたオブジェクト

バッチ推論を使用して、各画像内の複数のオブジェクトをセグメントします:

```python
# 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つのオブジェクトに複数の点を含む複雑なバッチシナリオを処理します:

```python
# 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"])
```

#### バッチ化されたバウンディングボックス

バウンディングボックス入力で複数の画像を処理します:

```python
# 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
print(f"IoU scores: {outputs.iou_scores.squeeze()}")
IoU scores: tensor([0.9301, 0.9348, 0.6605, 0.9465], device='cuda:0')
```

### 以前のマスクを入力として使用

EdgeTAM は、以前の予測から得られたマスクを入力として使用して、セグメンテーションを精緻化できます:

```python
# 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,
    )
```

## EdgeTamConfig[[transformers.EdgeTamConfig]]

#### transformers.EdgeTamConfig[[transformers.EdgeTamConfig]]

```python
transformers.EdgeTamConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/configuration_edgetam.py#L152)

**パラメータ:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : ビジョンバックボーンの config オブジェクトまたは辞書。

prompt_encoder_config `dict`、`EdgeTamPromptEncoderConfig` の Union 型（*optional*）: [EdgeTamPromptEncoderConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamPromptEncoderConfig) を初期化するために使用される設定オプションの辞書。

mask_decoder_config (Union[`dict`, `EdgeTamMaskDecoderConfig`], *optional*) : [EdgeTamMaskDecoderConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamMaskDecoderConfig)を初期化するために使用される設定オプションの辞書。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

これはEdgeTamModelの設定を保存するための設定クラスです。指定された引数に基づいてEdgetamモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[yonigozlan/EdgeTAM-hf](https://huggingface.co/yonigozlan/EdgeTAM-hf) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import (
...     EdgeTamVisionConfig,
...     EdgeTamPromptEncoderConfig,
...     EdgeTamMaskDecoderConfig,
...     EdgeTamModel,
... )

>>> # Initializing a EdgeTamConfig with `"facebook/edgetam.1_hiera_tiny"` style configuration
>>> configuration = EdgeTamConfig()

>>> # Initializing a EdgeTamModel (with random weights) from the `"facebook/edgetam.1_hiera_tiny"` style configuration
>>> model = EdgeTamModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

>>> # We can also initialize a EdgeTamConfig from a EdgeTamVisionConfig, EdgeTamPromptEncoderConfig, and EdgeTamMaskDecoderConfig
>>> # Initializing EDGETAM vision encoder, memory attention, and memory encoder configurations
>>> vision_config = EdgeTamVisionConfig()
>>> prompt_encoder_config = EdgeTamPromptEncoderConfig()
>>> mask_decoder_config = EdgeTamMaskDecoderConfig()

>>> config = EdgeTamConfig(vision_config, prompt_encoder_config, mask_decoder_config)
```

## EdgeTamVisionConfig[[transformers.EdgeTamVisionConfig]]

#### transformers.EdgeTamVisionConfig[[transformers.EdgeTamVisionConfig]]

```python
transformers.EdgeTamVisionConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, backbone_channel_list: list[int] | None = None, backbone_feature_sizes: list | None = None, fpn_hidden_size: int = 256, fpn_kernel_size: int = 1, fpn_stride: int = 1, fpn_padding: int = 0, fpn_top_down_levels: list[int] | None = None, num_feature_levels: int = 3, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, initializer_range: float = 0.02)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/configuration_edgetam.py#L29)

**パラメータ:**

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`、*optional*) : バックボーンモデルの設定です。

backbone_channel_list (`List[int]`、*optional*、デフォルトは`[384, 192, 96, 48]`) : バックボーンのチャネル次元のリストです。

backbone_feature_sizes (`List[List[int]]`、*任意*、デフォルトは `[[256, 256], [128, 128], [64, 64]]`) : バックボーンからの特徴マップの空間サイズです。

fpn_hidden_size (`int`、*optional*、デフォルトは 256) : FPN の隠れ層の次元数。

fpn_kernel_size (`int`、*optional*、デフォルトは 1) : neck 内の畳み込みのカーネルサイズです。

fpn_stride (`int`、*optional*、デフォルトは 1) : neck における畳み込みのストライドです。

fpn_padding (`int`、*任意*、デフォルトは 0) : neck 内の畳み込みの padding です。

fpn_top_down_levels (`List[int]`、*optional*、デフォルトは`[2, 3]`) : トップダウン FPN 接続のレベル。

num_feature_levels (`int`、*任意*、デフォルトは 3) : FPN から使用する特徴量レベルの数。

hidden_act (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

layer_norm_eps (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

これはEdgeTamModelの設定を保存するための設定クラスです。指定された引数に基づいてEdgetamモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[yonigozlan/EdgeTAM-hf](https://huggingface.co/yonigozlan/EdgeTAM-hf) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

## EdgeTamMaskDecoderConfig[[transformers.EdgeTamMaskDecoderConfig]]

#### transformers.EdgeTamMaskDecoderConfig[[transformers.EdgeTamMaskDecoderConfig]]

```python
transformers.EdgeTamMaskDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, hidden_act: str = 'gelu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, dynamic_multimask_via_stability: bool = True, dynamic_multimask_stability_delta: float = 0.05, dynamic_multimask_stability_thresh: float = 0.98)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/configuration_edgetam.py#L113)

**パラメータ:**

hidden_size (`int`、*任意*、デフォルトは`256`) : 隠れ表現の次元数。

hidden_act (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

mlp_dim (`int`、*optional*、デフォルトは 2048) : 2-way transformer における MLP の次元数。

num_hidden_layers (`int`、*任意*、デフォルトは `2`) : Transformer デコーダーの隠れ層の数。

num_attention_heads (`int`、*任意*、デフォルトは `8`) : Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。

attention_downsample_rate (`int`、*optional*、デフォルトは 2) : アテンション層のダウンサンプル率です。

num_multimask_outputs (`int`、*任意*、デフォルトは 3) : マルチマスク出力の数。

iou_head_depth (`int`、*optional*、デフォルトは 3) : IoU ヘッドの深さ。

iou_head_hidden_dim (`int`、*optional*、デフォルトは 256) : IoU ヘッドの隠れ次元です。

dynamic_multimask_via_stability (`bool`、*任意*、デフォルトは `True`) : stability を用いた動的マルチマスクを使用するかどうか。

dynamic_multimask_stability_delta (`float`、*任意*、デフォルトは 0.05) : 動的マルチマスクの安定性デルタです。

dynamic_multimask_stability_thresh (`float`、*任意*、デフォルト値は 0.98) : 動的マルチマスクの安定性しきい値です。

これはEdgeTamModelの設定を保存するための設定クラスです。指定された引数に基づいてEdgetamモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[yonigozlan/EdgeTAM-hf](https://huggingface.co/yonigozlan/EdgeTAM-hf) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

## EdgeTamPromptEncoderConfig[[transformers.EdgeTamPromptEncoderConfig]]

#### transformers.EdgeTamPromptEncoderConfig[[transformers.EdgeTamPromptEncoderConfig]]

```python
transformers.EdgeTamPromptEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, scale: int = 1)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/configuration_edgetam.py#L88)

**パラメータ:**

hidden_size (`int`、*任意*、デフォルトは`256`) : 隠れ表現の次元数。

image_size (`Union[int, list[int], tuple[int, int]]`、*任意*、デフォルトは`1024`) : 各画像のサイズ（解像度）。

patch_size (`Union[int, list[int], tuple[int, int]]`、*任意*、デフォルトは`16`) : 各パッチのサイズ（解像度）。

mask_input_channels (`int`、*任意*、デフォルトは 16) : `MaskDecoder` モジュールに渡すチャネル数です。

num_point_embeddings (`int`、*任意*、デフォルトは 4) : 使用するポイント埋め込みの数。

hidden_act (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

layer_norm_eps (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。

scale (`float`、*任意*、デフォルトは 1) : プロンプトエンコーダーのスケール係数です。

これはEdgeTamModelの設定を保存するための設定クラスです。指定された引数に基づいてEdgetamモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[yonigozlan/EdgeTAM-hf](https://huggingface.co/yonigozlan/EdgeTAM-hf) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

## EdgeTamVisionModel[[transformers.EdgeTamVisionModel]]

#### transformers.EdgeTamVisionModel[[transformers.EdgeTamVisionModel]]

```python
transformers.EdgeTamVisionModel(config: EdgeTamVisionConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/modeling_edgetam.py#L452)

**パラメータ:**

config ([EdgeTamVisionConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamVisionConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。

ヘッドや投影が一切付加されていない、EdgeTAMのビジョンモデルです。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

#### forward[[transformers.EdgeTamVisionModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.FloatTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/modeling_edgetam.py#L470)

## EdgeTamModel[[transformers.EdgeTamModel]]

#### transformers.EdgeTamModel[[transformers.EdgeTamModel]]

```python
transformers.EdgeTamModel(config: EdgeTamConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/modeling_edgetam.py#L945)

**パラメータ:**

config ([EdgeTamConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。

入力画像と、入力ポイントとラベル、ボックス、またはマスクを指定してセグメンテーションマスクを生成するためのSegment Anything Model 2 (SAM 2)。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

#### forward[[transformers.EdgeTamModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.FloatTensor] = None, input_points: typing.Optional[torch.FloatTensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.FloatTensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.FloatTensor] = None, multimask_output: bool = True, attention_similarity: typing.Optional[torch.FloatTensor] = None, target_embedding: typing.Optional[torch.FloatTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/modeling_edgetam.py#L1051)

**パラメータ:**

pixel_values (`torch.FloatTensor`、shape `(batch_size, num_channels, image_size, image_size)`、*任意*) : 入力画像に対応するテンソルです。ピクセル値は [Sam2ImageProcessor](/docs/transformers/main/ja/model_doc/sam2#transformers.Sam2ImageProcessor) を使用して取得できます。詳細については [Sam2ImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（[Sam2Processor](/docs/transformers/main/ja/model_doc/sam2#transformers.Sam2Processor) は画像の処理に [Sam2ImageProcessor](/docs/transformers/main/ja/model_doc/sam2#transformers.Sam2ImageProcessor) を使用します）。

input_points (`torch.FloatTensor`、shape は `(batch_size, num_points, 2)`) : 入力となる 2 次元空間上の点です。プロンプトエンコーダがこの点を使用してプロンプトをエンコードします。一般的に、これによりはるかに良い結果が得られます。点は、リストのリストのリストをプロセッサに渡すことで取得でき、プロセッサが次元 4 の対応する `torch` テンソルを作成します。最初の次元は画像のバッチサイズ、2 番目の次元は点のバッチサイズ（つまり、1 つの入力点あたりモデルに何つのセグメンテーションマスクを予測させたいか）、3 番目の次元は 1 つのセグメンテーションマスクあたりの点の数（1 つのマスクに対して複数の点を渡すことも可能です）、最後の次元は点の x（縦）および y（横）座標です。画像ごと、またはマスクごとに異なる数の点が渡された場合、プロセッサは (0, 0) 座標に対応する「PAD」点を作成し、これらの点についてはラベルを使用して埋め込みの計算をスキップします。

input_labels (`torch.LongTensor`、shape は `(batch_size, point_batch_size, num_points)`) : ポイントの入力ラベルです。プロンプトエンコーダーがプロンプトをエンコードするために使用されます。公式実装によると、ラベルには 3 種類あります - `1`: 対象オブジェクトを含むポイント - `0`: 対象オブジェクトを含まないポイント - `-1`: 背景に対応するポイント 追加したラベル: - `-10`: パディングポイントであり、プロンプトエンコーダーによって無視されるべきです パディングラベルは、プロセッサーによって自動的に設定される必要があります。

input_boxes (`torch.FloatTensor`、shape `(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つのマスクを出力します（関連する場合は、1ポイントごとまたは1バウンディングボックスごと）。ただし、`multimask_output=False`を指定することで、「最良」のマスクに相当する単一のマスクのみを出力することも可能です。

attention_similarity (`torch.FloatTensor`, *任意*) : 注意度類似度テンソル。モデルが[PerSAM](https://huggingface.co/papers/2305.03048)で導入されたパーソナライゼーションに使用される場合、ターゲットガイドされた注意度のためにマスクデコーダーに提供されます。

target_embedding (`torch.FloatTensor`, *任意*) : ターゲット概念の埋め込み。モデルが[PerSAM](https://huggingface.co/papers/2305.03048)で導入されたパーソナライゼーションに使用される場合、ターゲット意味プロンプティングのためにマスクデコーダーに提供されます。

**戻り値:** `EdgeTamImageSegmentationOutput` または `tuple(torch.FloatTensor)`

`EdgeTamImageSegmentationOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[EdgeTamConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamConfig)）や入力に応じて、さまざまな要素で構成されます。

[EdgeTamModel](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamModel)の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)`。マスクデコーダーのアテンション重みです。

例:

```python
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("danelcsb/edgetam.1_hiera_tiny")
>>> processor = AutoProcessor.from_pretrained("danelcsb/edgetam.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[[transformers.EdgeTamModel.get_image_features]]

```python
get_image_features(pixel_values: FloatTensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/edgetam/modeling_edgetam.py#L1229)

**パラメータ:**

pixel_values (`torch.FloatTensor`) : 形状が `(batch_size, num_channels, height, width)` の入力ピクセル値。

**戻り値:** `EdgeTamVisionEncoderOutput` または `tuple(torch.FloatTensor)`

`EdgeTamVisionEncoderOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[EdgeTamConfig](/docs/transformers/main/ja/model_doc/edgetam#transformers.EdgeTamConfig)）と入力に応じて、さまざまな要素で構成されます。

- **last_hidden_state** (`torch.FloatTensor`、形状 `(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` に対応する位置エンコーディングです。

例:

```python
```