# Sapiens2

    
        
        
    

## Обзор

Модель Sapiens2 была предложена в [Sapiens2](https://huggingface.co/papers/2604.21681) Rawal Khirodkar, He Wen, Julieta Martinez, Yuan Dong, Zhaoen Su, Shunsuke Saito. Sapiens2 — это семейство высокодетализированных vision transformers, предобученных на ~1 миллиарде отобранных изображений людей, предназначенное для задач компьютерного зрения, ориентированных на человека, включая оценку позы, сегментацию частей тела, оценку поверхностных нормалей и оценку pointmap.

Все исходные контрольные точки Sapiens2 можно найти в коллекции [Sapiens2](https://huggingface.co/collections/facebook/sapiens2).

Аннотация из статьи следующая:

*Мы представляем Sapiens2 — семейство трансформеров высокого разрешения для задач компьютерного зрения, ориентированных на человека, с акцентом на обобщаемость, универсальность и высокое качество результатов. Мы обучаем модель на ~1 млрд отобранных изображений высокого качества с улучшенными аннотациями задач и сочетаем восстановление изображений с маскированием с само-дистиллированными контрастными целями, чтобы обучать как низкоуровневые, так и семантические признаки. Наши модели масштабируются от 0,4 до 5 млрд параметров и обучаются в нативном разрешении 1K, а иерархические варианты 4K обеспечивают расширенное пространственное рассуждение. Sapiens2 демонстрирует существенное улучшение по сравнению с предыдущей версией: +4 mAP в оценке позы, +24,3 mIoU в сегментации частей тела и снижение ошибки на 45,6% в оценке нормалей, а также расширяется на новые задачи, такие как оценка pointmap и альбедо. Код доступен публично.*

Советы:

- Sapiens2 использует Rotary Position Embeddings (RoPE) и поддерживает произвольные разрешения входных данных. По умолчанию процессор изображений изменяет размер изображений до 1024×768 (высота×ширина).
- Модель использует Grouped Query Attention (GQA) для средних слоёв и полное multi-head внимание для первых и последних 8 слоёв.
- Регистрационные токены (по умолчанию — 8) снижают артефакты с высокой нормой в патч-токенах, что приводит к более чистым картам внимания и лучшей производительности на задачах плотного предсказания.

Эта модель была добавлена пользователем [guarin](https://huggingface.co/guarin). Исходный код можно найти [здесь](https://github.com/facebookresearch/sapiens2).

## Примеры использования

Пример ниже показывает, как получить токен CLS (эмбеддинг всего изображения) с помощью [Sapiens2Model](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Model).

```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/v5.23.0/ru/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/v5.23.0/ru/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]
```

Пример ниже показывает, как оценить 3D-координаты для каждого пикселя с помощью [Sapiens2ForPointmapEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation). Используйте `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/v5.23.0/ru/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)
```

Аугментация с горизонтальным отражением (test-time augmentation) повышает точность определения ключевых точек за счёт усреднения предсказаний для исходного и зеркально отражённого изображения. Передайте `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"]
```

Пример ниже показывает, как вычислить контролируемый (supervised) средний квадратичный (MSE) критерий потерь с помощью [Sapiens2ForPoseEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation), передав `labels` и необязательный `label_weights`. Это полезно для дообучения с использованием API `Trainer`.

```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/v5.23.0/ru/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/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForImageMatting). Выходные данные активируются сигмоидой и уже находятся в диапазоне `[0, 1]`; используйте `post_process_image_matting`, чтобы изменить размер и разделить их на `alphas`, `foregrounds` и необязательное изображение `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/v5.23.0/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`, *необязательный*, по умолчанию `24`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `16`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

hidden_act (`str`, *необязательный*, по умолчанию `silu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для вероятностей внимания.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

rope_theta (`float`, *optional*, по умолчанию 100.0) : Базовый период для вложений RoPE.

image_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `224`) : Размер (разрешение) каждого изображения.

num_channels (`int`, *необязательный*, по умолчанию `3`) : Количество входных каналов.

query_bias (`bool`, *необязательный*, по умолчанию `True`) : Добавлять ли смещение (bias) к проекции запроса.

key_bias (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли добавлять смещение (bias) к проекции ключей.

value_bias (`bool`, *необязательный*, по умолчанию `True`) : Добавлять ли смещение (bias) к проекции значения.

proj_bias (`bool`, *необязательный*, по умолчанию `True`) : Добавлять ли смещение (bias) к выходному проецированию.

mlp_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj в слоях MLP.

layerscale_value (`float`, *необязательный*, по умолчанию 1.0) : Начальное значение для layer scale.

drop_path_rate (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент drop path для слияния патчей.

use_gated_mlp (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли свёрточную нейронную сеть SwiGLU.

num_register_tokens (`int`, *необязательный*, по умолчанию 0) : Количество токенов регистра.

pos_embed_shift (`float`, *optional*) : Величина случайного смещения координат позиционных эмбеддингов в диапазоне [-shift, shift], применяется только в режиме обучения, если не равно `None`.

pos_embed_jitter (`float`, *optional*) : Величина случайного смещения координат позиционных эмбеддингов в логарифмически равномерном диапазоне [1/jitter, jitter], применяется только в режиме обучения, если не равно `None`.

pos_embed_rescale (`float`, *optional*, по умолчанию 2.0) : Коэффициент случайного масштабирования координат позиционных эмбеддингов в логарифмически равномерном диапазоне [1/rescale, rescale], применяется только в режиме обучения, если не равно `None`.

reshape_hidden_states (`bool`, *необязательный*, по умолчанию `True`) : Нужно ли изменять размерность скрытых состояний до пространственных измерений при использовании в качестве базовой модели.

use_mask_token (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли токен маски в эмбеддингах (необходимо для предобучения с маскированием изображений).

rms_norm_eps (`float`, *optional*, по умолчанию 1e-6) : Epsilon для слоёв нормализации RMS.

normalize_backbone_outputs (`bool`, *необязательный*, по умолчанию `True`) : Применяется ли RMSNorm к выходным `feature_maps` и `cls_tokens` бэкбона перед их возвратом из прямого прохода. Действует только при использовании модели в качестве бэкбона.

use_qk_norm (`bool`, *необязательный*, по умолчанию `True`) : Применяется ли RMSNorm к запросам и ключам перед RoPE в слоях внимания.

num_key_value_heads_per_layer (`list[int]`, *optional*) : Количество ключевых/значимых головок для каждого слоя трансформера. Если значение слоя равно `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` не задано. Игнорируется, если `num_key_value_heads_per_layer` задано.

num_first_full_attention_layers (`int`, *optional*, по умолчанию 8) : Количество начальных трансформерных слоев, использующих полное многоголовное внимание. Используется только тогда, когда `num_key_value_heads_per_layer` равно `None`.

num_last_full_attention_layers (`int`, *optional*, по умолчанию 8) : Количество последних слоёв трансформера, использующих полное многоголовое внимание. Используется только тогда, когда `num_key_value_heads_per_layer` равно `None`.

semantic_loss_ignore_index (`int`, *optional*, по умолчанию 255) : Индекс метки, который игнорируется при вычислении функции потерь сегментации.

flip_pairs (`list[list[int]]`, *необязательный*) : Пары индексов ключевых точек, зеркально отражённых по горизонтали (например, левое ухо ↔ правое ухо). Каждая пара — это список из двух элементов `[left_index, right_index]`. Используется для горизонтального флипа во время тестирования в задачах оценки позы: передайте эти пары во второй вызов forward, чтобы модель отразила тепловые карты обратно перед их возвратом.

head_config (`Sapiens2HeadConfig`, *необязательный*) : Конфигурация для декодирующей головы. См. [Sapiens2HeadConfig](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2HeadConfig) для доступных опций.

Это класс конфигурации для хранения настроек модели Sapiens2Model. Он используется для создания экземпляра модели Sapiens2 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [facebook/sapiens2-pretrain-0.4b](https://huggingface.co/facebook/sapiens2-pretrain-0.4b)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/sapiens2/configuration_sapiens2.py#L28)

**Параметры:**

upsample_out_channels (`list[int]`, *optional*) : Количество выходных каналов для каждого блока апсемплинга. Первый блок принимает на вход `hidden_size` каналов; последующие блоки используют предыдущий выход.

upsample_kernel_sizes (`list[int]`, *optional*) : Размер ядра для каждого блока апсемплинга. Автоматически заполняется значением `[4, ...]`, если `upsample_out_channels` задано, но это `None`. Должно иметь ту же длину, что и `upsample_out_channels`.

upsample_kernel_size (`int`, по умолчанию 4) : Размер ядра по умолчанию для блоков upsample, если `upsample_kernel_sizes` не задан.

use_pixel_shuffle (`bool`, *необязательный*) : Использует ли головная часть для апскейлинга пиксель-шаффл вместо транспонированных свёрток. Если `None` (по умолчанию), головная часть использует транспонированные свёртки.

conv_out_channels (`list[int]`, *необязательный*) : Количество выходных каналов для свёрточных слоёв уточнения, следующих за блоками апсемплинга.

conv_kernel_sizes (`list[int]`, *optional*) : Размер ядра для каждого слоя уточняющей свёртки. Автоматически заполняется значением `[1, ...]`, если задано `conv_out_channels`, но это `None`. Должно иметь ту же длину, что и `conv_out_channels`.

conv_kernel_size (`int`, по умолчанию 1) : Размер ядра по умолчанию для свёрточных слоёв, если `conv_kernel_sizes` не задан.

scale_conv_out_channels (`list[int]`, *optional*) : Количество выходных каналов для сверточных слоев с шагом 2, используемых для предсказания масштаба фокусного расстояния. Если `None` (по умолчанию), ветвь масштаба не создается.

scale_conv_kernel_sizes (`list[int]`, *optional*) : Размер ядра для каждого слоя свертки масштаба. Автоматически заполняется значением `[1, ...]`, если задано `scale_conv_out_channels`, но это `None`. Должно иметь ту же длину, что и `scale_conv_out_channels`.

scale_conv_kernel_size (`int`, по умолчанию 1) : Размер ядра по умолчанию для слоёв масштабирования (scale conv), если `scale_conv_kernel_sizes` не задан.

scale_final_input_size (`int`, *optional*) : Размер сглаженных признаков, передаваемый в масштабирующий MLP. Если `None` (по умолчанию), он вычисляется автоматически на основе `image_size` и `patch_size` в родительском [Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config).

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/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/sapiens2/image_processing_sapiens2.py#L407)

**Параметры:**

do_convert_rgb (`bool`, *kwargs*, *необязательный*) : Преобразовать ли изображение в RGB.

do_resize (`bool`, *kwargs*, *optional*, по умолчанию `True`) : Нужно ли изменять размер изображения.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, по умолчанию `{'height' : 1024, 'width': 768}`): Описывает максимальные размеры входных данных для модели.

default_to_square (`bool`, *kwargs*, *optional*, по умолчанию `True`) : Использовать ли квадратное изображение по умолчанию при изменении размера, если size является int.

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*, *optional*, по умолчанию `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*, *необязательный*) : Поддерживается только `ChannelDimension.FIRST`. Добавлено для совместимости с медленными процессорами.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *optional*) : Формат размерности каналов для входного изображения. Если не задано, формат размерности каналов определяется по входному изображению. Может быть одним из: - `"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, оно будет установлено в True, если изображения находятся на CPU, и в False в противном случае. Этот выбор основан на эмпирических наблюдениях, подробно описанных здесь: https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *необязательный*) : Количество токенов изображения, используемых для каждого изображения во входных данных. Добавлено для обратной совместимости, но в будущих моделях это значение следует задавать как атрибут процессора.

do_reduce_labels (`bool`, *kwargs*, *optional*, по умолчанию `self.do_reduce_labels`) : Нужно ли уменьшить все значения меток в сегментационных картах на 1. Обычно используется для наборов данных, где 0 обозначает фон, а сам фон не входит в число всех классов набора данных (например, ADE20k). Метка фона будет заменена на 255.

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *optional*, по умолчанию 4) : Коэффициент масштабирования целевого размера тепловой карты относительно размера входных данных модели.

keypoint_heatmap_sigma (`float`, *kwargs*, *optional*, по умолчанию 6.0) : Стандартное отклонение (сигма) для двумерных гауссовых распределений, используемых для генерации тепловых карт.

Создаёт процессор изображений 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/v5.23.0/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`, *необязательный*) : Список или массив ограничивающих прямоугольников для каждого изображения. Каждый прямоугольник должен быть списком из 4 чисел с плавающей точкой, представляющих координаты ограничивающего прямоугольника в формате COCO (top_left_x, top_left_y, width, height). Если указано, каждый вырез с человеком аффинно преобразуется до размера входных данных модели, вместо изменения размера всего изображения.

keypoints (`list[list[list[list[float]]]]`, *optional*) : Список ключевых точек для каждого человека на каждом изображении. Ожидаемый формат — COCO-стиль `[x, y, visibility]`. Значения `x` и `y` должны быть абсолютными координатами пикселей изображения. Формат: `[images -> persons -> keypoints -> [x, y, visibility]]`. Используется для генерации эталонных тепловых карт и весов видимости для дообучения оценки позы.

do_convert_rgb (`bool`, *kwargs*, *необязательный*) : Преобразовать ли изображение в RGB.

do_resize (`bool`, *kwargs*, *необязательный*) : Указывает, нужно ли изменить размер изображения.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Описывает максимальные размеры входных данных для модели.

default_to_square (`bool`, *kwargs*, *необязательный*) : Указывает, следует ли по умолчанию использовать квадратное изображение при изменении размера, если 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*, *необязательный*) : Нужно ли нормализовать изображение.

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*, *необязательный*) : Поддерживается только `ChannelDimension.FIRST`. Добавлено для совместимости с медленными процессорами.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *optional*) : Формат размерности каналов для входного изображения. Если не задано, формат размерности каналов определяется по входному изображению. Может быть одним из: - `"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, оно будет установлено в True, если изображения находятся на CPU, и в False в противном случае. Этот выбор основан на эмпирических наблюдениях, подробно описанных здесь: https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *необязательный*) : Количество токенов изображения, используемых для каждого изображения во входных данных. Добавлено для обратной совместимости, но в будущих моделях это значение следует задавать как атрибут процессора.

do_reduce_labels (`bool`, *kwargs*, *optional*, по умолчанию `self.do_reduce_labels`) : Нужно ли уменьшить все значения меток в сегментационных картах на 1. Обычно используется для наборов данных, где 0 обозначает фон, а сам фон не входит в число всех классов набора данных (например, ADE20k). Метка фона будет заменена на 255.

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *optional*, по умолчанию 4) : Коэффициент масштабирования целевого размера тепловой карты относительно размера входных данных модели.

keypoint_heatmap_sigma (`float`, *kwargs*, *optional*, по умолчанию 6.0) : Стандартное отклонение (сигма) для двумерных гауссовых распределений, используемых для генерации тепловых карт.

**Возвращает:** `~image_processing_base.BatchFeature`

- **data** (`dict`) — Словарь списков/массивов/тензоров, возвращаемый методом __call__ ('pixel_values' и т. д.).
- **tensor_type** (`Union[None, str, TensorType]`, *необязательный*) -- Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.

#### 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/v5.23.0/src/transformers/models/sapiens2/image_processing_sapiens2.py#L891)

**Параметры:**

outputs (`Sapiens2ImageMattingOutput`) : Сырые выходные данные модели.

target_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Запрашиваемое итоговое `(height, width)` для каждого предсказания. Изменяется размер с помощью билинейной интерполяции. Если не задано, предсказания возвращаются в разрешении вывода модели.

backgrounds (`ImageInput`, *необязательный*) : Фоновое изображение(я) для наложения. Может быть одним изображением (применяется ко всем элементам в батче) или списком изображений, по одному на каждый элемент батча. Принимает изображения PIL, массивы numpy или тензоры torch любого типа данных; целочисленные типы (например, uint8) автоматически масштабируются до `[0, 1]`. Если параметр указан, каждый словарь результата получает ключ `"composite"` с изображением после наложения в виде тензора uint8 в диапазоне `[0, 255]`.

**Возвращает:** `list[dict]` длины `batch_size`. Каждый словарь содержит

- `"alpha"` (`torch.Tensor` формы `(1, height, width)`): значения alpha в диапазоне `[0, 1]`.
- `"foreground"` (`torch.Tensor` формы `(3, height, width)`): предумноженный RGB в диапазоне `[0, 1]`.
- `"composite"` (`torch.Tensor` формы `(3, height, width)` или `None`): передний план, наложенный на `backgrounds`, в виде тензора uint8 в диапазоне `[0, 255]`; `None`, если `backgrounds` не задан.

Преобразует выход [Sapiens2ForImageMatting](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/sapiens2/image_processing_sapiens2.py#L818)

**Параметры:**

outputs (`Sapiens2NormalEstimatorOutput`) : Сырые выходные данные модели.

source_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Исходные `(height, width)` каждого изображения до предобработки. Если указано, добавленная при предобработке отсечка удаляется, а предсказания масштабируются обратно до исходного размера изображения (если `target_sizes` не переопределяет итоговый размер).

target_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Запрошенный итоговый размер `(height, width)` для каждого предсказания. Если указан, используется как целевой размер для масштабирования вместо `source_sizes`. Масштабирование выполняется с помощью билинейной интерполяции после L2-нормализации.

do_remove_padding (`bool`, *необязательный*) : Указывает, следует ли обрезать нулевую отступную область, добавленную на этапе предобработки, перед изменением размера. По умолчанию `True`, если задан `source_sizes`, иначе `False`.

**Возвращаемое значение:**

`list[dict[str, torch.Tensor]]` длины `batch_size`. Каждый словарь содержит ключ `"normals"`, соответствующий тензору формы `(3, height, width)` с L2-нормированными единичными векторами в диапазоне `[-1, 1]` для каждого канала (нормали поверхности XYZ).

Преобразует выход [Sapiens2ForNormalEstimation](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/sapiens2/image_processing_sapiens2.py#L854)

**Параметры:**

outputs (`Sapiens2PointmapEstimatorOutput`) : Сырые выходные данные модели.

source_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Исходные `(height, width)` каждого изображения до предобработки. Если указано, добавленная при предобработке отсечка удаляется, а предсказания масштабируются обратно до исходного размера изображения (если `target_sizes` не переопределяет итоговый размер).

target_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Запрашиваемый итоговый `(height, width)` для каждого предсказания. Переопределяет `source_sizes` в качестве целевого размера для масштабирования.

do_remove_padding (`bool`, *необязательный*) : Указывает, следует ли обрезать нулевую отступную область, добавленную на этапе предобработки, перед изменением размера. По умолчанию `True`, если задан `source_sizes`, иначе `False`.

**Возвращаемое значение:**

`list[dict[str, torch.Tensor]]` длины `batch_size`. Каждый словарь содержит ключ `"pointmap"`, который указывает на тензор формы `(3, height, width)` с 3D-координатами XYZ для каждого пикселя в каноническом пространстве камеры, при необходимости разделённые на `outputs.scales` для перевода в метрические координаты.

Преобразует выход [Sapiens2ForPointmapEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation) в тензоры pointmap в пространстве изображения.

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

```python
post_process_pose_estimation(outputs, boxes: list[list[list[float]]], 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/v5.23.0/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`) : Список или массив ограничивающих прямоугольников для каждого изображения в абсолютных пиксельных координатах. Каждый прямоугольник должен быть списком из 4 чисел с плавающей точкой, представляющих координаты ограничивающего прямоугольника в формате COCO (top_left_x, top_left_y, width, height). Должно соответствовать аргументу `boxes`, переданному в `preprocess`.

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` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Исходные `(height, width)` каждого изображения в пикселях. Обязателен, если предоставлено `target_sizes`, так как определяет исходное координатное пространство для масштабирования ключевых точек и ограничивающих прямоугольников.

target_sizes (`torch.Tensor` или `list[tuple[int, int]]` длины `batch_size`, *необязательный*) : Требуемое выходное пространство координат `(height, width)` для каждого изображения. Если указано вместе с `source_sizes`, координаты ключевых точек и ограничивающих прямоугольников масштабируются из исходного пространства в целевое.

**Возвращает:** `list[list[dict]]`

Внешний список итерируется по изображениям, внутренний — по лицам. Каждый словарь содержит:
- `keypoints` (`torch.Tensor` формы `(num_keypoints, 2)`): абсолютные координаты x/y в пространстве исходного изображения или в пространстве целевого изображения, если задан `target_sizes`.
- `scores` (`torch.Tensor` формы `(num_keypoints,)`): уверенность для каждой ключевой точки.
- `labels` (`torch.LongTensor` формы `(num_keypoints,)`): индексы ключевых точек.
- `bbox` (`torch.Tensor` формы `(4,)`): ограничивающая рамка в абсолютном формате (x_min, y_min, x_max, y_max) в том же пространстве координат, что и `keypoints`.

Преобразует выход [Sapiens2ForPoseEstimation](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/sapiens2/image_processing_sapiens2.py#L610)

**Параметры:**

outputs ([Sapiens2ForSemanticSegmentation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation)) : Сырые выходные данные модели.

target_sizes (`list[Tuple]` длины `batch_size`, *необязательный*) : Список кортежей, соответствующих запрашиваемому конечному размеру (высота, ширина) каждого предсказания. Если не задано, предсказания не будут изменены в размере.

return_segmentation_scores (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли возвращать оценки сегментации вместе с картой сегментации. Если `True`, каждый элемент возвращаемого списка представляет собой `SemanticSegmentationPostProcessorOutput` с полями `segmentation` (идентификаторы классов, форма `(height, width)`) и `segmentation_scores` (форма `(num_classes, height, width)`).

**Возвращает:** `list[torch.Tensor]` или `list[SemanticSegmentationPostProcessorOutput]`

Если `return_segmentation_scores=False` (по умолчанию), возвращается список длины `batch_size`, где каждый элемент — карта сегментации формы `(height, width)` с идентификаторами классов. Если `return_segmentation_scores=True`, возвращается список объектов `SemanticSegmentationPostProcessorOutput` с полями `segmentation` (идентификаторы классов, форма `(height, width)`) и `segmentation_scores` (форма `(num_classes, height, width)`). В обоих случаях `(height, width)` соответствует целевому размеру (если указан `target_sizes`).

Преобразует выход [Sapiens2ForSemanticSegmentation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation) в карты семантической сегментации.

## Sapiens2Model[[transformers.Sapiens2Model]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L867)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L880)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) для обработки изображений).

bool_masked_pos (`torch.BoolTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Позиции с булевой маской. Указывает, какие патчи замаскированы (1), а какие нет (0). Актуально только для предварительного обучения.

**Возвращает:** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) или `tuple(torch.Tensor)`

Объект [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод [Sapiens2Model](/docs/transformers/v5.23.0/ru/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)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L929)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Backbone Sapiens2.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L942)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) для обработки изображений).

**Возвращает:** `Sapiens2BackboneOutput` или `tuple(torch.Tensor)`

Объект `Sapiens2BackboneOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2Backbone](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Backbone) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **feature_maps** (`tuple(torch.Tensor)` формы `(batch_size, num_channels, height, width)`) -- Карты признаков на каждом этапе.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)` или `(batch_size, num_channels, height, width)`, в зависимости от базовой модели.

  Скрытые состояния модели на выходе каждого этапа, а также выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1365)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 с головой маттинга сверху (декодер на основе PixelShuffle, предсказывающий преумноженный RGB-фон и альфа-маску).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1372)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/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/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2ForImageMatting](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForImageMatting) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери.
- **alphas** (`torch.Tensor` формы `(batch_size, 1, height, width)`) -- Оцененные значения альфа.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) — Кортеж из `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет такой слой, + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния (также называемые картами признаков) модели на выходе каждого этапа.
- **attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **foregrounds** (`torch.Tensor` формы `(batch_size, 3, height, width)`) -- Предсказания RGB-фона с предварительным умножением в диапазоне `[0, 1]` (с сигмоидной активацией).

Пример:

```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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1215)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 с головкой для оценки нормалей поверх (декодер на основе PixelShuffle, предсказывающий карты нормалей поверхности).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1223)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/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/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2ForNormalEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation) переопределяет специальный метод `__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` (один для вывода эмбеддингов + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния модели на выходе каждого слоя, а также начальные выводы эмбеддингов.
- **attentions** (`tuple(torch.Tensor)`, *optional*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1287)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 с головой pointmap (декодер на основе PixelShuffle, предсказывающий 3D-координаты XYZ для каждого пикселя, плюс необязательная ветка масштаба для нормализации фокусного расстояния).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1299)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) для обработки изображений).

labels (`torch.Tensor` формы `(batch_size, 3, height, width)`, *необязательный*) : Истинная точка карта (ground-truth pointmap) для вычисления функции потерь.

**Возвращает:** `Sapiens2PointmapEstimatorOutput` или `tuple(torch.Tensor)`

Объект `Sapiens2PointmapEstimatorOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2ForPointmapEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря оценки pointmap.
- **pointmaps** (`torch.Tensor` формы `(batch_size, 3, height, width)`) -- Предсказания 3D-координат 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` (один для вывода эмбеддингов + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния модели на выходе каждого слоя, а также начальные выводы эмбеддингов.
- **attentions** (`tuple(torch.Tensor)`, *optional*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1132)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 с головкой для оценки позы (набор предикторов тепловых карт, размещенных поверх выходных скрытых состояний).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1140)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) для обработки изображений).

flip_pairs (`torch.Tensor` формы `(num_pairs, 2)`, *необязательный*) : Пары ключевых точек, которые являются зеркальными отражениями (например, левое ухо — правое ухо), используются для аугментации с горизонтальным переворотом на этапе тестирования. Если этот параметр указан, модель предполагает, что `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)`, *необязательный*) : Веса видимости для каждой ключевой точки. Должны быть расширяемы до формы `labels`.

**Возвращает:** `Sapiens2PoseEstimatorOutput` или `tuple(torch.Tensor)`

Объект `Sapiens2PoseEstimatorOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2ForPoseEstimation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря для оценки позы.
- **карты активаций** (`torch.Tensor` формы `(batch_size, num_keypoints, height, width)`) -- Карты активаций, предсказанные моделью.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) — Кортеж из `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет такой слой, + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния (также называемые картами признаков) модели на выходе каждого этапа.
- **attentions** (`tuple[torch.Tensor, ...]`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1019)

**Параметры:**

config ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Sapiens2 с головой семантической сегментации, например, для ADE20K, CityScapes.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/sapiens2/modeling_sapiens2.py#L1027)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Подробности см. в [Sapiens2ImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [Sapiens2ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) для обработки изображений).

labels (`torch.LongTensor` формы `(batch_size, height, width)`, *необязательный*) : Карты семантической сегментации для вычисления функции потерь. Индексы должны находиться в диапазоне `[0, ..., config.num_labels - 1]`. Если `config.num_labels > 1`, вычисляется функция потерь классификации (Cross-Entropy).

**Возвращает:** [SemanticSegmenterOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) или `tuple(torch.Tensor)`

Объект [SemanticSegmenterOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([Sapiens2Config](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2Config)) и входных данных.

Метод forward класса [Sapiens2ForSemanticSegmentation](/docs/transformers/v5.23.0/ru/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери классификации (или регрессии, если config.num_labels==1).
- **logits** (`torch.Tensor` формы `(batch_size, config.num_labels, logits_height, logits_width)`) — Оценки классификации для каждого пикселя.

  

  Возвращаемые logits не обязательно имеют тот же размер, что и переданные на вход `pixel_values`. Это сделано для того, чтобы избежать двух интерполяций и потери качества, когда пользователю необходимо изменить размер logits до исходного размера изображения на этапе постобработки. Всегда проверяйте форму logits и изменяйте размер по мере необходимости.

  
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, patch_size, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(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])
```