# Sapiens2

    
        
        
    

## 概要

Sapiens2モデルは、Rawal Khirodkar、He Wen、Julieta Martinez、Yuan Dong、Zhaoen Su、Shunsuke Saito によって [Sapiens2](https://huggingface.co/papers/2604.21681) で提案されました。Sapiens2は、約10億枚の厳選された人間の画像で事前学習された高解像度のビジョン・トランスフォーマーのファミリーであり、ポーズ推定、身体部位セグメンテーション、表面法線推定、ポイントマップ推定を含む、人間中心のコンピュータビジョンタスクのために設計されています。

すべてのオリジナルのSapiens2チェックポイントは、[Sapiens2](https://huggingface.co/collections/facebook/sapiens2)コレクション内で確認できます。

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

*我々は、汎化性・多用途性・高忠実度の出力に焦点を当てた、人間中心のビジョン向け高解像度 Transformer のファミリーである Sapiens2 を提案します。約 10 億枚の厳選された高品質な人間画像を、改善されたタスクアノテーション付きで事前学習し、マスクドイメージリコンストラクションと自己蒸留対比目的関数を組み合わせることで、低レベル特徴とセマンティック特徴の両方を学習します。モデルは 0.4B から 5B パラメータまでスケーリング可能で、ネイティブ 1K 解像度で学習され、拡張された空間推論のための階層的 4K 変種も用意されています。Sapiens2 は、先行モデルと比較して大幅な性能向上を達成しました：ポーズ推定で mAP +4、ボディパーツセグメンテーションで mIoU +24.3、ノーマル推定でエラー 45.6% 削減であり、pointmap や albedo 推定といった新しいタスクにも対応しています。コードは公開されています。*

ヒント:

- Sapiens2 は Rotary Position Embeddings (RoPE) を使用し、任意の入力解像度をサポートしています。デフォルトの画像プロセッサは、画像を 1024×768（高さ×幅）にリサイズします。
- モデルは、中間層に Grouped Query Attention (GQA) を、最初の8層と最後の8層にはフルのマルチヘッドアテンションを使用します。
- Register tokens（デフォルトでは8個）は、パッチトークンにおける高ノルムアーティファクトを低減し、よりクリーンなアテンションマップと、密な予測タスクにおけるパフォーマンスの向上をもたらします。

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

## 使用例

以下の例では、[Sapiens2Model](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2Model)を使用してCLSトークン（全体画像埋め込み）を取得する方法を示しています。

```python
import torch
from transformers import AutoImageProcessor, AutoModel
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pretrain-0.4b")
model = AutoModel.from_pretrained("facebook/sapiens2-pretrain-0.4b", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.pooler_output is the CLS token (whole-image embedding)
cls_token = outputs.pooler_output
print("CLS token shape:", cls_token.shape)  # [1, 1024]
```

[Sapiens2Backbone](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2Backbone) は、出力オブジェクト上で、空間次元にリシェイプ済みのパッチトークンと CLS トークンを直接公開します。

```python
import torch
from transformers import AutoBackbone, AutoImageProcessor
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pretrain-0.4b")
model = AutoBackbone.from_pretrained("facebook/sapiens2-pretrain-0.4b", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs, return_class_token=True)

# Patch tokens shaped (batch, height, width, channels)
patch_features = outputs.feature_maps[0]
cls_token = outputs.cls_tokens[0]
print("CLS token shape:", cls_token.shape)           # [1, 1024]
print("Patch features shape:", patch_features.shape) # [1, 64, 48, 1024]
```

以下の例では、[Sapiens2ForNormalEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation) を用いて表面法線ベクトルを推定する方法を示しています。出力される法線ベクトルは正規化されていない生データです。`post_process_normal_estimation` を使用して、リサイズおよび L2 正規化を行ってください。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForNormalEstimation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-normal-0.4b")
model = AutoModelForNormalEstimation.from_pretrained("facebook/sapiens2-normal-0.4b", device_map="auto")

inputs = image_processor(image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.normals shape: (batch_size, 3, height, width) — raw, unnormalized XYZ normals
print("Normals shape:", outputs.normals.shape)  # [1, 3, 1024, 768]

# Remove preprocessing padding, resize to original size, and L2-normalize to unit vectors in [-1, 1]
original_size = (image.height, image.width)
result = image_processor.post_process_normal_estimation(
    outputs, source_sizes=[original_size], target_sizes=[original_size]
)
normals = result[0]["normals"]
print("Normals shape:", normals.shape)   # [3, original_height, original_width]

### Example code for visualization

# Convert L2-normalized normals in [-1, 1] to RGB in [0, 255]
normals_rgb = ((normals + 1.0) / 2.0 * 255.0).clamp(0, 255).to(torch.uint8)

# Apply background removal using the segmentation model output.
# `segmentation` is the output of `post_process_semantic_segmentation` — a (H, W) tensor
# of per-pixel class IDs, where class 0 is background.
background_mask = segmentation == 0
normals_rgb[:, background_mask] = 0
print("Normals RGB shape:", normals_rgb.shape)   # [3, original_height, original_width]
```

以下の例では、[Sapiens2ForPointmapEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation) を用いてピクセルごとの3D座標を推定する方法を示します。`post_process_pointmap_estimation` を使用して、前処理時のパディングを除去し、元の画像サイズにリサイズし、予測された焦点距離のスケールを適用します。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForPointmapEstimation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pointmap-0.4b")
model = AutoModelForPointmapEstimation.from_pretrained("facebook/sapiens2-pointmap-0.4b", device_map="auto")

inputs = image_processor(image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.pointmaps shape: (batch_size, 3, height, width) — raw XYZ in canonical camera space
print("Pointmaps shape:", outputs.pointmaps.shape)  # [1, 3, 1024, 768]

# Remove preprocessing padding, resize to original size, and apply focal-length scale
original_size = (image.height, image.width)
result = image_processor.post_process_pointmap_estimation(
    outputs, source_sizes=[original_size], target_sizes=[original_size]
)
pointmap = result[0]["pointmap"]
print("Pointmap shape:", pointmap.shape)  # [3, original_height, original_width]

### Example code for visualization

# Visualize the pointmap as an RGB image using inverse-depth and the turbo colormap.
import matplotlib.pyplot as plt

# `segmentation` is the output of `post_process_semantic_segmentation` — a (H, W) tensor
# of per-pixel class IDs, where class 0 is background.
foreground_mask = segmentation != 0
depth = pointmap[2]  # Z channel: depth in camera space, shape (H, W)
pointmap_rgb = torch.zeros(3, *depth.shape, dtype=torch.uint8)
foreground_depth = depth[foreground_mask]
if foreground_depth.numel() > 0:
    depth_low, depth_high = torch.quantile(foreground_depth, torch.tensor([0.01, 0.99]))
    inverse_depth = 1.0 / foreground_depth.clamp(min=1e-6)
    inverse_depth_low = 1.0 / depth_high.clamp(min=1e-6)
    inverse_depth_high = 1.0 / depth_low.clamp(min=1e-6)
    inverse_depth_normalized = ((inverse_depth - inverse_depth_low) / (inverse_depth_high - inverse_depth_low + 1e-8)).clamp(0, 1)
    turbo = plt.get_cmap("turbo")
    foreground_colors = torch.from_numpy(turbo(inverse_depth_normalized.cpu().numpy())[..., :3] * 255).to(torch.uint8)  # (N, 3)
    pointmap_rgb[:, foreground_mask] = foreground_colors.T
print("Pointmap RGB shape:", pointmap_rgb.shape)  # [3, original_height, original_width]
```

以下の例は、[Sapiens2ForPoseEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) を使用してポーズ推定を実行する方法を示しています。モデルはキーポイントごとのヒートマップを予測します。`post_process_pose_estimation` を使用して、それらを画像空間のキーポイント座標にデコードしてください。`opencv-python` が必要です（`pip install opencv-python`）。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForPoseEstimation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pose-0.4b")
model = AutoModelForPoseEstimation.from_pretrained("facebook/sapiens2-pose-0.4b", device_map="auto")

# Provide bounding boxes in COCO format (x, y, width, height) for each person
boxes = [[[270.8, 0.6, 294.1, 379.5]]]
inputs = image_processor(image, boxes=boxes, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.heatmaps shape: (num_persons, num_keypoints, heatmap_height, heatmap_width)
print("Heatmaps shape:", outputs.heatmaps.shape)  # [1, 308, 256, 192]

# Decode heatmaps to image-space keypoint coordinates
results = image_processor.post_process_pose_estimation(outputs, boxes=boxes)[0]
keypoints = results[0]["keypoints"]   # (num_keypoints, 2) — x/y in image coordinates
scores = results[0]["scores"]         # (num_keypoints,) — per-keypoint confidence
print("Keypoints shape:", keypoints.shape)
```

水平方向の反転拡張（テスト時拡張）は、元の画像とミラーリングされた画像からの予測を平均化することで、キーポイントの精度を向上させます。2回目のフォワードパスに`flip_pairs`（`[left_keypoint, right_keypoint]`のペアからなるテンソル）を渡します。モデルは返却前にヒートマップを元の方向に反転させるため、両方の出力を直接平均化できます。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForPoseEstimation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pose-0.4b")
model = AutoModelForPoseEstimation.from_pretrained("facebook/sapiens2-pose-0.4b", device_map="auto")

boxes = [[[270.8, 0.6, 294.1, 379.5]]]
inputs = image_processor(image, boxes=boxes, return_tensors="pt").to(model.device)
pixel_values = inputs["pixel_values"]

flip_pairs = torch.tensor(model.config.flip_pairs, device=model.device)

with torch.inference_mode():
    outputs = model(pixel_values)
    outputs_flipped = model(pixel_values.flip(-1), flip_pairs=flip_pairs)

results = image_processor.post_process_pose_estimation(outputs, outputs_flipped=outputs_flipped, boxes=boxes)[0]
keypoints = results[0]["keypoints"]
scores = results[0]["scores"]
```

以下の例では、`labels` と任意の `label_weights` を渡すことで、[Sapiens2ForPoseEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) を用いて教師あり Masked Mean Squared Error (MSE) ロスを計算する方法を示しています。これは `Trainer` API を用いたファインチューニングに便利です。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForPoseEstimation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pose-0.4b")
model = AutoModelForPoseEstimation.from_pretrained("facebook/sapiens2-pose-0.4b", device_map="auto")

# Provide bounding boxes in COCO format (x, y, width, height) for each person
boxes = [[[270.8, 0.6, 294.1, 379.5]]]
inputs = image_processor(image, boxes=boxes, return_tensors="pt").to(model.device)

# Create dummy labels (heatmaps) and visibility weights to simulate ground truth
# 1.0 for visible keypoints, 0.0 for occluded/invisible keypoints
batch_size, num_keypoints = 1, 308
heatmap_height, heatmap_width = 1024, 768
labels = torch.randn(batch_size, num_keypoints, heatmap_height, heatmap_width, device=model.device)
label_weights = torch.ones(batch_size, num_keypoints, 1, 1, device=model.device)

# Forward pass with loss calculation
outputs = model(**inputs, labels=labels, label_weights=label_weights)

print("Loss:", outputs.loss.item())
```

以下の例では、[Sapiens2ForSemanticSegmentation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation) を用いた身体部位セグメンテーションの実行方法を示しています。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForSemanticSegmentation
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-seg-0.4b")
model = AutoModelForSemanticSegmentation.from_pretrained("facebook/sapiens2-seg-0.4b", device_map="auto")

inputs = image_processor(image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.logits shape: (batch_size, num_labels, height, width)
print("Logits shape:", outputs.logits.shape)  # [1, 29, 1024, 768]

# Get per-pixel class predictions, optionally resized to the original image size
original_size = (image.height, image.width)
segmentation = image_processor.post_process_semantic_segmentation(
    outputs, target_sizes=[original_size]
)[0]
print("Segmentation map shape:", segmentation.shape)  # [original_height, original_width]
```

以下の例は、[Sapiens2ForImageMatting](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForImageMatting) を使用して画像マッティングを実行する方法を示しています。出力はシグモイド活性化済みで、すでに`[0, 1]`の範囲内にあります。`post_process_image_matting` を使用して、`alphas`、`foregrounds`、および任意の`composite`画像にリサイズして分割します。composite画像は、以下の数式に従って、背景の上に前景を重ね合わせたものです: `composite = foreground * (1 - alpha) * background`。

```python
import torch
from transformers import AutoImageProcessor, AutoModelForImageMatting
from transformers.image_utils import load_image

image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")

image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-matting-1b")
model = AutoModelForImageMatting.from_pretrained("facebook/sapiens2-matting-1b", device_map="auto")

inputs = image_processor(image, return_tensors="pt").to(model.device)
with torch.inference_mode():
    outputs = model(**inputs)

# outputs.foregrounds: (1, 3, H, W), outputs.alphas: (1, 1, H, W) — both in [0, 1]
original_size = (image.height, image.width)

# Pass an optional background to composite the foreground over it.
# A (3, 1, 1) tensor broadcasts as a uniform color; PIL images and numpy arrays are also accepted.
background = torch.tensor([0, 177, 64], dtype=torch.uint8).view(3, 1, 1)  # chroma green in RGB
result = image_processor.post_process_image_matting(
    outputs, target_sizes=[original_size], backgrounds=background
)[0]
print("Alpha shape:", result["alpha"].shape)        # [1, original_height, original_width]
print("Foreground shape:", result["foreground"].shape)  # [3, original_height, original_width]
print("Composite shape:", result["composite"].shape)    # [3, original_height, original_width] — uint8 [0, 255]
```

## Sapiens2Config[[transformers.Sapiens2Config]]

#### transformers.Sapiens2Config[[transformers.Sapiens2Config]]

```python
transformers.Sapiens2Config(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, patch_size: int | list[int] | tuple[int, int] = 16, hidden_size: int = 1024, intermediate_size: int = 4096, num_hidden_layers: int = 24, num_attention_heads: int = 16, hidden_act: str = 'silu', attention_dropout: float | int = 0.0, initializer_range: float = 0.02, rope_theta: float = 100.0, image_size: int | list[int] | tuple[int, int] = 224, num_channels: int = 3, query_bias: bool = True, key_bias: bool = True, value_bias: bool = True, proj_bias: bool = True, mlp_bias: bool = True, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, use_gated_mlp: bool = True, num_register_tokens: int = 8, pos_embed_shift: float | None = None, pos_embed_jitter: float | None = None, pos_embed_rescale: float | None = 2.0, _out_features: list[str] | None = None, _out_indices: list[int] | None = None, reshape_hidden_states: bool = True, use_mask_token: bool = False, rms_norm_eps: float = 1e-06, normalize_backbone_outputs: bool = True, use_qk_norm: bool = True, num_key_value_heads_per_layer: list[int] | None = None, num_key_value_attention_heads: int = 8, num_first_full_attention_layers: int = 8, num_last_full_attention_layers: int = 8, semantic_loss_ignore_index: int = 255, flip_pairs: list[list[int]] | None = None, head_config: transformers.models.sapiens2.configuration_sapiens2.Sapiens2HeadConfig | dict | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/configuration_sapiens2.py#L116)

**パラメータ:**

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

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

intermediate_size (`int`、*任意*、デフォルトは`4096`) : MLP 表現の次元数。

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

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

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

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

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

rope_theta (`float`、*任意*、デフォルトは 100.0) : RoPE 埋め込みのベース期間です。

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

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

query_bias (`bool`、*任意*、デフォルトは`True`) : クエリ投影にバイアス項を追加するかどうか。

key_bias (`bool`、*任意*、デフォルトは`False`) : キーの投影にバイアスを追加するかどうか。

value_bias (`bool`、*任意*、デフォルトは`True`) : 値の投影にバイアスを追加するかどうか。

proj_bias (`bool`, *任意*, デフォルトは `True`) : 出力投影にバイアスを追加するかどうか。

mlp_bias (`bool`、*任意*、デフォルトは `True`) : MLP 層の up_proj、down_proj、gate_proj 層でバイアスを使用するかどうか。

layerscale_value (`float`、*任意*、デフォルト値は 1.0) : layer scale に使用する初期値。

drop_path_rate (`Union[float, int]`、*任意*、デフォルトは`0.0`) : パッチ融合のドロップパス率。

use_gated_mlp (`bool`, *任意*, デフォルトは `False`) : SwiGLUフィードフォワードニューラルネットワークを使用するかどうか。

num_register_tokens (`int`、*任意*、デフォルトは 0) : レジスタトークンの数。

pos_embed_shift (`float`, *任意*) : 学習モードの場合のみ、`None` でないときに適用される、位置埋め込み座標を [-shift, shift] の範囲でランダムにシフトする量です。

pos_embed_jitter (`float`, *optional*) : 位置埋め込みの座標を、[1/jitter, jitter] の範囲で対数一様分布に従ってランダムにジッターする量です。`None` でない場合、トレーニングモードでのみ適用されます。

pos_embed_rescale (`float`、*任意*、デフォルト値は 2.0) : 位置埋め込みの座標を、[1/rescale, rescale] の範囲で対数一様分布に従ってランダムにリスケールする量です。`None` でない場合、トレーニングモードでのみ適用されます。

reshape_hidden_states (`bool`, *任意*, デフォルトは `True`) : バックボーンとして使用する場合、隠れ状態を空間次元にリサイズするかどうかを指定します。

use_mask_token (`bool`、*任意*、デフォルトは`False`) : 埋め込みにマスクトークンを使用するかどうか（マスクドイメージモデリングの事前学習に必要）。

rms_norm_eps (`float`、*optional*、デフォルトは 1e-6) : RMS 正規化レイヤー用の Epsilon。

normalize_backbone_outputs (`bool`、*任意*、デフォルトは`True`) : フォワードパスから`feature_maps`および`cls_tokens`の出力を返す前に、バックボーンにRMSNormを適用するかどうか。モデルがバックボーンとして使用されている場合にのみ適用されます。

use_qk_norm (`bool`, *任意*, デフォルトは `True`) : アテンション層において、RoPE を適用する前にクエリとキーに RMSNorm を適用するかどうか。

num_key_value_heads_per_layer (`list[int]`、*optional*) : 各 Transformer レイヤーのキー/バリューヘッド数。レイヤーの値を`num_attention_heads`に設定するとフルマルチヘッドアテンションになり、より小さい値を設定するとグループドクエリーアテンションになります。デフォルトでは、最初の`num_first_full_attention_layers`レイヤーと最後の`num_last_full_attention_layers`レイヤーは`num_attention_heads`、それ以外のすべてのレイヤーは`num_key_value_attention_heads`になります。

num_key_value_attention_heads (`int`、*任意*、デフォルトは`8`) : `num_key_value_heads_per_layer`が設定されていない場合、grouped-query attentionを使用するレイヤーのkey/valueヘッド数。`num_key_value_heads_per_layer`が設定されている場合は無視されます。

num_first_full_attention_layers (`int`、*任意*、デフォルトは 8) : 完全なマルチヘッドアテンションを使用する先頭の Transformer レイヤーの数。`num_key_value_heads_per_layer` が `None` の場合のみ使用されます。

num_last_full_attention_layers (`int`、*任意*、デフォルトは 8) : 完全なマルチヘッドアテンションを使用する末尾の Transformer レイヤーの数。`num_key_value_heads_per_layer` が `None` の場合のみ使用されます。

semantic_loss_ignore_index (`int`、*optional*、デフォルトは 255) : セグメンテーション損失の計算時に無視されるラベルのインデックス。

flip_pairs (`list[list[int]]`, *任意*) : 水平方向でミラーリングされるキーポイントのインデックスのペア（例：左耳 ↔ 右耳）です。各ペアは2要素のリスト `[left_index, right_index]` です。ポーズ推定におけるテスト時の水平方向フリップ拡張に使用します。これらのペアを2回目のフォワード呼び出しに渡すことで、モデルは返す前にヒートマップを元に戻すようにフリップします。

head_config (`Sapiens2HeadConfig`, *任意*) : デコードヘッドの設定です。利用可能なオプションについては、[Sapiens2HeadConfig](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2HeadConfig)を参照してください。

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

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

## Sapiens2HeadConfig[[transformers.Sapiens2HeadConfig]]

#### transformers.Sapiens2HeadConfig[[transformers.Sapiens2HeadConfig]]

```python
transformers.Sapiens2HeadConfig(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, upsample_out_channels: list[int] | None = None, upsample_kernel_sizes: list[int] | None = None, upsample_kernel_size: int = 4, use_pixel_shuffle: bool | None = None, conv_out_channels: list[int] | None = None, conv_kernel_sizes: list[int] | None = None, conv_kernel_size: int = 1, scale_conv_out_channels: list[int] | None = None, scale_conv_kernel_sizes: list[int] | None = None, scale_conv_kernel_size: int = 1, scale_final_input_size: int | None = None, scale_final_hidden_sizes: list[int] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/configuration_sapiens2.py#L28)

**パラメータ:**

upsample_out_channels (`list[int]`, *optional*) : 各アップサンプルブロックの出力チャネル数。最初のブロックは`hidden_size`チャネルを入力として受け取り、その後のブロックは直前のブロックの出力を使用します。

upsample_kernel_sizes (`list[int]`, *optional*) : 各アップサンプルブロックのカーネルサイズ。`upsample_out_channels`が設定されているが、これが`None`の場合、`[4, ...]`で自動補完されます。`upsample_out_channels`と同じ長さである必要があります。

upsample_kernel_size (`int`、デフォルトは 4) : `upsample_kernel_sizes` が設定されていない場合の、アップサンプルブロックのデフォルトのカーネルサイズ。

use_pixel_shuffle (`bool`, *任意*) : アップサンプルヘッドが転置畳み込みではなくピクセルシャッフルによるアップサンプリングを使用するかどうか。`None`（デフォルト）の場合、ヘッドは転置畳み込みを使用します。

conv_out_channels (`list[int]`, *任意*) : アップサンプルブロックに続くリファインメント用畳み込み層の出力チャネル数。

conv_kernel_sizes (`list[int]`, *optional*) : 各リファインメント畳み込み層のカーネルサイズ。`conv_out_channels`が設定されているが、これが`None`の場合、`[1, ...]`で自動入力されます。`conv_out_channels`と同じ長さである必要があります。

conv_kernel_size (`int`、デフォルトは 1) : `conv_kernel_sizes` が設定されていない場合の、conv レイヤーのデフォルトのカーネルサイズ。

scale_conv_out_channels (`list[int]`, *optional*) : 焦点距離スケールを予測するために使用されるストライド2の畳み込み層の出力チャネル数。`None`（デフォルト）の場合、スケールブランチは構築されません。

scale_conv_kernel_sizes (`list[int]`, *optional*) : 各スケール畳み込み層のカーネルサイズ。`scale_conv_out_channels`が設定されているが、これが`None`の場合、`[1, ...]`で自動補完されます。`scale_conv_out_channels`と同じ長さである必要があります。

scale_conv_kernel_size (`int`、デフォルトは 1) : `scale_conv_kernel_sizes` が設定されていない場合の、スケール用 conv レイヤーのデフォルトのカーネルサイズ。

scale_final_input_size (`int`, *optional*) : スケール MLP に渡されるフラット化された特徴量サイズ。`None`（デフォルト）の場合、親の [Sapiens2Config](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2Config) の `image_size` と `patch_size` から自動的に推論されます。

scale_final_hidden_sizes (`list[int]`, *optional*) : 平坦化されたスケール特徴量をスカラーのスケール出力にマッピングする MLP の隠れ層サイズ。`None`（デフォルト）の場合、スケールブランチは構築されません。

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

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

## Sapiens2ImageProcessor[[transformers.Sapiens2ImageProcessor]]

#### transformers.Sapiens2ImageProcessor[[transformers.Sapiens2ImageProcessor]]

```python
transformers.Sapiens2ImageProcessor(**kwargs: *<class 'transformers.models.sapiens2.image_processing_sapiens2.Sapiens2ImageProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L407)

**パラメータ:**

do_convert_rgb (`bool`, *kwargs*, *optional*) : 画像を RGB に変換するかどうか。

do_resize (`bool`, *kwargs*, *任意*, デフォルトは `True`) : 画像をリサイズするかどうか。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*、デフォルト値は`{'height' : 1024, 'width': 768}`): モデルへの最大入力次元を説明します。

default_to_square (`bool`, *kwargs*, *任意*、デフォルトは `True`) : size が整数の場合、リサイズ時に正方形の画像をデフォルトとするかどうか。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*、デフォルト値は `{'height' : 224, 'width': 224}`): `center_crop` を適用した後の出力画像のサイズ。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*、デフォルト値は`2`) : 画像のリサイズ時に使用するリサンプリングフィルタです。これは列挙型`PILImageResampling`のいずれかになります。`do_resize`が`True`に設定されている場合のみ、効果が現れます。

do_rescale (`bool`, *kwargs*, *optional*, デフォルトは `True`) : 画像をリスケールするかどうか。

rescale_factor (`float`, *kwargs*, *optional*, デフォルトは `0.00392156862745098`) : `do_rescale` が `True` に設定されている場合、画像をリスケールするための係数。

do_normalize (`bool`, *kwargs*, *optional*, デフォルトは `True`) : 画像を正規化するかどうかを指定します。

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *optional*, デフォルトは `[0.485, 0.456, 0.406]`) : 正規化に使用する画像の平均値です。`do_normalize` が `True` に設定されている場合のみ有効です。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *optional*, デフォルトは `[0.229, 0.224, 0.225]`) : 正規化に使用する画像の標準偏差。`do_normalize` が `True` に設定されている場合のみ有効です。

do_pad (`bool`, *kwargs*, *任意*、デフォルトは `False`) : 画像にパディングを適用するかどうか。パディングは、バッチ内の最大サイズに合わせるか、画像ごとに固定の正方形サイズに合わせるかのいずれかで行われます。正確なパディング戦略はモデルによって異なります。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 画像をパディングするサイズを`{"height": int, "width" int}`で指定します。前処理に提供されたすべての画像サイズより大きい必要があります。`pad_size`が指定されない場合、バッチ内の最大の幅と高さにパディングされます。`do_pad=True.`の場合にのみ適用されます。

do_center_crop (`bool`, *kwargs*, *optional*, デフォルトは `False`) : 画像を中央クロップするかどうか。

data_format (`Union[str, ~image_utils.ChannelDimension]`、*kwargs*、*optional*) : 対応するのは `ChannelDimension.FIRST` のみです。slow processors との互換性のために追加されました。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *任意*) : 入力画像のチャネル次元の形式です。設定されていない場合、入力画像からチャネル次元の形式が推論されます。以下のいずれかになります: - `"channels_first"` または `ChannelDimension.FIRST`: (num_channels, height, width) 形式の画像。 - `"channels_last"` または `ChannelDimension.LAST`: (height, width, num_channels) 形式の画像。 - `"none"` または `ChannelDimension.NONE`: (height, width) 形式の画像。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 動画を処理するデバイスです。未設定の場合、入力動画からデバイスが推論されます。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。

disable_grouping (`bool`, *kwargs*, *optional*) : 画像をサイズごとにグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうかを指定します。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている実証的な観察に基づいています。

image_seq_length (`int`, *kwargs*, *任意*) : 入力内の各画像に使用される画像トークンの数です。後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。

do_reduce_labels (`bool`, *kwargs*, *任意*、デフォルトは `self.do_reduce_labels`) : セグメンテーションマップのすべてのラベル値を 1 減らすかどうか。0 が背景に使用され、かつ背景自体がデータセットのすべてのクラスに含まれていないデータセット（ADE20k など）で通常使用されます。背景ラベルは 255 に置き換えられます。

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *optional*, デフォルトは 4) : モデルの入力サイズに対する、ターゲットヒートマップサイズのダウンスケール係数。

keypoint_heatmap_sigma (`float`, *kwargs*, *optional*, デフォルト値は 6.0) : ヒートマップを生成するために使用される 2 次元ガウス分布の標準偏差 (sigma) です。

Sapiens2ImageProcessor の画像プロセッサを構築します。

#### preprocess[[transformers.Sapiens2ImageProcessor.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, boxes: list[list[list[float]]] | None = None, keypoints: list[list[list[list[float]]]] | None = None, **kwargs: *<class 'transformers.models.sapiens2.image_processing_sapiens2.Sapiens2ImageProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L430)

**パラメータ:**

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`, *任意*) : 前処理対象のセグメンテーションマップ。

boxes (`list[list[list[float]]]` または `np.ndarray`、*optional*) : 各画像のバウンディングボックスのリストまたは配列。各ボックスは、COCO 形式のバウンディングボックス座標（top_left_x、top_left_y、width、height）を表す 4 つの float のリストである必要があります。指定された場合、フルサイズ画像のリサイズではなく、各人物のクロップがアフィン変換されてモデルの入力サイズに調整されます。

keypoints (`list[list[list[list[float]]]]`, *任意*) : 各画像内の各人物のキーポイントのリスト。期待される形式は、COCOスタイルの`[x, y, visibility]`です。`x`および`y`の値は、絶対的な画像ピクセル座標であることが期待されます。形式は`[images -> persons -> keypoints -> [x, y, visibility]]`です。ポーズ推定のファインチューニングにおいて、正解データ（ground-truth）のヒートマップと可視性重みの生成に使用されます。

do_convert_rgb (`bool`, *kwargs*, *optional*) : 画像を RGB に変換するかどうか。

do_resize (`bool`, *kwargs*, *optional*) : 画像をリサイズするかどうか。

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : モデルへの最大入力次元を記述します。

default_to_square (`bool`, *kwargs*, *optional*) : size が int の場合、リサイズ時に正方形の画像をデフォルトとするかどうか。

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop` を適用した後の出力画像のサイズ。

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 画像をリサイズする場合に使用するリサンプリングフィルタ。`PILImageResampling` の列挙型のいずれかです。`do_resize` が `True` に設定されている場合のみ有効です。

do_rescale (`bool`, *kwargs*, *任意*) : 画像をリスケールするかどうか。

rescale_factor (`float`, *kwargs*, *optional*) : `do_rescale` が `True` に設定されている場合、画像をリサイズするためのリスケール係数。

do_normalize (`bool`, *kwargs*, *optional*) : 画像を正規化するかどうかを指定します。

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *optional*) : 正規化に使用する画像の平均値。`do_normalize` が `True` に設定されている場合のみ有効です。

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *optional*) : 正規化に使用する画像の標準偏差。`do_normalize` が `True` に設定されている場合のみ有効です。

do_pad (`bool`, *kwargs*, *任意*) : 画像にパディングを適用するかどうか。パディングは、バッチ内の最大サイズに合わせるか、画像ごとに固定の正方形サイズに合わせるかのいずれかで行われます。正確なパディング戦略はモデルによって異なります。

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 画像をパディングするサイズを`{"height": int, "width" int}`で指定します。前処理に提供されたすべての画像サイズより大きい必要があります。`pad_size`が指定されない場合、バッチ内の最大の幅と高さにパディングされます。`do_pad=True.`の場合にのみ適用されます。

do_center_crop (`bool`, *kwargs*, *optional*) : 画像を中央クロップするかどうか。

data_format (`Union[str, ~image_utils.ChannelDimension]`、*kwargs*、*optional*) : 対応するのは `ChannelDimension.FIRST` のみです。slow processors との互換性のために追加されました。

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *任意*) : 入力画像のチャネル次元の形式です。設定されていない場合、入力画像からチャネル次元の形式が推論されます。以下のいずれかになります: - `"channels_first"` または `ChannelDimension.FIRST`: (num_channels, height, width) 形式の画像。 - `"channels_last"` または `ChannelDimension.LAST`: (height, width, num_channels) 形式の画像。 - `"none"` または `ChannelDimension.NONE`: (height, width) 形式の画像。

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 動画を処理するデバイスです。未設定の場合、入力動画からデバイスが推論されます。

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`に設定されている場合はスタックされたテンソルを返し、それ以外の場合はテンソルのリストを返します。

disable_grouping (`bool`, *kwargs*, *optional*) : 画像をサイズごとにグループ化してバッチ処理するのではなく、個別に処理するためにグループ化を無効にするかどうかを指定します。None の場合、画像が CPU にある場合は True、それ以外の場合は False に設定されます。この選択は、https://github.com/huggingface/transformers/pull/38157 に詳しく記載されている実証的な観察に基づいています。

image_seq_length (`int`, *kwargs*, *任意*) : 入力内の各画像に使用される画像トークンの数です。後方互換性のために追加されましたが、将来のモデルではプロセッサの属性として設定されるべきです。

do_reduce_labels (`bool`, *kwargs*, *任意*、デフォルトは `self.do_reduce_labels`) : セグメンテーションマップのすべてのラベル値を 1 減らすかどうか。0 が背景に使用され、かつ背景自体がデータセットのすべてのクラスに含まれていないデータセット（ADE20k など）で通常使用されます。背景ラベルは 255 に置き換えられます。

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *optional*, デフォルトは 4) : モデルの入力サイズに対する、ターゲットヒートマップサイズのダウンスケール係数。

keypoint_heatmap_sigma (`float`, *kwargs*, *optional*, デフォルト値は 6.0) : ヒートマップを生成するために使用される 2 次元ガウス分布の標準偏差 (sigma) です。

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

- **data** (`dict`) -- __call__ メソッドによって返されるリスト/配列/テンソルの辞書（'pixel_values' など）。
- **tensor_type** (`Union[None, str, TensorType]`、*省略可*) -- 初期化時に PyTorch/Numpy の Tensor 内の整数リストを変換するために、ここで tensor_type を指定できます。

#### post_process_image_matting[[transformers.Sapiens2ImageProcessor.post_process_image_matting]]

```python
post_process_image_matting(outputs, target_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, backgrounds: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L891)

**パラメータ:**

outputs (`Sapiens2ImageMattingOutput`) : モデルの生出力。

target_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 各予測について要求される最終的な `(height, width)`。双線形補間によってリサイズされます。設定されていない場合、予測はモデルの出力解像度で返されます。

backgrounds (`ImageInput`, *任意*) : 合成する背景画像です。単一の画像（バッチ内のすべてのアイテムに適用される）または、バッチアイテムごとに1枚ずつの画像のリストを指定できます。PIL画像、numpy配列、任意のdtypeのtorchテンソルを受け付けます。整数型（例: uint8）は自動的に`[0, 1]`にスケーリングされます。指定された場合、各結果の辞書には、合成された画像が`[0, 255]`のuint8テンソルとして格納された`"composite"`キーが追加されます。

**戻り値:** 長さ`batch_size`の`list[dict]`。各dictには

- `"alpha"`（`torch.Tensor`、形状 `(1, height, width)`）: `[0, 1]` 範囲の alpha 値。
- `"foreground"`（`torch.Tensor`、形状 `(3, height, width)`）: `[0, 1]` 範囲の、乗算済み RGB。
- `"composite"`（`(3, height, width)` の形状の `torch.Tensor` または `None`）: `[0, 255]` の uint8 テンソルとして、`backgrounds` 上に合成された前景。 `backgrounds` が指定されていない場合は `None`。

[Sapiens2ForImageMatting](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForImageMatting)の出力をアルファマットとフォアグラウンドマップに変換します。

#### post_process_normal_estimation[[transformers.Sapiens2ImageProcessor.post_process_normal_estimation]]

```python
post_process_normal_estimation(outputs, source_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, target_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, do_remove_padding: bool | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L818)

**パラメータ:**

outputs (`Sapiens2NormalEstimatorOutput`) : モデルの生出力。

source_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 前処理前の各画像の元の `(height, width)`。指定された場合、前処理で追加されたパディングが除去され、予測結果は元の画像サイズにリサイズされます（`target_sizes` が最終サイズを上書きしない限り）。

target_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 各予測について要求される最終的な `(height, width)`。指定された場合、`source_sizes` の代わりにリサイズ先として使用されます。L2 正規化後に双線形補間によってリサイズされます。

do_remove_padding (`bool`, *任意*) : リサイズ前に、前処理で追加されたゼロパディングを切り捨てるかどうか。`source_sizes` が指定されている場合はデフォルトで `True`、それ以外の場合は `False` になります。

**戻り値:**

`list[dict[str, torch.Tensor]]` の長さ `batch_size` のリスト。各 dict は `"normals"` キーを持ち、これは `(3, height, width)` の形状のテンソルにマッピングされ、各チャネル（XYZ 表面法線）について `[-1, 1]` の範囲で L2 正規化された単位ベクトルを保持します。

[Sapiens2ForNormalEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation)の出力を、L2正規化された表面法線マップに変換します。

#### post_process_pointmap_estimation[[transformers.Sapiens2ImageProcessor.post_process_pointmap_estimation]]

```python
post_process_pointmap_estimation(outputs, source_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, target_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, do_remove_padding: bool | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L854)

**パラメータ:**

outputs (`Sapiens2PointmapEstimatorOutput`) : モデルの生出力。

source_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 前処理前の各画像の元の `(height, width)`。指定された場合、前処理で追加されたパディングが除去され、予測結果は元の画像サイズにリサイズされます（`target_sizes` が最終サイズを上書きしない限り）。

target_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*任意*) : 各予測について要求される最終的な `(height, width)`。`source_sizes` を上書きしてリサイズ先として使用します。

do_remove_padding (`bool`, *任意*) : リサイズ前に、前処理で追加されたゼロパディングを切り捨てるかどうか。`source_sizes` が指定されている場合はデフォルトで `True`、それ以外の場合は `False` になります。

**戻り値:**

`batch_size` の長さの `list[dict[str, torch.Tensor]]`。各 dict には `"pointmap"` というキーがあり、正規化カメラ空間におけるピクセルごとの 3D XYZ 座標を持つ、形状が `(3, height, width)` のテンソルにマップされています。必要に応じて `outputs.scales` で除算することで、メートル単位の座標に変換できます。

[Sapiens2ForPointmapEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation)の出力を、画像空間におけるpointmapテンソルに変換します。

#### post_process_pose_estimation[[transformers.Sapiens2ImageProcessor.post_process_pose_estimation]]

```python
post_process_pose_estimation(outputs, boxes: list, outputs_flipped = None, kernel_size: int = 11, threshold: float | None = None, source_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None, target_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L676)

**パラメータ:**

outputs (`Sapiens2PoseEstimatorOutput`) : モデルの生出力。`outputs.heatmaps` の形状は `(N_total, num_keypoints, heatmap_height, heatmap_width)` である必要があります。ここで `N_total = sum(len(b) for b in boxes)` です。

boxes (`list[list[list[float]]]` または `np.ndarray`) : 絶対ピクセル座標での、各画像のバウンディングボックスのリストまたは配列。各ボックスは、COCO形式のバウンディングボックス座標 (top_left_x, top_left_y, width, height) を表す4つのfloatのリストである必要があります。`preprocess` に渡される `boxes` 引数と一致している必要があります。

outputs_flipped (`Sapiens2PoseEstimatorOutput`, *任意*) : 水平反転した入力に対してモデルを実行した結果の出力です。指定された場合、キーポイント抽出の前に `outputs` とヒートマップを平均化して精度を向上させます: `avg_heatmaps = (outputs.heatmaps + outputs_flipped.heatmaps) / 2`。

kernel_size (`int`, *optional*, デフォルトは 11) : UDP Dark Pose のリファインメントで使用するガウスぼかしカーネルのサイズ。

threshold (`float`, *optional*) : スコアの閾値。この値以下（等しい場合を含む）のスコアを持つキーポイントは、結果の辞書から除外されます。

source_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 各画像の元の `(height, width)`（ピクセル単位）。`target_sizes` が指定された場合、キーポイントとバウンディングボックスの縮小・拡大の元となる座標空間として必要です。

target_sizes (`torch.Tensor` または長さ `batch_size` の `list[tuple[int, int]]`、*optional*) : 各画像の出力座標空間 `(height, width)`。`source_sizes` と同時に指定された場合、キーポイントの座標とバウンディングボックスはソース空間からターゲット空間へスケーリングされます。

**戻り値:** `list[list[dict]]`

Outer listは画像を、inner listは人物を反復します。各辞書には以下が含まれます:
- `keypoints` (`torch.Tensor`、形状 `(num_keypoints, 2)`): ソース画像空間における絶対的な x/y 座標。ただし、`target_sizes` が指定されている場合は、ターゲット空間における座標になります。
- `scores`（`torch.Tensor`、形状 `(num_keypoints,)`）: キーポイントごとの信頼度。
- `labels` (`torch.LongTensor`、shape `(num_keypoints,)`): キーポイントのインデックス。
- `bbox` (`torch.Tensor`、形状 `(4,)`): 絶対座標形式 (x_min, y_min, x_max, y_max) のバウンディングボックス。`keypoints` と同じ座標空間です。

[Sapiens2ForPoseEstimation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation)の出力を、画像空間におけるキーポイント予測に変換します。

#### post_process_semantic_segmentation[[transformers.Sapiens2ImageProcessor.post_process_semantic_segmentation]]

```python
post_process_semantic_segmentation(outputs, target_sizes: list[tuple] | None = None, return_segmentation_scores: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/image_processing_sapiens2.py#L610)

**パラメータ:**

outputs ([Sapiens2ForSemanticSegmentation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation)) : モデルの生出力。

target_sizes (`list[Tuple]`、長さ `batch_size`、*任意*) : 各予測の要求される最終サイズ（高さ、幅）に対応するタプルのリスト。未設定の場合、予測はリサイズされません。

return_segmentation_scores (`bool`、*任意*、デフォルトは`False`) : セグメンテーションマップとともにセグメンテーションスコアを返すかどうか。`True`の場合、返されるリストの各要素は、`segmentation`（クラス ID、形状`(height, width)`）と`segmentation_scores`（形状`(num_classes, height, width)`）というフィールドを持つ`SemanticSegmentationPostProcessorOutput`です。

**戻り値:** `list[torch.Tensor]` または `list[SemanticSegmentationPostProcessorOutput]`

`return_segmentation_scores=False` (デフォルト)の場合、長さが`batch_size`のリストが返され、各要素はクラス ID を持つ形状`(height, width)`のセグメンテーションマップです。`return_segmentation_scores=True`の場合、`SemanticSegmentationPostProcessorOutput`のリストが返され、フィールド`segmentation` (クラス ID、形状`(height, width)`)と`segmentation_scores` (形状`(num_classes, height, width)`)を持ちます。どちらの場合も、`(height, width)`はターゲットサイズに対応します(`target_sizes`が指定されている場合)。

[Sapiens2ForSemanticSegmentation](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation)の出力をセマンティックセグメンテーションマップに変換します。

## Sapiens2Model[[transformers.Sapiens2Model]]

#### transformers.Sapiens2Model[[transformers.Sapiens2Model]]

```python
transformers.Sapiens2Model(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L867)

**パラメータ:**

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

特定のヘッドを付加せずに、生のhidden-statesを出力する素のSapiens2 Model。

このモデルは [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.Sapiens2Model.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L880)

**パラメータ:**

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

bool_masked_pos (`torch.BoolTensor`、形状 `(batch_size, sequence_length)`、*任意*) : 真偽値のマスク位置。どのパッチがマスクされているか（1）、されていないか（0）を示します。事前学習でのみ関連します。

**戻り値:** [BaseModelOutputWithPooling](/docs/transformers/main/ja/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) または `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **pooler_output** (`torch.Tensor`、形状 `(batch_size, hidden_size)`) -- 補助的な事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン（分類トークン）の最終層の隠れ状態です。例えば、BERT系のモデルでは、線形層とtanh活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次の文予測（分類）目的から学習されます。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pretrain-0.4b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-pretrain-0.4b")

>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> cls_token = outputs.pooler_output
>>> cls_token.shape
torch.Size([1, 1024])
```

## Sapiens2Backbone[[transformers.Sapiens2Backbone]]

#### transformers.Sapiens2Backbone[[transformers.Sapiens2Backbone]]

```python
transformers.Sapiens2Backbone(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L929)

**パラメータ:**

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

Sapiens2のバックボーン。

このモデルは [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.Sapiens2Backbone.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L942)

**パラメータ:**

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

**戻り値:** `Sapiens2BackboneOutput` または `tuple(torch.Tensor)`

`Sapiens2BackboneOutput` または `torch.Tensor` のタプル（`return_dict=False` が渡された場合、または `config.return_dict=False` の場合）。[Sapiens2Config](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2Config) および入力に応じて、さまざまな要素で構成されます。

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

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

- **feature_maps** (`tuple(torch.Tensor)`、形状 `(batch_size, num_channels, height, width)`) -- 各ステージのフィーチャマップ。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込みの出力用 1 つ + 各レイヤーの出力用 1 つ）。形状は `(batch_size, sequence_length, hidden_size)` または `(batch_size, num_channels, height, width)` で、バックボーンによって異なります。

  各ステージの出力におけるモデルのHidden-states、および初期の埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。バックボーンがアテンションを使用する場合にのみ適用されます。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **cls_tokens** (`tuple(torch.Tensor)`, *オプション*) -- 選択された各特徴量ステージからのCLSトークンで、それぞれの形状は`(batch_size, hidden_size)`です。`config.return_class_token=True`の場合にのみ存在します。

例:

```python
>>> from transformers import AutoBackbone, AutoImageProcessor
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pretrain-0.4b")
>>> model = AutoBackbone.from_pretrained("facebook/sapiens2-pretrain-0.4b")

>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs, return_class_token=True)

>>> outputs.feature_maps[0].shape
torch.Size([1, 1024, 64, 48])
>>> outputs.cls_tokens[0].shape
torch.Size([1, 1024])
```

## Sapiens2ForImageMatting[[transformers.Sapiens2ForImageMatting]]

#### transformers.Sapiens2ForImageMatting[[transformers.Sapiens2ForImageMatting]]

```python
transformers.Sapiens2ForImageMatting(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1365)

**パラメータ:**

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

マッティングヘッドを上部に備えたSapiens2モデル（ピクセルシャッフルベースのデコーダーで、プリマルチプライされたRGBの前景とアルファマットを予測します）。

このモデルは [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.Sapiens2ForImageMatting.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1372)

**パラメータ:**

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

labels (`torch.Tensor`、形状 `(batch_size, 4, height, width)`、*任意*) : ロスの計算に使用する正解のマットングターゲット。

**戻り値:** `Sapiens2ImageMattingOutput` または `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor`、形状 `(1,)`、*任意*、`labels` が指定された場合に返されます) -- 損失。
- **alphas** (`torch.Tensor`、形状 `(batch_size, 1, height, width)`) -- 推定されたアルファ値。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各ステージの出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。各ステージの出力におけるモデルの隠れ状態（特徴マップとも呼ばれます）。
- **attentions** (`tuple[torch.Tensor]`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **foregrounds** (`torch.Tensor`、形状 `(batch_size, 3, height, width)`) -- `[0, 1]` 範囲の、乗算済み RGB フォアグラウンド予測（シグモイド活性化済み）。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-matting-1b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-matting-1b")

>>> inputs = image_processor(image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> outputs.alphas.shape
torch.Size([1, 1, 1024, 768])
>>> outputs.foregrounds.shape
torch.Size([1, 3, 1024, 768])
```

## Sapiens2ForNormalEstimation[[transformers.Sapiens2ForNormalEstimation]]

#### transformers.Sapiens2ForNormalEstimation[[transformers.Sapiens2ForNormalEstimation]]

```python
transformers.Sapiens2ForNormalEstimation(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1215)

**パラメータ:**

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

PixelShuffleベースのデコーダーで、表面法線マップを予測する法線推定ヘッドを上部に備えたSapiens2モデル。

このモデルは [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.Sapiens2ForNormalEstimation.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1223)

**パラメータ:**

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

labels (`torch.Tensor`、形状 `(batch_size, num_labels, height, width)`、*任意*) : ロスの計算に使用する正解の表面法線マップ。

**戻り値:** `Sapiens2NormalEstimatorOutput` または `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor`、形状 `(1,)`、*任意*、`labels` が指定された場合に返されます) -- 正規推定損失。
- **normals** (`torch.Tensor`、形状 `(batch_size, num_labels, height, width)`) -- モデルが出力する生のノーマルマップの予測値（正規化されていません）。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込みの出力用 1 つ + 各ステージの出力用 1 つ）、形状は `(batch_size, sequence_length, hidden_size)` です。各レイヤーの出力におけるモデルの隠れ状態と、初期埋め込みの出力です。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。アテンションの softmax 後のアテンション重み。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-normal-0.4b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-normal-0.4b")

>>> inputs = image_processor(image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> outputs.normals.shape
torch.Size([1, 3, 1024, 768])
```

## Sapiens2ForPointmapEstimation[[transformers.Sapiens2ForPointmapEstimation]]

#### transformers.Sapiens2ForPointmapEstimation[[transformers.Sapiens2ForPointmapEstimation]]

```python
transformers.Sapiens2ForPointmapEstimation(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1287)

**パラメータ:**

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

pointmapヘッドを備えたSapiens2モデル（ピクセルごとの3次元XYZ座標を予測するPixelShuffleベースのデコーダー、および焦点距離の正規化のための任意のスケールブランチ）。

このモデルは [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.Sapiens2ForPointmapEstimation.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1299)

**パラメータ:**

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

labels (`torch.Tensor`、形状 `(batch_size, 3, height, width)`、*任意*) : 損失を計算するための正解のpointmap。

**戻り値:** `Sapiens2PointmapEstimatorOutput` または `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor`、形状 `(1,)`、*任意*、`labels` が指定された場合に返されます) -- Pointmap 推定損失。
- **pointmaps** (`torch.Tensor`、形状 `(batch_size, 3, height, width)`) -- 正規化カメラ空間における、ピクセルごとの3次元XYZ座標の予測値。
- **scales** (`torch.Tensor`、形状 `(batch_size, 1)`、*任意*) -- 正規化焦点距離 / 実際の焦点距離の比率。スケールブランチが設定されていない場合は `None`。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込みの出力用 1 つ + 各ステージの出力用 1 つ）、形状は `(batch_size, sequence_length, hidden_size)` です。各レイヤーの出力におけるモデルの隠れ状態と、初期埋め込みの出力です。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。アテンションの softmax 後のアテンション重み。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pointmap-0.4b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-pointmap-0.4b")

>>> inputs = image_processor(image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> outputs.pointmaps.shape
torch.Size([1, 3, 1024, 768])
```

## Sapiens2ForPoseEstimation[[transformers.Sapiens2ForPoseEstimation]]

#### transformers.Sapiens2ForPoseEstimation[[transformers.Sapiens2ForPoseEstimation]]

```python
transformers.Sapiens2ForPoseEstimation(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1132)

**パラメータ:**

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

pose estimation head（hidden statesの出力上に配置された一連のheatmap predictors）を備えたSapiens2モデル。

このモデルは [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.Sapiens2ForPoseEstimation.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1140)

**パラメータ:**

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

flip_pairs (`torch.Tensor`、shape `(num_pairs, 2)`、*optional*) : 左右対称のキーポイントのペア（例：左耳 -- 右耳）です。テスト時のフリップ拡張に使用されます。指定された場合、モデルは`pixel_values`が水平方向に反転した画像を含むと仮定し、出力ヒートマップに対して`flip_back`を呼び出して元の方向を復元します。

labels (`torch.Tensor`、形状 `(batch_size, num_keypoints, height, width)`、*任意*) : 損失を計算するためのヒートマップの正解データ。

label_weights (`torch.Tensor`、形状は`(batch_size, num_labels, 1, 1)`または`(batch_size, num_labels, height, width)`、*optional*) : 各キーポイントの可視性重み。`labels`の形状にブロードキャスト可能である必要があります。

**戻り値:** `Sapiens2PoseEstimatorOutput` または `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor`、形状 `(1,)`、*任意*、`labels` が指定された場合に返されます) -- ポーズ推定損失。
- **ヒートマップ**（`torch.Tensor`、形状 `(batch_size, num_keypoints, height, width)`）-- モデルが予測したヒートマップ。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各ステージの出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。各ステージの出力におけるモデルの隠れ状態（特徴マップとも呼ばれます）。
- **attentions** (`tuple[torch.Tensor, ...]`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)` です。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-pose-0.4b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-pose-0.4b")

>>> boxes = [[[270.8, 0.6, 294.1, 379.5]]]
>>> inputs = image_processor(image, boxes=boxes, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> outputs.heatmaps.shape
torch.Size([1, 308, 256, 192])
```

## Sapiens2ForSemanticSegmentation[[transformers.Sapiens2ForSemanticSegmentation]]

#### transformers.Sapiens2ForSemanticSegmentation[[transformers.Sapiens2ForSemanticSegmentation]]

```python
transformers.Sapiens2ForSemanticSegmentation(config: Sapiens2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1019)

**パラメータ:**

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

ADE20KやCityScapesなどのタスクに使用されるセマンティックセグメンテーションヘッドを備えたSapiens2モデル。

このモデルは [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.Sapiens2ForSemanticSegmentation.forward]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sapiens2/modeling_sapiens2.py#L1027)

**パラメータ:**

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

labels (`torch.LongTensor`、shape `(batch_size, height, width)`、*任意*) : ロスの計算に使用する正解のセマンティックセグメンテーションマップ。インデックスは `[0, ..., config.num_labels - 1]` の範囲である必要があります。`config.num_labels > 1` の場合、分類ロス（Cross-Entropy）が計算されます。

**戻り値:** [SemanticSegmenterOutput](/docs/transformers/main/ja/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) または `tuple(torch.Tensor)`

設定（[Sapiens2Config](/docs/transformers/main/ja/model_doc/sapiens2#transformers.Sapiens2Config)）や入力に応じて、さまざまな要素で構成される、[SemanticSegmenterOutput](/docs/transformers/main/ja/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) または `torch.Tensor` のタプル（`return_dict=False` が渡された場合、または `config.return_dict=False` の場合）。

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

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

- **loss** (`torch.Tensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 分類損失（config.num_labels==1 の場合は回帰損失）。
- **logits** (`torch.Tensor`、形状 `(batch_size, config.num_labels, logits_height, logits_width)`) -- 各ピクセルの分類スコア。

  

  返される logits は、入力として渡された `pixel_values` と同じサイズであるとは限りません。これは、ユーザーが後処理として logits を元の画像サイズにリサイズする際に、2回の補間処理による品質の低下を避けるためです。常に logits の形状を確認し、必要に応じてリサイズしてください。

  
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用 1 つ + 各層の出力用 1 つ）で、形状は `(batch_size, patch_size, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, patch_size, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

```python
>>> from transformers import AutoImageProcessor, AutoModel
>>> from transformers.image_utils import load_image
>>> import torch

>>> image = load_image("http://images.cocodataset.org/val2017/000000004016.jpg")
>>> image_processor = AutoImageProcessor.from_pretrained("facebook/sapiens2-seg-0.4b")
>>> model = AutoModel.from_pretrained("facebook/sapiens2-seg-0.4b")

>>> inputs = image_processor(image, return_tensors="pt")
>>> with torch.inference_mode():
...     outputs = model(**inputs)

>>> outputs.logits.shape
torch.Size([1, 29, 1024, 768])
```