# SAM-HQ

## 概要

SAM-HQ (High-Quality Segment Anything Model) は、Lei Ke、Mingqiao Ye、Martin Danelljan、Yifan Liu、Yu-Wing Tai、Chi-Keung Tang、Fisher Yu によって [Segment Anything in High Quality](https://huggingface.co/papers/2306.01567) で提案されました。

このモデルは、元のSAMモデルの強化版であり、SAMの元のプロンプト可能設計、効率性、ゼロショット汎用性を維持しながら、はるかに高品質なセグメンテーションマスクを生成します。

![example image](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-output.png)

SAM-HQは、元のSAMモデルに対していくつかの重要な改善を導入しています:

1. 高品質な出力トークン: より高品質なマスク予測のためにSAMのマスクデコーダーに注入される学習可能なトークン
2. グローバル・ローカル特徴融合: モデルの異なる段階からの特徴を組み合わせることで、マスクの詳細を改善します
3. 学習データ: SA-1Bではなく、44Kの高品質なマスクからなる慎重にキュレーションされたデータセットを使用します
4. 効率性: マスクの品質を大幅に向上させながら、追加パラメータはわずか0.5%のみ
5. Zero-shot Capability: SAMの強力なゼロショット性能を維持しつつ、精度を向上させます

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

*最近登場した Segment Anything Model (SAM) は、セグメンテーションモデルのスケーリングにおいて大きな飛躍を遂げ、強力なゼロショット機能と柔軟なプロンプティングを可能にしました。11 億個のマスクで訓練されているにもかかわらず、SAM のマスク予測品質は多くの場合で不足しており、特に複雑な構造を持つオブジェクトを扱う際に顕著です。我々は HQ-SAM を提案し、SAM の元のプロンプタブルな設計、効率性、ゼロショット汎化性を維持しながら、任意のオブジェクトを正確にセグメンテーションする機能を SAM に付与します。我々の慎重な設計により、SAM の事前学習済みモデルの重みは再利用・保持され、追加されるパラメータと計算量は最小限に抑えられます。学習可能な High-Quality Output Token を設計し、これを SAM のマスクデコーダに注入することで、高品質なマスクの予測を担当させます。マスクデコーダの特徴量にのみ適用するのではなく、マスクの詳細を向上させるため、まず初期および最終的な ViT 特徴量と融合させます。導入した学習可能なパラメータを訓練するために、複数のソースから 44K の細粒度マスクで構成されるデータセットを作成しました。HQ-SAM はこの 44k マスクのデータセットのみで訓練され、8 つの GPU 上でわずか 4 時間で完了します。*

ヒント:

- SAM-HQ は、元の SAM モデルよりも高品質なマスクを生成します。特に、複雑な構造や細部を持つオブジェクトにおいてその優位性が顕著です。
- モデルは、より正確な境界線と、細い構造のより良い処理により、バイナリマスクを予測します
- SAMと同様に、このモデルは入力として2Dの点および/またはバウンディングボックスを与えることで、より高いパフォーマンスを発揮します。
- 同じ画像に対して複数のポイントをプロンプトとして指定し、1つの高品質なマスクを予測できます
- モデルはSAMのゼロショット汎化能力を維持します
- SAM-HQ は SAM と比べて、パラメータが約 0.5% しか増加しません
- モデルのファインチューニングは現在サポートされていません

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

画像と2次元の点を与えてマスクを生成する方法の例を以下に示します。

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

プロセッサでは、入力画像と並行して独自のマスクも処理し、モデルに渡すことができます。

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
mask_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
segmentation_map = Image.open(requests.get(mask_url, stream=True).raw).convert("1")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, segmentation_maps=segmentation_map, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

## リソース

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

- モデルの使用方法を示すデモノートブック（近日公開予定）
- 論文の実装とコード: [SAM-HQ GitHub リポジトリ](https://github.com/SysCV/SAM-HQ)

## SamHQConfig[[transformers.SamHQConfig]]

#### transformers.SamHQConfig[[transformers.SamHQConfig]]

```python
transformers.SamHQConfig(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, tie_word_embeddings: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L155)

**パラメータ:**

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

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

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

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

tie_word_embeddings (`bool`、*任意*、デフォルトは`True`) : モデルの`tied_weights_keys`マッピングに従って重み埋め込みを共有するかどうか。

これはSamHQModelの設定を保存するための設定クラスです。指定された引数に基づいてSam Hqモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)と類似した設定が得られます。

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

## SamHQVisionConfig[[transformers.SamHQVisionConfig]]

#### transformers.SamHQVisionConfig[[transformers.SamHQVisionConfig]]

```python
transformers.SamHQVisionConfig(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 = 768, output_channels: int = 256, num_hidden_layers: int = 12, num_attention_heads: int = 12, num_channels: int = 3, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, attention_dropout: float | int = 0.0, initializer_range: float = 1e-10, qkv_bias: bool = True, mlp_ratio: float = 4.0, use_abs_pos: bool = True, use_rel_pos: bool = True, window_size: int = 14, global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11), num_pos_feats: int = 128, mlp_dim: int | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L55)

**パラメータ:**

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

output_channels (`int`、*任意*、デフォルトは 256) : Patch Encoder の出力チャネルの次元数。

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

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

num_channels (`int`、*任意*、デフォルトは`3`) : 入力チャネル数。

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

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

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

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

attention_dropout (`Union[float, int]`、*任意*、デフォルトは`0.0`) : 注意確率のドロップアウト率。

initializer_range (`float`、*任意*、デフォルトは `1e-10`) : 全重み行列の初期化に使用される truncated_normal_initializer の標準偏差です。

qkv_bias (`bool`, *任意*, デフォルトは `True`) : クエリ、キー、バリューにバイアスを追加するかどうか。

mlp_ratio (`float`、*任意*、デフォルトは `4.0`) : MLP の隠れ層次元と埋め込み次元の比率。

use_abs_pos (`bool`、*任意*、デフォルトは`True`) : 絶対位置埋め込みを使用するかどうか。

use_rel_pos (`bool`、*任意*、デフォルトは`True`) : 相対位置埋め込みを使用するかどうか。

window_size (`int`, *optional*, デフォルトは 14) : 相対位置のウィンドウサイズ。

global_attn_indexes (`list[int]`、*任意*、デフォルトは`[2, 5, 8, 11]`) : グローバルアテンションレイヤーのインデックスです。

num_pos_feats (`int`、*optional*、デフォルトは 128) : 位置埋め込みの次元数。

mlp_dim (`int`, *optional*) : TransformerエンコーダーのMLP層の次元数。`None`の場合、デフォルトは`mlp_ratio * hidden_size`です。

これはSamHQModelの設定を保存するための設定クラスです。指定された引数に基づいてSam Hqモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)と類似した設定が得られます。

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

例:

```python
>>> from transformers import (
...     SamHQVisionConfig,
...     SamHQVisionModel,
... )

>>> # Initializing a SamHQVisionConfig with `"facebook/sam_hq-vit-huge"` style configuration
>>> configuration = SamHQVisionConfig()

>>> # Initializing a SamHQVisionModel (with random weights) from the `"facebook/sam_hq-vit-huge"` style configuration
>>> model = SamHQVisionModel(configuration)

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

## SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

#### transformers.SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

```python
transformers.SamHQMaskDecoderConfig(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 = 'relu', 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, layer_norm_eps: float = 1e-06, vit_dim: int = 768)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L120)

**パラメータ:**

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

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

mlp_dim (`int`、*optional*、デフォルトは 2048) : Transformer エンコーダーにおける「intermediate」（すなわち、feed-forward）層の次元数。

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

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

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

num_multimask_outputs (`int`、*optional*、デフォルトは 3) : `SamMaskDecoder` モジュールからの出力数です。Segment Anything の論文では、この値は 3 に設定されています。

iou_head_depth (`int`, *任意*, デフォルトは 3) : IoU ヘッドモジュールの層数。

iou_head_hidden_dim (`int`、*optional*、デフォルトは 256) : IoU ヘッドモジュールにおける隠れ状態の次元数。

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

vit_dim (`int`、*optional*、デフォルトは 768) : `SamHQMaskDecoder` モジュールで使用される Vision Transformer (ViT) の次元数。

これはSamHQModelの設定を保存するための設定クラスです。指定された引数に基づいてSam Hqモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)と類似した設定が得られます。

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

## SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

#### transformers.SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

```python
transformers.SamHQPromptEncoderConfig(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)
```

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

**パラメータ:**

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 です。

これはSamHQModelの設定を保存するための設定クラスです。指定された引数に基づいてSam Hqモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)と類似した設定が得られます。

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

## SamHQProcessor[[transformers.SamHQProcessor]]

#### transformers.SamHQProcessor[[transformers.SamHQProcessor]]

```python
transformers.SamHQProcessor(image_processor)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L83)

**パラメータ:**

image_processor (`SamImageProcessor`) : 画像プロセッサは必須の入力です。

画像プロセッサーを単一のプロセッサーにラップするSamHQProcessorを構築します。

[SamHQProcessor](/docs/transformers/main/ja/model_doc/sam_hq#transformers.SamHQProcessor) は [SamImageProcessor](/docs/transformers/main/ja/model_doc/sam#transformers.SamImageProcessor) のすべての機能を提供します。詳細については、[~SamImageProcessor](/docs/transformers/main/ja/model_doc/sam#transformers.SamImageProcessor) を参照してください。

#### __call__[[transformers.SamHQProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L93)

**パラメータ:**

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`, *kwargs*, *optional*) : 入力画像と並行して処理する正解セグメンテーションマップ。これらのマップは学習または評価のために使用され、処理された画像の寸法に合わせてリサイズおよび正規化されます。

input_points (`NestedList`、*kwargs*、*optional*)：プロンプトベースのセグメンテーション用の入力ポイントです。`[image_level, object_level, point_level, [x, y]]` という構造のネストされたリストである必要があります。各ポイントは、元の画像空間における `[x, y]` 座標で指定されます。ポイントは、モデルに渡される前にターゲットの画像サイズに正規化されます。

input_labels (`NestedList`、*kwargs*、*optional*) : 入力ポイントのラベル。各ポイントが前景（1）か背景（0）かを表します。`[image_level, object_level, point_level]` という構造を持つネストされたリストである必要があります。`input_points` と同じ構造（座標次元を除く）である必要があります。

input_boxes (`NestedList`, *kwargs*, *optional*) : プロンプトベースのセグメンテーション用のバウンディングボックス。構造が`[image_level, box_level, [x1, y1, x2, y2]]`のネストされたリストである必要があります。各ボックスは、元の画像空間における`[x1, y1, x2, y2]`座標で指定されます。ボックスは、モデルに渡される前にターゲット画像サイズに正規化されます。

point_pad_value (`int`, *kwargs*, *optional*, デフォルトは `None`) : 長さの異なるシーケンスをバッチ処理する際に、入力ポイントのパディングに使用される値です。この値はパディングされた位置を示し、座標正規化の間も保持されることで、実際のポイントとパディングを区別します。`None` の場合、プロセッサ設定のデフォルトのパディング値が使用されます。

mask_size (`dict[str, *kwargs*, int]`, *任意*) : キー `"height"` と `"width"` を持つ辞書で、ターゲットマスクのサイズを指定します。これにより、モデルが生成する出力セグメンテーションマスクの解像度が決定されます。

mask_pad_size (`dict[str, *kwargs*, int]`, *任意*) : キーに`"height"`と`"width"`を持つ、マスクのパディングサイズを指定する辞書です。これは、異なるサイズのマスクをバッチ処理する際に、次元の一貫性を確保するために使用されます。

return_tensors (`str` または [TensorType](/docs/transformers/main/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、特定のフレームワークのテンソルを返します。受け入れ可能な値は以下の通りです:  - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: NumPy の `np.ndarray` オブジェクトを返します。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ja/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 各モダリティ（テキスト、画像、動画、音声）の追加処理オプション。モデル固有のパラメータは上記にリストされています。サポートされている引数の完全なリストについては、TypedDict クラスを参照してください。

**戻り値:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *任意*) -- __call__/pad メソッドによって返されるリスト/配列/テンソルの辞書（'input_values'、'attention_mask' など）。
- **tensor_type** (`Union[None, str, TensorType]`、*省略可*) -- 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。
- **skip_tensor_conversion** (`list[str]` または `set[str]`、*任意*) -- `tensor_type` が指定されている場合でも、テンソルに変換すべきでないキーのリストまたはセット。

## SamHQVisionModel[[transformers.SamHQVisionModel]]

#### transformers.SamHQVisionModel[[transformers.SamHQVisionModel]]

```python
transformers.SamHQVisionModel(config: SamHQVisionConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1076)

**パラメータ:**

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

ヘッドや投影が上に乗せられていないSamHQのビジョンモデル。

このモデルは [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.SamHQVisionModel.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/sam_hq/modeling_sam_hq.py#L1088)

**パラメータ:**

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

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

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

[SamHQVisionModel](/docs/transformers/main/ja/model_doc/sam_hq#transformers.SamHQVisionModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **image_embeds** (`torch.FloatTensor`、shape `(batch_size, output_dim)`、*optional*、モデルが`with_projection=True`で初期化された場合に返されます) -- pooler_output に投影層を適用して得られる画像埋め込みです。
- **last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*optional*) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **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後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **intermediate_embeddings** (`list(torch.FloatTensor)`, *オプション*) -- モデル内の特定のブロック、通常はウィンドウ付きアテンションを持たないブロックから収集された中間埋め込みのリストです。リストの各要素の形状は `(batch_size, sequence_length, hidden_size)` です。これは SAM-HQ 固有のもので、ベースの SAM には存在しません。

## SamHQModel[[transformers.SamHQModel]]

#### transformers.SamHQModel[[transformers.SamHQModel]]

```python
transformers.SamHQModel(config: SamHQConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1234)

**パラメータ:**

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

入力画像と任意の2D位置およびバウンディングボックスを指定してマスクを生成するためのSegment Anything Model HQ (SAM-HQ)。

このモデルは [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.SamHQModel.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, hq_token_only: bool = False, attention_similarity: typing.Optional[torch.FloatTensor] = None, target_embedding: typing.Optional[torch.FloatTensor] = None, intermediate_embeddings: list[torch.FloatTensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1318)

**パラメータ:**

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

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_HQ モデルはセグメンテーションマスクも入力として受け付けます。マスクはプロンプトエンコーダーによって埋め込まれ、対応する埋め込みが生成されます。この埋め込みは後でマスクデコーダーに渡されます。これらのマスクはユーザーが手動で渡す必要があり、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`を指定することで、「最良」のマスクに相当する単一のマスクのみを出力することも可能です。

hq_token_only (`bool`, *任意*, デフォルトは `False`) : マスク生成にHQトークンパスのみを使用するかどうか。False の場合、標準パスとHQパスの両方を組み合わせます。これは SAM-HQ のアーキテクチャ固有のものです。

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

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

intermediate_embeddings (`List[torch.FloatTensor]`, *任意*) : ビジョンエンコーダーのウィンドウなしブロックからの中間埋め込み。SAM-HQがマスク品質の向上に使用します。pixel_valuesの代わりに事前計算済みのimage_embeddingsを指定する場合に必要です。

**戻り値:**

`list[dict[str, torch.Tensor]]`

[SamHQModel](/docs/transformers/main/ja/model_doc/sam_hq#transformers.SamHQModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

例:

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

>>> model = AutoModel.from_pretrained("sushmanth/sam_hq_vit_b")
>>> processor = AutoProcessor.from_pretrained("sushmanth/sam_hq_vit_b")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=image, input_points=input_points, return_tensors="pt")

>>> # Get high-quality segmentation mask
>>> outputs = model(**inputs)

>>> # For high-quality mask only
>>> outputs = model(**inputs, hq_token_only=True)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"], inputs["reshaped_input_sizes"]
... )
```